{"id":18046323,"url":"https://github.com/xp-forge/mongodb","last_synced_at":"2026-04-25T22:01:35.055Z","repository":{"id":42654022,"uuid":"284955219","full_name":"xp-forge/mongodb","owner":"xp-forge","description":"MongoDB for the XP Framework","archived":false,"fork":false,"pushed_at":"2025-10-03T08:17:52.000Z","size":472,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-10-03T09:30:24.737Z","etag":null,"topics":["bson","compression","cosmosdb","mongodb","mongodb-atlas","mongodb-driver","mongodb-php","protocol","replica-set","scram-sha-1","scram-sha-256","sessions","snappy","transactions","xp-framework","zlib","zstandard"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xp-forge.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-08-04T11:07:59.000Z","updated_at":"2025-10-03T08:24:42.000Z","dependencies_parsed_at":"2023-12-30T10:23:00.481Z","dependency_job_id":"1283c721-08c3-44ab-b147-043a3c62db1a","html_url":"https://github.com/xp-forge/mongodb","commit_stats":null,"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/xp-forge/mongodb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Fmongodb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Fmongodb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Fmongodb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Fmongodb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xp-forge","download_url":"https://codeload.github.com/xp-forge/mongodb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xp-forge%2Fmongodb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32278249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bson","compression","cosmosdb","mongodb","mongodb-atlas","mongodb-driver","mongodb-php","protocol","replica-set","scram-sha-1","scram-sha-256","sessions","snappy","transactions","xp-framework","zlib","zstandard"],"created_at":"2024-10-30T19:06:49.263Z","updated_at":"2026-04-25T22:01:35.048Z","avatar_url":"https://github.com/xp-forge.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"MongoDB connectivity\n====================\n\n[![Build status on GitHub](https://github.com/xp-forge/mongodb/workflows/Tests/badge.svg)](https://github.com/xp-forge/mongodb/actions)\n[![XP Framework Module](https://raw.githubusercontent.com/xp-framework/web/master/static/xp-framework-badge.png)](https://github.com/xp-framework/core)\n[![BSD Licence](https://raw.githubusercontent.com/xp-framework/web/master/static/licence-bsd.png)](https://github.com/xp-framework/core/blob/master/LICENCE.md)\n[![Requires PHP 7.4+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-7_4plus.svg)](http://php.net/)\n[![Supports PHP 8.0+](https://raw.githubusercontent.com/xp-framework/web/master/static/php-8_0plus.svg)](http://php.net/)\n[![Latest Stable Version](https://poser.pugx.org/xp-forge/mongodb/version.svg)](https://packagist.org/packages/xp-forge/mongodb)\n\nThis library implements MongoDB connectivity via its binary protocol. It has no dependencies on the PHP extension.\n\n* ✅ Local MongoDB installations\n* ✅ [MongoDB Atlas](https://www.mongodb.com/docs/atlas/) and [Atlas Search](https://www.mongodb.com/docs/atlas/atlas-search/)\n* ✅ [Azure Cosmos DB for MongoDB](https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/introduction)\n\nExamples\n--------\nFinding documents inside a collection:\n\n```php\nuse com\\mongodb\\{MongoConnection, ObjectId};\nuse util\\cmd\\Console;\n\n$c= new MongoConnection('mongodb://localhost');\n$id= new ObjectId('...');\n\n// Find all documents\n$cursor= $c-\u003ecollection('test.products')-\u003equery();\n\n// Find document with the specified ID\n$cursor= $c-\u003ecollection('test.products')-\u003equery($id);\n\n// Find all documents with a name of \"Test\"\n$cursor= $c-\u003ecollection('test.products')-\u003equery(['name' =\u003e 'Test']);\n\n// Use aggregation pipelines\n$cursor= $c-\u003ecollection('test.products')-\u003equery([\n  ['$match' =\u003e ['color' =\u003e 'green', 'state' =\u003e 'ACTIVE']],\n  ['$lookup' =\u003e [\n    'from'         =\u003e 'users',\n    'localField'   =\u003e 'owner.id',\n    'foreignField' =\u003e '_id',\n    'as'           =\u003e 'owner',\n  ]],\n  ['$addFields' =\u003e ['owner' =\u003e ['$first' =\u003e '$owner']]],\n]);\n\nforeach ($cursor as $document) {\n  Console::writeLine('\u003e\u003e ', $document);\n}\n```\n\nInserting a document into a collection:\n\n```php\nuse com\\mongodb\\{MongoConnection, Document};\nuse util\\cmd\\Console;\n\n$c= new MongoConnection('mongodb://localhost');\n\n$result= $c-\u003ecollection('test.products')-\u003einsert(new Document([\n  'name' =\u003e 'Test',\n  'qty'  =\u003e 10,\n  'tags' =\u003e ['new', 'tested'],\n]));\nConsole::writeLine('\u003e\u003e ', $result);\n```\n\nUpdating documents:\n\n```php\nuse com\\mongodb\\{MongoConnection, ObjectId};\nuse util\\cmd\\Console;\n\n$c= new MongoConnection('mongodb://localhost');\n$id= new ObjectId('...');\n\n// Select a single document for updating by its ID\n$result= $c-\u003ecollection('test.products')-\u003eupdate($id, ['$inc' =\u003e ['qty' =\u003e 1]]);\n\n// Apply to all documents matchig a given filter\n$result= $c-\u003ecollection('test.products')-\u003eupdate(['name' =\u003e 'Test'], ['$inc' =\u003e ['qty' =\u003e 1]]);\n\nConsole::writeLine('\u003e\u003e ', $result);\n\n// Return document after modification\n$result= $c-\u003ecollection('test.products')-\u003emodify($id, ['$inc' =\u003e ['qty' =\u003e 1]]);\nConsole::writeLine('\u003e\u003e ', $result-\u003ekind(), ' ', $result-\u003edocument());\n```\n\n[Upserting](https://www.mongodb.com/docs/manual/reference/command/update/#std-label-update-command-upsert) documents:\n\n```php\nuse com\\mongodb\\{MongoConnection, Document};\nuse util\\cmd\\Console;\n\n$c= new MongoConnection('mongodb://localhost');\n\n$result= $c-\u003ecollection('test.products')-\u003eupsert(['slug' =\u003e 'test'], new Document([\n  'slug' =\u003e 'test',\n  'name' =\u003e 'Test',\n  'qty'  =\u003e 10,\n  'tags' =\u003e ['new', 'tested'],\n]));\n\nConsole::writeLine('\u003e\u003e ', $result);\n```\n\nDeleting documents:\n\n```php\nuse com\\mongodb\\{MongoConnection, ObjectId};\nuse util\\cmd\\Console;\n\n$c= new MongoConnection('mongodb://localhost');\n$id= new ObjectId('...');\n\n// Select a single document to be removed\n$result= $c-\u003ecollection('test.products')-\u003edelete($id);\n\n// Remove all documents matchig a given filter\n$result= $c-\u003ecollection('test.products')-\u003edelete(['name' =\u003e 'Test']);\n\nConsole::writeLine('\u003e\u003e ', $result);\n\n// Return deleted document\n$result= $c-\u003ecollection('test.products')-\u003eremove($id);\nConsole::writeLine('\u003e\u003e ', $result-\u003ekind(), ' ', $result-\u003edocument());\n```\n\n*Note: All of the above have used the `collection()` shortcut which is equivalent to chaining `database('test')-\u003ecollection('products')`.*\n\nAuthentication\n--------------\nTo 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`.\n\nBoth *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`.\n\nSSL / TLS\n---------\nTo connect via SSL / TLS, pass `ssl=true` as connection string parameters, e.g.:\n\n```php\nuse com\\mongodb\\MongoConnection;\n\n$c= new MongoConnection('mongodb://localhost?ssl=true');\n\n// Explicit call to connect, can be omitted when using collection()\n$c-\u003econnect();\n```\n\nAggregation\n-----------\nThe `Collection` class also features aggregation methods:\n\n* `count($filter= [])`\n* `distinct($key, $filter= [])`\n* `aggregate($pipeline)`\n\nSee https://docs.mongodb.com/manual/reference/command/nav-aggregation/\n\nCommands\n--------\nTo run commands on a given collection, use the *run()* method:\n\n```php\nuse com\\mongodb\\MongoConnection;\n\n$c= new MongoConnection('mongodb+srv://server.example.com');\n\n// A simple connection-wide command without arguments\n$result= $c-\u003erun('ping')-\u003evalue();\n\n// A command might return a cursor\n$indexes= $c-\u003ecollection('app.sessions')-\u003erun('listIndexes', [], 'read');\nforeach ($indexes-\u003ecursor() as $index) {\n  // ...\n}\n```\n\nSee https://www.mongodb.com/docs/manual/reference/command/ for a list of commands.\n\nDNS Seed List Connection\n------------------------\nAdding in DNS to specify clusters adds another level of flexibility to deployment. Given the following DNS entries:\n\n```\nRecord                            TTL   Class    Priority Weight Port  Target\n_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27317 mongodb1.example.com.\n_mongodb._tcp.server.example.com. 86400 IN SRV   0        5      27017 mongodb2.example.com.\n```\n\n...the following code will connect to one of the above:\n\n```php\nuse com\\mongodb\\MongoConnection;\n\n$c= new MongoConnection('mongodb+srv://server.example.com');\n$c-\u003econnect();\n```\n\nSessions\n--------\nUsing a causally consistent session, an application can read its own writes and is guaranteed monotonic reads, even when reading from replica set secondaries.\n\n```php\nuse com\\mongodb\\{MongoConnection, ObjectId};\nuse util\\cmd\\Console;\n\n$c= new MongoConnection('mongodb+srv://server.example.com?readPreference=secondary');\n$session= $c-\u003esession();\n\n$id= new ObjectId('...');\n\n// Will write to primary\n$collection= $c-\u003ecollection('test.products');\n$collection-\u003eupdate($id, ['$set' =\u003e ['qty' =\u003e 1]], $session);\n\n// Will read the updated document\n$updated= $collection-\u003efind($id, $session);\n\n$session-\u003eclose();\n```\n\nHandling errors\n---------------\nAll operations raise instances of the `com.mongodb.Error` class. Connection and authentication errors can be handled by checking for *CannotConnect*:\n\n```php\nuse com\\mongodb\\{MongoConnection, Error, CannotConnect};\nuse util\\cmd\\Console;\n\n$c= new MongoConnection('mongodb+srv://user:pass@mongo.example.com');\ntry {\n  $c-\u003econnect();\n} catch (CannotConnect $e) {\n  // Error during authentication phase, e.g.:\n  // - DNS errors\n  // - None of the replica set members is reachable\n  // - Authentication failed\n} catch (Error $e) {\n  // Any other error\n}\n```\n\nType mapping\n------------\nAll builtin types are mapped to their BSON equivalents. In addition, the following type mappings are used:\n\n* `util.Date` =\u003e UTC datetime\n* `util.Bytes` =\u003e Binary data\n* `util.UUID` =\u003e UUID binary data\n* `com.mongodb.Int64` =\u003e 64-bit integer\n* `com.mongodb.Decimal128` =\u003e 128-bit decimal\n* `com.mongodb.ObjectId` =\u003e Object ID\n* `com.mongodb.Timestamp` =\u003e Timestamp\n* `com.mongodb.Regex` =\u003e Regular expression\n* `com.mongodb.Encrypted` =\u003e Encrypted values\n\nThe deprecated types of the BSON spec are not supported, see http://bsonspec.org/spec.html","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxp-forge%2Fmongodb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxp-forge%2Fmongodb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxp-forge%2Fmongodb/lists"}