PHP-1327: Add docblocks

src/Collection.php

@@ -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;
     }