Skip to content

M
mongo-php-library
Commit 906c2ab1 authored by Hannes Magnusson's avatar Hannes Magnusson
Browse files
Options

PHP-1327: Add docblocks

parent 5a3e0dec
Hide whitespace changes
Inline Side-by-side
Showing with 388 additions and 71 deletions
src/Collection.php
View file @ 906c2ab1
......@@ -29,24 +29,46 @@ class Collection {
const FIND_ONE_AND_RETURN_AFTER = 0x02;
protected $manager;
protected $rp;
protected $wc;
protected $ns;
protected $wc;
protected $rp;
protected $dbname;
protected $collname;
/* }}} */
function __construct(Manager $manager, $ns, WriteConcern $wc = null, ReadPreference $rp = null) { /* {{{ */
/**
* Constructs new MongoDB\Collection instance
*
* This is the suggested CRUD interface when using phongo.
* It implements the MongoDB CRUD specification which is an interface all MongoDB
* supported drivers follow.
*
* @param MongoDB\Manager $manager The phongo Manager instance
* @param MongoDB\WriteConcern $wc The WriteConcern to apply to writes
* @param MongoDB\ReadPreference $rp The ReadPreferences to apply to reads
*/
function __construct(Manager $manager, $ns, WriteConcern $wc = null, ReadPreference $rp = null) {
$this->manager = $manager;
$this->ns = $ns;
$this->wc = $wc;
$this->rp = $rp;
list($this->dbname, $this->collname) = explode(".", $ns, 2);
} /* }}} */
}
function find(array $filter = array(), array $options = array()) { /* {{{ {{{ */
/**
* Performs a find (query) on the collection
*
* @see http://docs.mongodb.org/manual/core/read-operations-introduction/
* @see MongoDB\Collection::getFindOptions() for supported $options
*
* @param array $filter The find query to execute
* @param array $options Additional options
* @return MongoDB\QueryResult
*/
function find(array $filter = array(), array $options = array()) {
$options = array_merge($this->getFindOptions(), $options);
$query = $this->_buildQuery($filter, $options);
......@@ -54,8 +76,14 @@ class Collection {
$cursor = $this->manager->executeQuery($this->ns, $query, $this->rp);
return $cursor;
} /* }}} */
function getFindOptions() { /* {{{ */
}
/**
* Retrieves all find options with their default values.
*
* @return array of MongoDB\Collection::find() options
*/
function getFindOptions() {
return array(
/**
* Get partial results from a mongos if some shards are down (instead of throwing an error).
......@@ -123,6 +151,7 @@ class Collection {
* Internal replication use only - driver should not set
*
* @see http://docs.mongodb.org/meta-driver/latest/legacy/mongodb-wire-protocol/#op-query
* @internal
*/
"oplogReplay" => false,
......@@ -148,8 +177,17 @@ class Collection {
*/
"sort" => array(),
);
} /* }}} */
protected function _opQueryFlags($options) { /* {{{ */
}
/**
* Constructs the Query Wire Protocol field 'flags' based on $options
* provided to other helpers
*
* @param array $options
* @return integer OP_QUERY Wire Protocol flags
* @internal
*/
final protected function _opQueryFlags($options) {
$flags = 0;
$flags |= $options["allowPartialResults"] ? self::QUERY_FLAG_PARTIAL : 0;
......@@ -158,8 +196,17 @@ class Collection {
$flags |= $options["noCursorTimeout"] ? self::QUERY_FLAG_NO_CURSOR_TIMEOUT : 0;
return $flags;
} /* }}} */
protected function _buildQuery($filter, $options) { /* {{{ */
}
/**
* Helper to build a MongoDB\Query object
*
* @param array $filter the query document
* @param array $options query/protocol options
* @return MongoDB\Query
* @internal
*/
final protected function _buildQuery($filter, $options) {
if ($options["comment"]) {
$options["modifiers"]['$comment'] = $options["comment"];
}
......@@ -177,23 +224,80 @@ class Collection {
$query = new Query($filter, $options);
return $query;
} /* }}} */
/* }}} */
/* {{{ writes */
function getWriteOptions() { /* {{{ */
}
/**
* Retrieves all Write options with their default values.
*
* @return array of available Write options
*/
function getWriteOptions() {
return array(
"ordered" => false,
"upsert" => false,
"limit" => 1,
);
} /* }}} */
function getBulkOptions() { /* {{{ */
}
/**
* Retrieves all Bulk Write options with their default values.
*
* @return array of available Bulk Write options
*/
function getBulkOptions() {
return array(
"ordered" => false,
);
} /* }}} */
}
function bulkWrite(array $bulk, array $options = array()) { /* {{{ */
/**
* Adds a full set of write operations into a batch and executes it
*
* The syntax of the $bulk array is:
* $bulk = [
* [
* 'METHOD' => [
* $document,
* $extraArgument1,
* $extraArgument2,
* ],
* ],
* [
* 'METHOD' => [
* $document,
* $extraArgument1,
* $extraArgument2,
* ],
* ],
* ]
*
*
* Where METHOD is one of
* - 'insertOne'
* Supports no $extraArgument
* - 'updateMany'
* Requires $extraArgument1, same as $update for MongoDB\Collection\updateMany()
* Optional $extraArgument2, same as $options for MongoDB\Collection\updateMany()
* - 'updateOne'
* Requires $extraArgument1, same as $update for MongoDB\Collection\updateOne()
* Optional $extraArgument2, same as $options for MongoDB\Collection\updateOne()
* - 'replaceOne'
* Requires $extraArgument1, same as $update for MongoDB\Collection\replaceOne()
* Optional $extraArgument2, same as $options for MongoDB\Collection\replaceOne()
* - 'deleteOne'
* Supports no $extraArgument
* - 'deleteMany'
* Supports no $extraArgument
*
* @example Collection-bulkWrite.php Using Collection::bulkWrite()
*
* @see MongoDB\Collection::getBulkOptions() for supported $options
*
* @param array $bulk Array of operations
* @param array $options Additional options
* @return MongoDB\WriteResult
*/
function bulkWrite(array $bulk, array $options = array()) {
$options = array_merge($this->getBulkOptions(), $options);
$batch = new WriteBatch($options["ordered"]);
......@@ -258,67 +362,153 @@ class Collection {
}
}
return $this->manager->executeWriteBatch($this->ns, $batch, $this->wc);
} /* }}} */
}
function insertOne(array $filter) { /* {{{ */
/**
* Inserts the provided document
*
* @see http://docs.mongodb.org/manual/reference/command/insert/
* @see MongoDB\Collection::getWriteOptions() for supported $options
*
* @param array $document The document to insert
* @param array $options Additional options
* @return MongoDB\InsertResult
*/
function insertOne(array $document) {
$options = array_merge($this->getWriteOptions());
$batch = new WriteBatch($options["ordered"]);
$id = $batch->insert($filter);
$id = $batch->insert($document);
$wr = $this->manager->executeWriteBatch($this->ns, $batch, $this->wc);
return new InsertResult($wr, $id);
} /* }}} */
}
protected function _delete($filter, $limit = 1) { /* {{{ */
/**
* Internal helper for delete one/many documents
* @internal
*/
final protected function _delete($filter, $limit = 1) {
$options = array_merge($this->getWriteOptions(), array("limit" => $limit));
$batch = new WriteBatch($options["ordered"]);
$batch->delete($filter, $options);
return $this->manager->executeWriteBatch($this->ns, $batch, $this->wc);
} /* }}} */
function deleteOne(array $filter) { /* {{{ */
}
/**
* Deletes a document matching the $filter criteria.
* NOTE: Will delete at most ONE document matching $filter
*
* @see http://docs.mongodb.org/manual/reference/command/delete/
*
* @param array $filter The $filter criteria to delete
* @return MongoDB\DeleteResult
*/
function deleteOne(array $filter) {
$wr = $this->_delete($filter);
return new DeleteResult($wr);
} /* }}} */
function deleteMany(array $filter) { /* {{{ */
}
/**
* Deletes a document matching the $filter criteria.
* NOTE: Will delete ALL documents matching $filter
*
* @see http://docs.mongodb.org/manual/reference/command/delete/
*
* @param array $filter The $filter criteria to delete
* @return MongoDB\DeleteResult
*/
function deleteMany(array $filter) {
$wr = $this->_delete($filter, 0);
return new DeleteResult($wr);
} /* }}} */
}
protected function _update($filter, $update, $options) { /* {{{ */
/**
* Internal helper for replacing/updating one/many documents
* @internal
*/
protected function _update($filter, $update, $options) {
$options = array_merge($this->getWriteOptions(), $options);
$batch = new WriteBatch($options["ordered"]);
$batch->update($filter, $update, $options);
return $this->manager->executeWriteBatch($this->ns, $batch, $this->wc);
} /* }}} */
function replaceOne(array $filter, array $update, array $options = array()) { /* {{{ */
}
/**
* Replace one document
*
* @see http://docs.mongodb.org/manual/reference/command/update/
* @see MongoDB\Collection::getWriteOptions() for supported $options
*
* @param array $filter The document to be replaced
* @param array $update The document to replace with
* @param array $options Additional options
* @return MongoDB\UpdateResult
*/
function replaceOne(array $filter, array $update, array $options = array()) {
if (key($update)[0] == '$') {
throw new \InvalidArgumentException("First key in \$update must NOT be a \$operator");
}
$wr = $this->_update($filter, $update, $options);
return new UpdateResult($wr);
} /* }}} */
function updateOne(array $filter, array $update, array $options = array()) { /* {{{ */
}
/**
* Update one document
* NOTE: Will update at most ONE document matching $filter
*
* @see http://docs.mongodb.org/manual/reference/command/update/
* @see MongoDB\Collection::getWriteOptions() for supported $options
*
* @param array $filter The document to be replaced
* @param array $update An array of update operators to apply to the document
* @param array $options Additional options
* @return MongoDB\UpdateResult
*/
function updateOne(array $filter, array $update, array $options = array()) {
if (key($update)[0] != '$') {
throw new \InvalidArgumentException("First key in \$update must be a \$operator");
}
$wr = $this->_update($filter, $update, $options);
return new UpdateResult($wr);
} /* }}} */
function updateMany(array $filter, $update, array $options = array()) { /* {{{ */
}
/**
* Update one document
* NOTE: Will update ALL documents matching $filter
*
* @see http://docs.mongodb.org/manual/reference/command/update/
* @see MongoDB\Collection::getWriteOptions() for supported $options
*
* @param array $filter The document to be replaced
* @param array $update An array of update operators to apply to the document
* @param array $options Additional options
* @return MongoDB\UpdateResult
*/
function updateMany(array $filter, $update, array $options = array()) {
$wr = $this->_update($filter, $update, $options + array("limit" => 0));
return new UpdateResult($wr);
} /* }}} */
/* }}} */
}
function count(array $filter = array(), array $options = array()) { /* {{{ */
/**
* Counts all documents matching $filter
* If no $filter provided, returns the numbers of documents in the collection
*
* @see http://docs.mongodb.org/manual/reference/command/count/
* @see MongoDB\Collection::getCountOptions() for supported $options
*
* @param array $filter The find query to execute
* @param array $options Additional options
* @return integer
*/
function count(array $filter = array(), array $options = array()) {
$options = array_merge($this->getCountOptions(), $options);
$cmd = array(
"count" => $this->collname,
......@@ -330,8 +520,14 @@ class Collection {
return $doc["n"];
}
throw $this->_generateCommandException($doc);
} /* }}} */
function getCountOptions() { /* {{{ */
}
/**
* Retrieves all count options with their default values.
*
* @return array of MongoDB\Collection::count() options
*/
function getCountOptions() {
return array(
/**
* The index to use.
......@@ -361,9 +557,20 @@ class Collection {
*/
"skip" => 0,
);
} /* }}} */
}
function distinct($fieldName, array $filter = array(), array $options = array()) { /* {{{ */
/**
* Finds the distinct values for a specified field across the collection
*
* @see http://docs.mongodb.org/manual/reference/command/distinct/
* @see MongoDB\Collection::getDistinctOptions() for supported $options
*
* @param string $fieldName The fieldname to use
* @param array $filter The find query to execute
* @param array $options Additional options
* @return integer
*/
function distinct($fieldName, array $filter = array(), array $options = array()) {
$options = array_merge($this->getDistinctOptions(), $options);
$cmd = array(
"distinct" => $this->collname,
......@@ -376,8 +583,14 @@ class Collection {
return $doc["values"];
}
throw $this->_generateCommandException($doc);
} /* }}} */
function getDistinctOptions() { /* {{{ */
}
/**
* Retrieves all distinct options with their default values.
*
* @return array of MongoDB\Collection::distinct() options
*/
function getDistinctOptions() {
return array(
/**
* The maximum amount of time to allow the query to run. The default is infinite.
......@@ -386,9 +599,23 @@ class Collection {
*/
"maxTimeMS" => 0,
);
} /* }}} */
}
function aggregate(array $pipeline, array $options = array()) { /* {{{ */
/**
* Runs an aggregation framework pipeline
* NOTE: The return value of this method depends on your MongoDB server version
* and possibly options.
* MongoDB 2.6 (and later) will return a MongoDB\QueryCursor by default
* MongoDB pre 2.6 will return a ArrayIterator
*
* @see http://docs.mongodb.org/manual/reference/command/aggregate/
* @see MongoDB\Collection::getAggregateOptions() for supported $options
*
* @param array $pipeline The pipeline to execute
* @param array $options Additional options
* @return Iteratable
*/
function aggregate(array $pipeline, array $options = array()) {
$options = array_merge($this->getAggregateOptions(), $options);
$options = $this->_massageAggregateOptions($options);
$cmd = array(
......@@ -407,8 +634,14 @@ class Collection {
}
throw $this->_generateCommandException($doc);
} /* }}} */
function getAggregateOptions() { /* {{{ */
}
/**
* Retrieves all aggregate options with their default values.
*
* @return array of MongoDB\Collection::aggregate() options
*/
function getAggregateOptions() {
$opts = array(
/**
* Enables writing to temporary files. When set to true, aggregation stages
......@@ -449,18 +682,32 @@ class Collection {
/* FIXME: Add a version check for useCursor */
return $opts;
} /* }}} */
protected function _massageAggregateOptions($options) { /* {{{ */
}
/**
* Internal helper for massaging aggregate options
* @internal
*/
protected function _massageAggregateOptions($options) {
if ($options["useCursor"]) {
$options["cursor"] = array("batchSize" => $options["batchSize"]);
}
unset($options["useCursor"], $options["batchSize"]);
return $options;
} /* }}} */
}
/* {{{ findAndModify */
function findOneAndDelete(array $filter, array $options = array()) { /* {{{ */
/**
* Finds a single document and deletes it, returning the original.
*
* @see http://docs.mongodb.org/manual/reference/command/findAndModify/
* @see MongoDB\Collection::getFindOneAndDelete() for supported $options
*
* @param array $filter The $filter criteria to search for
* @param array $options Additional options
* @return array The original document
*/
function findOneAndDelete(array $filter, array $options = array()) {
$options = array_merge($this->getFindOneAndDeleteOptions(), $options);
$options = $this->_massageFindAndModifyOptions($options);
$cmd = array(
......@@ -474,8 +721,14 @@ class Collection {
}
throw $this->_generateCommandException($doc);
} /* }}} */
function getFindOneAndDeleteOptions() { /* {{{ */
}
/**
* Retrieves all findOneDelete options with their default values.
*
* @return array of MongoDB\Collection::findOneAndDelete() options
*/
function getFindOneAndDeleteOptions() {
return array(
/**
......@@ -499,9 +752,23 @@ class Collection {
*/
"sort" => array(),
);
} /* }}} */
}
function findOneAndReplace(array $filter, array $replacement, array $options = array()) { /* {{{ */
/**
* Finds a single document and replaces it, returning either the original or the replaced document
* By default, returns the original document.
* To return the new document set:
* $options = array("returnDocument" => MongoDB\Collection::FIND_ONE_AND_RETURN_AFTER);
*
* @see http://docs.mongodb.org/manual/reference/command/findAndModify/
* @see MongoDB\Collection::getFindOneAndReplace() for supported $options
*
* @param array $filter The $filter criteria to search for
* @param array $replacement The document to replace with
* @param array $options Additional options
* @return array
*/
function findOneAndReplace(array $filter, array $replacement, array $options = array()) {
if (key($replacement)[0] == '$') {
throw new \InvalidArgumentException("First key in \$replacement must NOT be a \$operator");
}
......@@ -520,8 +787,14 @@ class Collection {
}
throw $this->_generateCommandException($doc);
} /* }}} */
function getFindOneAndReplaceOptions() { /* {{{ */
}
/**
* Retrieves all findOneAndReplace options with their default values.
*
* @return array of MongoDB\Collection::findOneAndReplace() options
*/
function getFindOneAndReplaceOptions() {
return array(
/**
......@@ -562,9 +835,24 @@ class Collection {
"upsert" => false,
);
} /* }}} */
}
function findOneAndUpdate(array $filter, array $update, array $options = array()) { /* {{{ */
/**
* Finds a single document and updates it, returning either the original or the updated document
* By default, returns the original document.
* To return the new document set:
* $options = array("returnDocument" => MongoDB\Collection::FIND_ONE_AND_RETURN_AFTER);
*
*
* @see http://docs.mongodb.org/manual/reference/command/findAndModify/
* @see MongoDB\Collection::getFindOneAndUpdate() for supported $options
*
* @param array $filter The $filter criteria to search for
* @param array $update An array of update operators to apply to the document
* @param array $options Additional options
* @return array
*/
function findOneAndUpdate(array $filter, array $update, array $options = array()) {
if (key($update)[0] != '$') {
throw new \InvalidArgumentException("First key in \$update must be a \$operator");
}
......@@ -583,8 +871,14 @@ class Collection {
}
throw $this->_generateCommandException($doc);
} /* }}} */
function getFindOneAndUpdateOptions() { /* {{{ */
}
/**
* Retrieves all findOneAndUpdate options with their default values.
*
* @return array of MongoDB\Collection::findOneAndUpdate() options
*/
function getFindOneAndUpdateOptions() {
return array(
/**
......@@ -624,9 +918,13 @@ class Collection {
"upsert" => false,
);
} /* }}} */
}
protected function _massageFindAndModifyOptions($options, $update = array()) { /* {{{ */
/**
* Internal helper for massaging findandmodify options
* @internal
*/
final protected function _massageFindAndModifyOptions($options, $update = array()) {
$ret = array(
"sort" => $options["sort"],
"new" => isset($options["returnDocument"]) ? $options["returnDocument"] == self::FIND_ONE_AND_RETURN_AFTER : false,
......@@ -640,25 +938,44 @@ class Collection {
}
return $ret;
} /* }}} */
/* }}} */
}
protected function _generateCommandException($doc) { /* {{{ */
/**
* Internal helper for throwing an exception with error message
* @internal
*/
final protected function _generateCommandException($doc) {
if ($doc["errmsg"]) {
return new Exception($doc["errmsg"]);
}
var_dump($doc);
return new \Exception("FIXME: Unknown error");
} /* }}} */
protected function _runCommand($dbname, array $cmd, ReadPreference $rp = null) { /* {{{ */
}
/**
* Internal helper for running a command
* @internal
*/
final protected function _runCommand($dbname, array $cmd, ReadPreference $rp = null) {
//var_dump(\BSON\toJSON(\BSON\fromArray($cmd)));
$command = new Command($cmd);
return $this->manager->executeCommand($dbname, $command, $rp);
}
/**
* Returns the CollectionName this object operates on
*
* @return string
*/
function getCollectionName() {
return $this->collname;
}
/**
* Returns the DatabaseName this object operates on
*
* @return string
*/
function getDatabaseName() {
return $this->dbname;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment