(mongodb >=1.0.0)
MongoDB\Driver\Manager::executeCommand — 執行資料庫命令
$db, MongoDB\Driver\Command $command, array|MongoDB\Driver\ReadPreference|null $options = null): MongoDB\Driver\Cursor根據 "readPreference" 選項選取伺服器，並在該伺服器上執行命令。
此方法不會對命令套用任何特殊邏輯。"readPreference"、"readConcern" 和 "writeConcern" 選項的預設值將從活動交易（由 "session" 選項指示）推斷。如果沒有活動交易，則會使用主要讀取偏好來選取伺服器。
預設值不會從連線 URI 推斷。因此，如果可能，建議使用者使用特定的讀取和/或寫入命令方法。
db (string)要在其上執行命令的資料庫名稱。
command (MongoDB\Driver\Command)要執行的命令。
options
| 選項 | 類型 | 說明 |
|---|---|---|
| readConcern | MongoDB\Driver\ReadConcern |
要套用至作業的讀取關注。 此選項在 MongoDB 3.2+ 中可用，如果為較舊的伺服器版本指定，將在執行時產生例外。 |
| readPreference | MongoDB\Driver\ReadPreference |
用於選取作業伺服器的讀取偏好。 |
| session | MongoDB\Driver\Session |
要與作業關聯的會話。 |
| writeConcern | MongoDB\Driver\WriteConcern |
要套用至作業的寫入關注。 |
如果您正在使用具有進行中交易的 "session"，則無法指定 "readConcern" 或 "writeConcern" 選項。這將導致擲回 MongoDB\Driver\Exception\InvalidArgumentException。相反地，您應該在您使用 MongoDB\Driver\Session::startTransaction() 建立交易時設定這兩個選項。
成功時回傳 MongoDB\Driver\Cursor。
"session" 選項與相關交易結合使用 "readConcern" 或 "writeConcern" 選項，則會擲回 MongoDB\Driver\Exception\InvalidArgumentException。"session" 選項與未確認的寫入關注結合使用，則會擲回 MongoDB\Driver\Exception\InvalidArgumentException。
| 版本 | 說明 |
|---|---|
| PECL mongodb 1.4.4 |
如果 "session" 選項與未確認的寫入關注結合使用，則會擲回 MongoDB\Driver\Exception\InvalidArgumentException。 |
| PECL mongodb 1.4.0 | 第三個參數現在是 options 陣列。為了向後相容，此參數仍然接受 MongoDB\Driver\ReadPreference 物件。 |
範例 1 MongoDB\Driver\Manager::executeCommand()，使用回傳單一結果文件的命令
<?php
$manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017');
$command = new MongoDB\Driver\Command(['ping' => 1]);
try {
$cursor = $manager->executeCommand('admin', $command);
} catch(MongoDB\Driver\Exception $e) {
echo $e->getMessage(), "\n";
exit;
}
/* ping 命令回傳單一結果文件，因此我們需要存取
* cursor 中的第一個結果。 */
$response = $cursor->toArray()[0];
var_dump($response);
?>以上範例將輸出
array(1) {
["ok"]=>
float(1)
}
範例 2 MongoDB\Driver\Manager::executeCommand()，使用回傳 cursor 的命令
<?php
$manager = new MongoDB\Driver\Manager("mongodb://127.0.0.1:27017");
$bulk = new MongoDB\Driver\BulkWrite;
$bulk->insert(['x' => 1, 'y' => 'foo']);
$bulk->insert(['x' => 2, 'y' => 'bar']);
$bulk->insert(['x' => 3, 'y' => 'bar']);
$manager->executeBulkWrite('db.collection', $bulk);
$command = new MongoDB\Driver\Command([
'aggregate' => 'collection',
'pipeline' => [
['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
],
'cursor' => new stdClass,
]);
$cursor = $manager->executeCommand('db', $command);
/* The aggregate command can optionally return its results in a cursor instead
* of a single result document. In this case, we can iterate on the cursor
* directly to access those results. */
foreach ($cursor as $document) {
var_dump($document);
}
?>以上範例將輸出
object(stdClass)#6 (2) {
["_id"]=>
string(3) "bar"
["sum"]=>
int(10)
}
object(stdClass)#7 (2) {
["_id"]=>
string(3) "foo"
["sum"]=>
int(2)
}
範例 #3 限制命令的執行時間
可以透過在 MongoDB\Driver\Command 文件中指定 "maxTimeMS" 的值來限制命令的執行時間。請注意，此時間限制是在伺服器端強制執行的，並未將網路延遲納入考量。有關更多資訊，請參閱 MongoDB 手冊中的» 終止執行中的操作。
<?php
$manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017');
$command = new MongoDB\Driver\Command([
'count' => 'collection',
'query' => ['x' => ['$gt' => 1]],
'maxTimeMS' => 1000,
]);
$cursor = $manager->executeCommand('db', $command);
var_dump($cursor->toArray()[0]);
?>如果命令在伺服器上執行一秒後仍未完成，將會拋出 MongoDB\Driver\Exception\ExecutionTimeoutException 異常。
注意: 如果使用次要的
readPreference，呼叫者有責任確保command可以在次要節點上執行。驅動程式不會執行任何驗證。
注意: 這個方法預設不會使用 MongoDB 連線 URI 中的讀取偏好設定。需要此行為的應用程式應考慮使用 MongoDB\Driver\Manager::executeReadCommand()。