Mongo Php Adapter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alcaeus/mongo-php-adapter:^1.2.5
   

   Ensure ext-mongodb (PHP driver) is installed (php -m | grep mongodb) and PHP 8.2 is used (this release fixes compatibility).

2. Basic Usage (Updated for PHP 8.2):

   use MongoDB\Client as MongoClient;
   use Alcaeus\MongoClient\Connection;
   
   $client = new MongoClient('mongodb://localhost:27017');
   $adapter = new Connection($client); // Now fully PHP 8.2 compatible
   $collection = $adapter->selectCollection('db', 'collection');
   

3. First Use Case (Legacy Migration): Replace deprecated ext-mongo calls with the adapter:

   // Old (deprecated)
   $conn = mongo_connect('localhost');
   // New (PHP 8.2 safe)
   $client = new MongoClient('mongodb://localhost');
   $adapter = new Connection($client);
   

Implementation Patterns

Workflow: Legacy Code Migration (PHP 8.2 Safe)

1. Wrap MongoDB\Client (No Breaking Changes):

   $mongoClient = new MongoClient('mongodb://user:pass@host:port');
   $legacyAdapter = new Connection($mongoClient); // Fixed for PHP 8.2
   

2. Replace mongo_* Functions (Updated Examples):

   • mongo_connect() → new Connection($client)
   • mongo_query() → $collection->find($query) (returns Cursor object)
   • Note: All legacy methods now work without private API warnings (fixed in PR #307).

3. Cursor Handling (No Changes Needed):

   $cursor = $collection->find(['status' => 'active']);
   while ($cursor->advance()) {
       $doc = $cursor->current(); // Works as before
   }
   

Integration Tips (PHP 8.2 Compatibility)

• Laravel Eloquent: Use with jenssegers/mongodb (tested with PHP 8.2):

  $adapter = new Connection(new MongoClient(env('DB_CONNECTION')));
  config(['database.connections.mongodb.adapter' => $adapter]);
  

• Query Builder: Chain legacy methods with modern queries (no breaking changes):

  $result = $collection
      ->find()
      ->limit(10)
      ->sort(['createdAt' => -1]);
  

• Transactions (Fixed Session Handling):

  $session = $client->startSession();
  $adapter->setSession($session); // Now works without private API issues
  

Gotchas and Tips

Pitfalls (Updated for 1.2.5)

1. Deprecation Warning (Still Applies): The package is deprecated (last release 2023). Prefer native mongodb/mongodb for new projects.

   • Workaround: Use only for legacy codebases migrating from ext-mongo.

2. PHP 8.2 Specific Fixes:

   • No Breaking Changes: PR #307 fixed private API usage, so existing code works without warnings.
   • Deprecation Notices: PR #306 silenced PHP 8.2 deprecation notices (e.g., foreach with string keys).

3. Method Mismatches (Unchanged):

   • mongo_insert() → Use $collection->insertOne().
   • mongo_find() → Use $collection->find() (returns Cursor).
   • Tip: Cross-reference legacy docs.

4. Session Handling (Fixed in 1.2.5):

   • Sessions no longer trigger private API warnings:

     $session = $client->startSession();
     $adapter->setSession($session); // Safe for transactions
     

Debugging (PHP 8.2)

• Enable Adapter Logging:

  $adapter = new Connection($client, [
      'logger' => new \Monolog\Logger('mongo_adapter'),
  ]);
  

• Check for Deprecated Calls: Use xdebug to trace Alcaeus\MongoClient method calls in legacy code.
  • Note: PHP 8.2 deprecation notices are now suppressed (PR #306).

Extension Points (Unchanged)

1. Custom Adapters: Extend Connection for domain logic (PHP 8.2 compatible):

   class CustomAdapter extends Connection {
       public function findByEmail($email) {
           return $this->selectCollection('users')->find(['email' => $email]);
       }
   }
   

2. Override Cursor Behavior: Extend Cursor (no PHP 8.2 issues):

   class CachedCursor extends Cursor {
       protected $cache = [];
       public function current() {
           if (!isset($this->cache[$this->key])) {
               $this->cache[$this->key] = parent::current();
           }
           return $this->cache[$this->key];
       }
   }
   

3. Hybrid Queries: Combine legacy and modern syntax (works as before):

   $query = ['$query' => ['age' => ['$gt' => 18]], '$orderby' => ['name' => 1]];
   $result = $collection->find($query);