Skip to content

Commit a276e33

Browse files
bjoribjori
committed
Initial documentation
Using markdown and mkdocs ( $ pip install mkdocs )
1 parent 5b69759 commit a276e33

File tree

5 files changed

+333
-2
lines changed

5 files changed

+333
-2
lines changed

‎.gitignore

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,19 +41,26 @@ php.ini
4141
*.swp
4242
.*
4343
!tests/utils/*.php
44-
!docs
4544
!.travis.yml
4645
!.travis.scripts/*
47-
!bin/*.php
4846

4947

48+
# MKDocs
49+
!docs
50+
site
51+
52+
# Run tests
5053
tmp-php.ini
5154

55+
# Release files
56+
!bin/*.php
5257
ChangeLog
5358
RELEASE-*
5459
package.xml
5560
phongo-*tgz
5661

5762
# Composer (for testing)
63+
composer.phar
5864
composer.lock
5965
vendor/
66+

‎docs/batch.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Batch CRUD
2+
3+
```php
4+
<?php
5+
6+
$hannes = array(
7+
"name" => "Hannes",
8+
"nick" => "bjori",
9+
"citizen" => "Iceland",
10+
);
11+
$hayley = array(
12+
"name" => "Hayley",
13+
"nick" => "Alien Ninja",
14+
"citizen" => "USA",
15+
);
16+
$jonpall = array(
17+
"name" => "Jon Pall",
18+
"nick" => "unknown",
19+
"citizen" => "Iceland",
20+
);
21+
22+
/* Ordered batch is executed in the same order as we add the operations to it.
23+
* If operation fails the execution stops and no further operations executed.
24+
* For unordered batch, the operations can be executed in any order by the database
25+
* in an attempt to optimize its workload. An operation failure will not stop
26+
* the exection of the rest of the operations.
27+
* Default: true
28+
*/
29+
$ordered = true;
30+
31+
$batch = new MongoDB\WriteBatch($ordered);
32+
33+
?>
34+
```
35+
36+
## CREATE
37+
38+
```php
39+
<?php
40+
41+
/* Argument#1 The document (array/object) to insert.
42+
* Returns the generated BSON\ObjectID if no _id was provided
43+
*/
44+
$hannes_id = $batch->insert($hannes);
45+
$hayley_id = $batch->insert($hayley);
46+
$jonpall_id = $batch->insert($jonpall);
47+
48+
?>
49+
```
50+
51+
## UPDATE
52+
53+
```php
54+
<?php
55+
56+
/* Arguments
57+
* #1: array, search criteria
58+
* #2: array, the object or operations to apply to the matching document
59+
* #3: array, wire protocol options:
60+
* limit: integer, 0 or 1,
61+
* 0: Apply to all matching documents
62+
* 1: Only apply to the first matching document
63+
* upsert: boolean
64+
* true: Insert new document matching the criteria
65+
* false: Do not insert new document if no matches are found
66+
*/
67+
$batch->update(
68+
array("_id" => $hayley_id),
69+
array('$set' => array("citizen" => "Iceland")),
70+
array("limit" => 1, "upsert" => false)
71+
);
72+
$batch->update(
73+
array("citizen" => "Iceland"),
74+
array("$set" => array("viking" => true)),
75+
array("limit" => 0, "upsert" => false)
76+
);
77+
$batch->update(
78+
array("name" => "Chuck Norris"),
79+
array('$set' => array("viking" => false)),
80+
array("limit" => 1, "upsert" => true)
81+
);
82+
83+
?>
84+
```
85+
86+
## DELETE
87+
88+
```php
89+
<?php
90+
91+
/* Arguments
92+
* #1: array, search criteria
93+
* #2: array, wire protocol options:
94+
* limit: integer, 0 or 1,
95+
* 0: Delete all matching documents
96+
* 1: Only delete the first matching document
97+
*/
98+
$batch->delete(array("_id" => $jonpall_id), array("limit" => 1));
99+
100+
?>
101+
```
102+
103+
## Executing and checking the results
104+
105+
```php
106+
<?php
107+
$manager = new MongoDB\Manager("mongodb://localhost:27017");
108+
$wc = new MongoDB\WriteConcern(MongoDB\WriteConcern::MAJORITY);
109+
$result = $manager->executeWriteBatch("db.collection", $batch, $wc);
110+
111+
printf("numInserted: %d\n", $result->getNumInserted());
112+
printf("numMatched: %d\n", $result->getNumMatched());
113+
printf("numModified: %d\n", $result->getNumModified());
114+
printf("numUpserted: %d\n", $result->getNumUpserted());
115+
printf("numRemoved: %d\n", $result->getNumRemoved());
116+
117+
foreach ($result->getUpsertedIds() as $index => $id) {
118+
printf("upsertedId: '%s', index: %d\n", $id, $index);
119+
}
120+
121+
$query = new MongoDB\Query(array("viking" => false));
122+
$cursor = $manager->executeQuery("db.collection", $query);
123+
var_dump(iterator_to_array($cursor));
124+
125+
?>
126+
```
127+
128+

‎docs/crud.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Basic CRUD
2+
3+
```php
4+
<?php
5+
6+
/* The document we'll be working with */
7+
$document = array("hello" => "world");
8+
9+
/* We want to gurantee all writes to the majority of our nodes */
10+
$w = MongoDB\WriteConcern::MAJORITY;
11+
12+
/* But don't be waiting on me fore more then 1000ms (1sec),
13+
* I have an application to run! */
14+
$wtimeout = 1000;
15+
16+
/* No need to journal or fsync (are infact discouraged in general) */
17+
$journal = $fsync = false;
18+
19+
/* Construct the WriteConcern object from our options */
20+
$wc = new MongoDB\WriteConcern($w, $wtimeout, $journal, $fsync);
21+
22+
23+
/* We prefer to read from the secondary, but are OK to read from the primary
24+
* if we can't find any secondaries */
25+
$prefer = MongoDB\ReadPreference::RP_SECONDARY_PREFERRED;
26+
$tags = array(
27+
/* Prefer the West Coast datacenter in Iceland */
28+
array("country" => "iceland", "datacenter" => "west"),
29+
30+
/* Fallback to any datacenter in Iceland */
31+
array("country" => "iceland"),
32+
33+
/* If Iceland is offline, read from whatever is online! */
34+
array(),
35+
);
36+
37+
/* Construct the ReadPreference object from our options */
38+
$rp = new MongoDB\ReadPreference($prefer, $tags);
39+
40+
41+
/* Construct the MongoDB Manager */
42+
$manager = new MongoDB\Manager("mongodb://localhost:27017");
43+
44+
?>
45+
```
46+
47+
## CREATE
48+
49+
```php
50+
<?php
51+
52+
try {
53+
/* Full namespace as the first argumnet (databasename.collectionname),
54+
* and the document to insert as the second.
55+
*
56+
* Returns MongoDB\WriteResult on success, throws exception on failure
57+
*/
58+
$result = $manager->executeInsert("db.collection", $document, $wc);
59+
} catch(Exception $e) {
60+
echo $e->getMessage(), "\n";
61+
exit;
62+
}
63+
64+
?>
65+
```
66+
67+
## READ
68+
69+
```php
70+
<?php
71+
72+
/* Construct an empty find query ("select all") */
73+
$query = new MongoDB\Query(array());
74+
75+
try {
76+
/* Full namespace as the first argument (dbname.collname), and the query object
77+
* to execute as the second.
78+
* Returns MongoDB\QueryResult on success, throws exception on failure
79+
*/
80+
$cursor = $manager->executeQuery("db.collection", $query, $rp);
81+
82+
/* Iterate over all matched documents */
83+
foreach($cursor as $document) {
84+
var_dump($document);
85+
}
86+
} catch(Exception $e) {
87+
echo $e->getMessage(), "\n";
88+
exit;
89+
}
90+
91+
?>
92+
```
93+
94+
## UPDATE
95+
96+
```php
97+
<?php
98+
99+
/* The search criteria */
100+
$where = array("hello" => "world");
101+
102+
/* What to update the matched document with */
103+
$set = array('$set' => array("hello" => "wonderful world"));
104+
105+
/* Special MongoDB wireprotocol options:
106+
* limit: integer. Updates all matching document when 0 (false).
107+
* Only the first matching document when > 0 (true).
108+
* upsert: boolean. If there is no matching document, create a new document
109+
* from the $where and apply the $set
110+
*/
111+
$options = array("limit" => 1, "upsert" => false);
112+
try {
113+
/* Full namespace as the first argument (dbname.collname), the search criteria
114+
* second.
115+
* Returns MongoDB\WriteResult on success, throws exception on failure
116+
*/
117+
$result = $manager->executeUpdate("db.collection", $where, $set, $options, $wc);
118+
var_dump($result);
119+
} catch(Exception $e) {
120+
echo $e->getMessage(), "\n";
121+
exit;
122+
}
123+
124+
?>
125+
```
126+
127+
## DELETE
128+
129+
```php
130+
<?php
131+
132+
/* The search criteria */
133+
$where = array("hello" => "world");
134+
135+
/* Special MongoDB wireprotocol options:
136+
* limit: integer. Updates all matching document when > 0 (true).
137+
* Only the first matching document when 0 (false).
138+
*/
139+
$options = array("limit" => 1);
140+
try {
141+
/*
142+
/* Full namespace as the first argument (dbname.collname), the search criteria
143+
* second.
144+
* Returns MongoDB\WriteResult on success, throws exception on failure
145+
*/
146+
$result = $manager->executeDelete("db.collection", $where, $options, $wc);
147+
var_dump($result);
148+
} catch(Exception $e) {
149+
echo $e->getMessage(), "\n";
150+
exit;
151+
}
152+
153+
?>
154+
```
155+
156+

‎docs/index.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# What is PHongo?
2+
3+
[Phongo](https://github.com/bjori/phongo) is an experimental MongoDB driver for PHP,
4+
likely replacing the
5+
[mongodb/mongo-php-driver](https://github.com/mongodb/mongo-php-driver) driver in the
6+
near future.
7+
8+
Phongo is written ontop of [libmongoc](https://github.com/mongodb/mongo-c-driver) and
9+
[libbson](https://github.com/mongodb/libbson), and is meant to be as basic as possible.
10+
Core MongoDB concepts are implemented, but everything else is left for other toolkits
11+
to come in and provide pretty and flexible bindings that make sense for their ecosystem.
12+
13+
This makes the driver exceptionally fast, and really easy to work with and provide
14+
first class experience in your framework, library or application.
15+
16+
The plan is to provide an example bindings, which you may chose to use - or ignore
17+
and make your own.
18+
19+
20+
21+
# Installation
22+
23+
Ultimately, this extension is not intended to be explicitly installed. Users should
24+
choose one (or more) userland PHP libraries that depend on this driver, and install
25+
them using, for example, Composer.
26+
27+
To build and install the driver:
28+
29+
$ wget https://github.com/bjori/phongo/releases/download/0.1.1/phongo-0.1.1.tgz
30+
$ pecl install phongo-0.1.1.tgz
31+
$ echo "extension=phongo.so" >> `php --ini | grep "Loaded Configuration" | sed -e "s|.*:\s*||"`
32+
33+

‎mkdocs.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
site_name: "PHongo: The MongoDB Driver for PHP"
2+
repo_url: https://github.com/bjori/phongo
3+
theme: spacelab
4+
pages:
5+
- [index.md, Home]
6+
- [crud.md, CRUD]
7+
- [batch.md, Batch CRUD]

0 commit comments

Comments
 (0)