Getting Started

Installation Add the package via Composer:
```
composer require soyuka/stubs-mongodb
```
No additional configuration is required—this package provides PHPStorm stubs for the ext-mongodb extension.
Where to Look First
- Check the original JetBrains repository for context on the stubs.
- Verify ext-mongodb is installed and enabled in your PHP environment (php -m | grep mongodb).
- Ensure PHPStorm recognizes the stubs by restarting the IDE after installation.
First Use Case
- Open a Laravel project using mongodb (e.g., via jenssegers/laravel-mongodb).
- Create a new PHP file with MongoDB operations (e.g., Client, Collection, Manager).
- PHPStorm should now provide autocompletion, type hints, and error detection for MongoDB methods (e.g., find(), insertOne()).

Implementation Patterns

Leveraging Stubs in Laravel
- Use with jenssegers/laravel-mongodb for seamless MongoDB integration:
```
use Jenssegers\Mongodb\Manager;
use MongoDB\Client;

$manager = app(Manager::class);
$client = new Client('mongodb://localhost:27017');
$collection = $client->selectCollection('db', 'users');
```
- Stubs enable IDE support for:
  - MongoDB Client, Collection, BSON, and Driver classes.
  - Query methods like find(), aggregate(), updateOne().
Workflow Integration
- Pair with Laravel IDE Helper: Generate stubs for Eloquent models if using laravel-mongodb models:
```
php artisan ide-helper:generate
```
- Unit Testing: Write tests with MongoDB mocks (e.g., Mockery or PHPUnit + mongodb-mock):
```
$mockClient = Mockery::mock('overload:MongoDB\Client');
$mockClient->shouldReceive('selectCollection')->andReturnSelf();
```
Custom Stubs Extension
- Extend stubs for project-specific MongoDB classes by copying the stub files from:
```
vendor/soyuka/stubs-mongodb/stubs/
```
- Place custom stubs in stubs/ in your project root and configure PHPStorm to use them: File > Settings > Languages & Frameworks > PHP > Stub Files.

Stub Version Mismatch
- Stubs may lag behind ext-mongodb updates. Verify compatibility by checking:
  - PHP version (ext-mongodb requires PHP 7.4+).
  - MongoDB PHP driver version (php -i | grep "mongodb").
- Fix: Manually update stubs from JetBrains’ repo if needed.
IDE Caching Issues
- PHPStorm may not recognize stubs immediately. Restart the IDE or:
  - Invalidate caches (File > Invalidate Caches).
  - Delete .idea directory and regenerate it (File > Settings > IDE Settings > Build, Execution, Deployment > Invalidate Caches).
Laravel-Mongodb-Specific Quirks
- jenssegers/laravel-mongodb wraps MongoDB classes. Stubs won’t cover Laravel-specific methods (e.g., Model::query()).
- Workaround: Use @mixin in IDE helper files:
```
<?php
/** @mixin \MongoDB\Driver\Manager */
class MongoDBManager {}
```

Verify Stubs Are Loaded
- Open a MongoDB class (e.g., Client) in PHPStorm.
- Hover over methods like selectCollection()—if stubs work, you’ll see a tooltip with parameters/return types.

Fallback for Missing Stubs

If a class/method lacks stubs, use @var annotations:

/** @var \MongoDB\Driver\Cursor $cursor */
$cursor = $collection->find([]);

Extending Stubs for Namespace Conflicts
- If using custom MongoDB namespaces (e.g., App\Services\MongoDB), create a stub file like:
```
stubs/App/Services/MongoDB.stub
```
  With content:
```
<?php
namespace App\Services {
    class MongoDB extends \MongoDB\Client {}
}
```

Add Custom MongoDB Classes
- For project-specific MongoDB utilities, define stubs in stubs/ and reference them in phpstorm.meta.php:
```
return [
    'stubs' => [
        'App\\Services\\MongoDB\\' => 'stubs/App/Services/MongoDB/',
    ],
];
```
Integrate with Laravel Packages
- If using spatie/laravel-mongodb or other MongoDB packages, check their docs for stub compatibility. Contribute missing stubs to this package or JetBrains’ repo.
CI/CD Pipeline Check
- Add a script to verify stubs work in CI (e.g., PHPStan or Psalm):
```
vendor/bin/phpstan analyse --level=5 --generate-mock-files
```