From 0137d3c264ab0c1ce34bfbd9610319ed61326a3f Mon Sep 17 00:00:00 2001 From: Kristina Chodorow Date: Mon, 1 Feb 2010 15:24:10 +0000 Subject: [PATCH] much nicer class organization git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@294311 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mongo/book.xml | 46 +---- reference/mongo/core.xml | 18 ++ reference/mongo/datatypes.xml | 312 ------------------------------ reference/mongo/exceptions.xml | 14 ++ reference/mongo/functions.xml | 10 + reference/mongo/gridfs.xml | 12 ++ reference/mongo/manual.xml | 1 - reference/mongo/types.xml | 336 +++++++++++++++++++++++++++++++++ 8 files changed, 395 insertions(+), 354 deletions(-) create mode 100644 reference/mongo/core.xml create mode 100644 reference/mongo/exceptions.xml create mode 100644 reference/mongo/functions.xml create mode 100644 reference/mongo/gridfs.xml create mode 100644 reference/mongo/types.xml diff --git a/reference/mongo/book.xml b/reference/mongo/book.xml index b3da9abc6d..7ecbefc965 100644 --- a/reference/mongo/book.xml +++ b/reference/mongo/book.xml @@ -6,48 +6,12 @@ Mongo &reference.mongo.manual; + &reference.mongo.core; + &reference.mongo.types; + &reference.mongo.gridfs; + &reference.mongo.functions; + &reference.mongo.exceptions; - - Core Classes - &reference.mongo.mongo; - &reference.mongo.mongodb; - &reference.mongo.mongocollection; - &reference.mongo.mongocursor; - - - - Types - &reference.mongo.mongoid; - &reference.mongo.mongocode; - &reference.mongo.mongodate; - &reference.mongo.mongoregex; - &reference.mongo.mongobindata; - &reference.mongo.mongodbref; - &reference.mongo.mongominkey; - &reference.mongo.mongomaxkey; - &reference.mongo.mongotimestamp; - - - - GridFS - &reference.mongo.mongogridfs; - &reference.mongo.mongogridfsfile; - &reference.mongo.mongogridfscursor; - - - - Functions - &reference.mongo.reference; - - - - Exceptions - &reference.mongo.mongoexception; - &reference.mongo.mongocursorexception; - &reference.mongo.mongocursortimeoutexception; - &reference.mongo.mongoconnectionexception; - &reference.mongo.mongogridfsexception; - + + + + Core Classes + + + The core classes are the most important part of the driver. + + + + &reference.mongo.mongo; + &reference.mongo.mongodb; + &reference.mongo.mongocollection; + &reference.mongo.mongocursor; + + diff --git a/reference/mongo/datatypes.xml b/reference/mongo/datatypes.xml index fc6d8bf741..b7d715425e 100644 --- a/reference/mongo/datatypes.xml +++ b/reference/mongo/datatypes.xml @@ -3,318 +3,6 @@
Data Types - - MongoDB allows programmers to save and query for data expressed in all of the - basic PHP types, compound types (arrays, associative arrays, and objects), and - a half-dozen classes provided by the MongoDB PHP driver (for regular - expressions, dates, and other specialized applications). - - - MongoDB uses a storage format called "BSON," Binary Serializable Object - Notation, which is similar to JSON but more compact and rich in types. Listed - below is the exact byte size of each type (or information required to compute - its size, in the case of variable-length types). Keep in mind that these - sizes do not include field names. The size of an object can be manually - computed, but it may be easier for programmers to call the - bson_encode function and take the length of the resulting - string. - - - An example of manually computing BSON size for saving the object - array("x" => null, "y" => 40): - - - - - -
- Simple Types - - The built-in types are: - - - - - - - Type - Description - Size in MongoDB (bytes) - - - - - &null; - Fairly self-explanatory. - 0 - - - boolean - &true; and &false; - 1 - - - int - Integer values. - 4 - - - float - Double values. - 8 - - - string - Strings of UTF-8 characters. - string length + 1 - - - - - -
- -
- Arrays and Objects - - - Arrays and objects can also be saved to the database. An array with ascending - numeric keys will be saved as a an array, anything else will be saved as an - object. - - - - insert(array("scores" => $scores); - -// $scores will be saved as an object -$scores = array("quiz1" => 98, "midterm" => 100, "quiz2" => 73, "final" => 85); -$collection->insert(array("scores" => $scores); - -?> -]]> - - - - If you query for these objects using the database shell, they will look like: - - db.students.find() -{ "_id" : ObjectId("4b06beada9ad6390dab17c43"), "scores" : [ 98, 100, 73, 85 ] } -{ "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "scores" : { "quiz1" : 98, "midterm" : 100, "quiz2" : 73, "final" : 85 } } -]]> - - - - - The database can also save arbitrary PHP objects (although they will be - returned as associative arrays). The fields are used for the key/value - pairs. For example, a blog post might look like: - -author = $author; - $this->content = $content; - $this->date = new MongoDate(); - } - - public function setTitle($title) { - $this->title = $title; - } -} - -// create a simple blog post and insert it into the database -$post1 = new Post("Adam", "This is a blog post"); - -$blog->insert($post1); - - -// there is nothing restricting the type of the "author" field, so we can make -// it a nested object -$author = array("name" => "Fred", "karma" => 42); -$post2 = new Post($author, "This is another blog post."); - -// we create an extra field by setting the title -$post2->setTitle("Second Post"); - -$blog->insert($post2); - -?> -]]> - - - - - From the database shell, this will look something like: - - db.blog.find() -{ "_id" : ObjectId("4b06c263edb87a281e09dad8"), "author" : "Adam", "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:22:59 GMT-0500 (EST)" } -{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "author" : { "name" : "Fred", "karma" : 42 }, "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:23:30 GMT-0500 (EST)", "title" : "Second Post" } -]]> - - -
- -
- MongoDB Types - - - The Mongo PHP driver also defines a few new types to use with the database. - See class documentation for details and examples. - - - - - - - Type - Description - Size in MongoDB (bytes) - - - - - MongoBinData - Binary data. - Number of bytes in binary data + 5 - - - MongoCode - JavaScript code. - String length of code + object size of scope. - - - MongoDate - Dates and times. Stored as milliseconds since the epoch. - 8 - - - MongoId - Unique document id: - - - 4 bytes of timestamp - - No two records can have the same id if they were inserted at different - times. - - - - 3 bytes machine id - - No two records can have the same id if they were inserted on different - machines - - - - 2 bytes thread id - - No two records can have the same id if they were inserted by different - threads running on the same machine. - - - - 3 bytes incrementing value - - Each time an id is created, a global counter is incremented and used - as the increment value of the next id. - - - - Thus, no two records can have the same id unless a single process on a - single machine managed to insert 256^3 (over 16 million) documents in - one second, overflowing the increment field. - - 12 - - - MongoMinKey - Always smaller than any other value. - String length of code + object size of scope. - - - MongoMaxKey - JavaScript code. - Always larger than any other value. - - - MongoRegex - Regular expressions. - - Number of characters in regular expression + number of flags - - - - MongoTimestamp - Sharding timestamp - 8 - - - - - -
- -
- Unsupported Types - - Types supported by Mongo, but not the PHP driver: - - - - - - Type - Description - Size in MongoDB (bytes) - - - - - long - - As PHP does not support 8 byte integers, longs fetched from the database - are converted to doubles. Integers will always be saved to the database - as 4 byte ints (even on machines that support 8 byte ints) and doubles - will be saved as 8 bytes doubles, so there is no way to save a long to - the database with the PHP driver. - - 8 - - - - - -
diff --git a/reference/mongo/exceptions.xml b/reference/mongo/exceptions.xml new file mode 100644 index 0000000000..4798a79ddf --- /dev/null +++ b/reference/mongo/exceptions.xml @@ -0,0 +1,14 @@ + + + + + + Exceptions + + &reference.mongo.mongoexception; + &reference.mongo.mongocursorexception; + &reference.mongo.mongocursortimeoutexception; + &reference.mongo.mongoconnectionexception; + &reference.mongo.mongogridfsexception; + + diff --git a/reference/mongo/functions.xml b/reference/mongo/functions.xml new file mode 100644 index 0000000000..40dbec35ca --- /dev/null +++ b/reference/mongo/functions.xml @@ -0,0 +1,10 @@ + + + + + + Functions + + &reference.mongo.reference; + + diff --git a/reference/mongo/gridfs.xml b/reference/mongo/gridfs.xml new file mode 100644 index 0000000000..9397d5114b --- /dev/null +++ b/reference/mongo/gridfs.xml @@ -0,0 +1,12 @@ + + + + + + GridFS Classes + + &reference.mongo.mongogridfs; + &reference.mongo.mongogridfsfile; + &reference.mongo.mongogridfscursor; + + diff --git a/reference/mongo/manual.xml b/reference/mongo/manual.xml index bc7b27286e..0134da01bf 100644 --- a/reference/mongo/manual.xml +++ b/reference/mongo/manual.xml @@ -8,7 +8,6 @@ &reference.mongo.ini; &reference.mongo.tutorial; &reference.mongo.examples; - &reference.mongo.datatypes; &reference.mongo.queries; &reference.mongo.updates; &reference.mongo.trouble; diff --git a/reference/mongo/types.xml b/reference/mongo/types.xml new file mode 100644 index 0000000000..1fe356d330 --- /dev/null +++ b/reference/mongo/types.xml @@ -0,0 +1,336 @@ + + + + + + Types + + + +
+ + MongoDB allows programmers to save and query for data expressed in all of the + basic PHP types, compound types (arrays, associative arrays, and objects), and + a half-dozen classes provided by the MongoDB PHP driver (for regular + expressions, dates, and other specialized applications). + + + MongoDB uses a storage format called "BSON," Binary Serializable Object + Notation, which is similar to JSON but more compact and rich in types. Listed + below is the exact byte size of each type (or information required to compute + its size, in the case of variable-length types). Keep in mind that these + sizes do not include field names. The size of an object can be manually + computed, but it may be easier for programmers to call the + bson_encode function and take the length of the resulting + string. + + + An example of manually computing BSON size for saving the object + array("x" => null, "y" => 40): + + + + +
+ +
+ Simple Types + + The built-in types are: + + + + + + + Type + Description + Size in MongoDB (bytes) + + + + + &null; + Fairly self-explanatory. + 0 + + + boolean + &true; and &false; + 1 + + + int + Integer values. + 4 + + + float + Double values. + 8 + + + string + Strings of UTF-8 characters. + string length + 1 + + + + + +
+ +
+ Arrays and Objects + + + Arrays and objects can also be saved to the database. An array with ascending + numeric keys will be saved as a an array, anything else will be saved as an + object. + + + + insert(array("scores" => $scores); + +// $scores will be saved as an object +$scores = array("quiz1" => 98, "midterm" => 100, "quiz2" => 73, "final" => 85); +$collection->insert(array("scores" => $scores); + +?> +]]> + + + + If you query for these objects using the database shell, they will look like: + + db.students.find() +{ "_id" : ObjectId("4b06beada9ad6390dab17c43"), "scores" : [ 98, 100, 73, 85 ] } +{ "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "scores" : { "quiz1" : 98, "midterm" : 100, "quiz2" : 73, "final" : 85 } } +]]> + + + + + The database can also save arbitrary PHP objects (although they will be + returned as associative arrays). The fields are used for the key/value + pairs. For example, a blog post might look like: + + author = $author; +$this->content = $content; + $this->date = new MongoDate(); + } + + public function setTitle($title) { + $this->title = $title; + } +} + +// create a simple blog post and insert it into the database +$post1 = new Post("Adam", "This is a blog post"); + +$blog->insert($post1); + + +// there is nothing restricting the type of the "author" field, so we can make +// it a nested object +$author = array("name" => "Fred", "karma" => 42); +$post2 = new Post($author, "This is another blog post."); + +// we create an extra field by setting the title +$post2->setTitle("Second Post"); + +$blog->insert($post2); + +?> +]]> + + + + + From the database shell, this will look something like: + + db.blog.find() +{ "_id" : ObjectId("4b06c263edb87a281e09dad8"), "author" : "Adam", "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:22:59 GMT-0500 (EST)" } +{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "author" : { "name" : "Fred", "karma" : 42 }, "content" : "This is a blog post", "comments" : [ ], "date" : "Fri Nov 20 2009 11:23:30 GMT-0500 (EST)", "title" : "Second Post" } +]]> + + +
+ +
+ MongoDB Types + + + The Mongo PHP driver also defines a few new types to use with the database. + See class documentation for details and examples. + + + + + + + Type + Description + Size in MongoDB (bytes) + + + + + MongoBinData + Binary data. + Number of bytes in binary data + 5 + + + MongoCode + JavaScript code. + String length of code + object size of scope. + + + MongoDate + Dates and times. Stored as milliseconds since the epoch. + 8 + + + MongoId + Unique document id: + + + 4 bytes of timestamp + + No two records can have the same id if they were inserted at different + times. + + + + 3 bytes machine id + + No two records can have the same id if they were inserted on different + machines + + + + 2 bytes thread id + + No two records can have the same id if they were inserted by different + threads running on the same machine. + + + + 3 bytes incrementing value + + Each time an id is created, a global counter is incremented and used + as the increment value of the next id. + + + + Thus, no two records can have the same id unless a single process on a + single machine managed to insert 256^3 (over 16 million) documents in + one second, overflowing the increment field. + + 12 + + + MongoMinKey + Always smaller than any other value. + String length of code + object size of scope. + + + MongoMaxKey + JavaScript code. + Always larger than any other value. + + + MongoRegex + Regular expressions. + + Number of characters in regular expression + number of flags + + + + MongoTimestamp + Sharding timestamp + 8 + + + + + +
+ +
+ Unsupported Types + + Types supported by Mongo, but not the PHP driver: + + + + + + Type + Description + Size in MongoDB (bytes) + + + + + long + + As PHP does not support 8 byte integers, longs fetched from the database + are converted to doubles. Integers will always be saved to the database + as 4 byte ints (even on machines that support 8 byte ints) and doubles + will be saved as 8 bytes doubles, so there is no way to save a long to + the database with the PHP driver. + + 8 + + + + + +
+ + + &reference.mongo.mongoid; + &reference.mongo.mongocode; + &reference.mongo.mongodate; + &reference.mongo.mongoregex; + &reference.mongo.mongobindata; + &reference.mongo.mongodbref; + &reference.mongo.mongominkey; + &reference.mongo.mongomaxkey; + &reference.mongo.mongotimestamp; + +