Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xp-forge/mongodb
MongoDB for the XP Framework
https://github.com/xp-forge/mongodb
bson mongodb mongodb-atlas mongodb-php-library protocol replica-set scram-sha-1 scram-sha-256 sessions transactions xp-framework
Last synced: about 2 months ago
JSON representation
MongoDB for the XP Framework
- Host: GitHub
- URL: https://github.com/xp-forge/mongodb
- Owner: xp-forge
- Created: 2020-08-04T11:07:59.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-10-29T07:28:09.000Z (about 2 months ago)
- Last Synced: 2024-10-29T08:23:56.169Z (about 2 months ago)
- Topics: bson, mongodb, mongodb-atlas, mongodb-php-library, protocol, replica-set, scram-sha-1, scram-sha-256, sessions, transactions, xp-framework
- Language: PHP
- Homepage:
- Size: 342 KB
- Stars: 0
- Watchers: 4
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
Awesome Lists containing this project
README
MongoDB connectivity
====================
[](https://github.com/xp-forge/mongodb/actions)
[](https://github.com/xp-framework/core)
[](https://github.com/xp-framework/core/blob/master/LICENCE.md)
[](http://php.net/)
[](http://php.net/)
[](https://packagist.org/packages/xp-forge/mongodb)
This library implements MongoDB connectivity via its binary protocol. It has no dependencies on the PHP extension.
Examples
--------
Finding documents inside a collection:
```php
use com\mongodb\{MongoConnection, ObjectId};
use util\cmd\Console;
$c= new MongoConnection('mongodb://localhost');
$id= new ObjectId(...);
// Find all documents
$cursor= $c->collection('test.products')->find();
// Find document with the specified ID
$cursor= $c->collection('test.products')->find($id);
// Find all documents with a name of "Test"
$cursor= $c->collection('test.products')->find(['name' => 'Test']);
foreach ($cursor as $document) {
Console::writeLine('>> ', $document);
}
```
Inserting a document into a collection:
```php
use com\mongodb\{MongoConnection, Document};
use util\cmd\Console;
$c= new MongoConnection('mongodb://localhost');
$result= $c->collection('test.products')->insert(new Document([
'name' => 'Test',
'qty' => 10,
'tags' => ['new', 'tested'],
]));
Console::writeLine('>> ', $result);
```
Updating documents:
```php
use com\mongodb\{MongoConnection, ObjectId};
use util\cmd\Console;
$c= new MongoConnection('mongodb://localhost');
$id= new ObjectId(...);
// Select a single document for updating by its ID
$result= $c->collection('test.products')->update($id, ['$inc' => ['qty' => 1]]);
// Apply to all documents matchig a given filter
$result= $c->collection('test.products')->update(['name' => 'Test'], ['$inc' => ['qty' => 1]]);
Console::writeLine('>> ', $result);
```
[Upserting](https://www.mongodb.com/docs/manual/reference/command/update/#std-label-update-command-upsert) documents:
```php
use com\mongodb\MongoConnection;
use util\cmd\Console;
$c= new MongoConnection('mongodb://localhost');
$result= $c->collection('test.products')->upsert(['slug' => 'test'], new Document([
'slug' => 'test',
'name' => 'Test',
'qty' => 10,
'tags' => ['new', 'tested'],
]));
Console::writeLine('>> ', $result);
```
Deleting documents:
```php
use com\mongodb\{MongoConnection, ObjectId};
use util\cmd\Console;
$c= new MongoConnection('mongodb://localhost');
$id= new ObjectId(...);
// Select a single document to be removed
$result= $c->collection('test.products')->delete($id);
// Remove all documents matchig a given filter
$result= $c->collection('test.products')->delete(['name' => 'Test']);
Console::writeLine('>> ', $result);
```
*Note: All of the above have used the `collection()` shortcut which is equivalent to chaining `database('test')->collection('products')`.*
Authentication
--------------
To authenticate, pass username and password via the connection string, e.g. `mongodb://user:pass@localhost`. The authentication source defaults to *admin* but can be set by supplying a path, e.g. `mongodb://user:pass@localhost/test`.
Both *SCRAM-SHA-256* and *SCRAM-SHA-1* are supported as authentication mechanisms. Which one is used is negotiated upon connecting with the server / cluster. To explicitely select the authentication mechanism, pass it as part of the connection string, e.g. `mongodb://user:pass@localhost?authMechanism=SCRAM-SHA-256`.
SSL / TLS
---------
To connect via SSL / TLS, pass `ssl=true` as connection string parameters, e.g.:
```php
use com\mongodb\MongoConnection;
$c= new MongoConnection('mongodb://localhost?ssl=true');
// Explicit call to connect, can be omitted when using collection()
$c->connect();
```
Aggregation
-----------
The `Collection` class also features aggregation methods:
* `count($filter= [])`
* `distinct($key, $filter= [])`
* `aggregate($pipeline)`
See https://docs.mongodb.com/manual/reference/command/nav-aggregation/
Commands
--------
To run commands on a given collection, use the *run()* method:
```php
use com\mongodb\MongoConnection;
$c= new MongoConnection('mongodb+srv://server.example.com');
// A simple connection-wide command without arguments
$result= $c->run('ping')->value();
// A command might return a cursor
$indexes= $c->collection('app.sessions')->run('listIndexes', [], 'read');
foreach ($indexes->cursor() as $index) {
// ...
}
```
See https://www.mongodb.com/docs/manual/reference/command/ for a list of commands.
DNS Seed List Connection
------------------------
Adding in DNS to specify clusters adds another level of flexibility to deployment. Given the following DNS entries:
```
Record TTL Class Priority Weight Port Target
_mongodb._tcp.server.example.com. 86400 IN SRV 0 5 27317 mongodb1.example.com.
_mongodb._tcp.server.example.com. 86400 IN SRV 0 5 27017 mongodb2.example.com.
```
...the following code will connect to one of the above:
```php
use com\mongodb\MongoConnection;
$c= new MongoConnection('mongodb+srv://server.example.com');
$c->connect();
```
Sessions
--------
Using a causally consistent session, an application can read its own writes and is guaranteed monotonic reads, even when reading from replica set secondaries.
```php
use com\mongodb\{MongoConnection, ObjectId};
use util\cmd\Console;
$c= new MongoConnection('mongodb+srv://server.example.com?readPreference=secondary');
$session= $c->session();
$id= new ObjectId('...');
// Will write to primary
$collection= $c->collection('test.products');
$collection->update($id, ['$set' => ['qty' => 1]], $session);
// Will read the updated document
$updated= $collection->find($id, $session);
$session->close();
```
Handling errors
---------------
All operations raise instances of the `com.mongodb.Error` class. Connection and authentication errors can be handled by checking for *CannotConnect*:
```php
use com\mongodb\{MongoConnection, Error, CannotConnect};
use util\cmd\Console;
$c= new MongoConnection('mongodb+srv://user:[email protected]');
try {
$c->connect();
} catch (CannotConnect $e) {
// Error during authentication phase, e.g.:
// - DNS errors
// - None of the replica set members is reachable
// - Authentication failed
} catch (Error $e) {
// Any other error
}
```
Type mapping
------------
All builtin types are mapped to their BSON equivalents. In addition, the following type mappings are used:
* `util.Date` => UTC datetime
* `util.Bytes` => Binary data
* `util.UUID` => UUID binary data
* `com.mongodb.Int64` => 64-bit integer
* `com.mongodb.Decimal128` => 128-bit decimal
* `com.mongodb.ObjectId` => Object ID
* `com.mongodb.Timestamp` => Timestamp
* `com.mongodb.Regex` => Regular expression
The deprecated types of the BSON spec are not supported, see http://bsonspec.org/spec.html