Orm Pack Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require johnkrovitch/orm-pack
   

   Add to composer.json under require-dev if only for testing:

   "require-dev": {
       "johnkrovitch/orm-pack": "^3.0"
   }
   

2. First Use Case:

   • Replace individual ORM dependencies (e.g., doctrine/orm, eloquent, cycle/orm) with a single johnkrovitch/orm-pack dependency.
   • New Feature: Leverage Pagerfanta integration for pagination in Twig templates. Example: Install Pagerfanta Twig extension:

     composer require pagerfanta/twig
     

   • Replace eloquent in composer.json:

     "require": {
         "-illuminate/database": "*",
         "johnkrovitch/orm-pack": "^3.0",
         "pagerfanta/twig": "^3.0"  # Optional, if using Twig
     }
     

   • Run composer update.

3. Verify:

   • Check vendor/composer/installed.json to confirm mutualized dependencies.
   • Test ORM functionality (e.g., Eloquent queries, Doctrine entities) and new Pagerfanta Twig integration:

     {% pagerfanta results %}
     

Implementation Patterns

Mutualization Workflow

1. Dependency Replacement:

   • Replace all ORM-related packages (e.g., doctrine/orm, eloquent, cycle/orm, yii2, cakephp/orm) with johnkrovitch/orm-pack.
   • Use composer why-not to identify conflicts before replacement.

2. Version Alignment:

   • The pack locks versions of mutualized dependencies (e.g., Doctrine 2.10, Eloquent 8.x, Pagerfanta 3.x).
   • Check composer.json of the pack for version constraints:

     "extra": {
         "orm-pack": {
             "doctrine/orm": "2.10.*",
             "eloquent": "8.0",
             "pagerfanta/twig": "3.0"
         }
     }
     

3. Integration with Laravel:

   • For Laravel projects, remove illuminate/database and add the pack.
   • Configure config/database.php to use the mutualized ORM (e.g., Eloquent) as usual.
   • New: Enable Pagerfanta Twig integration in config/app.php:

     'providers' => [
         JohnKrovitch\OrmPack\Providers\OrmServiceProvider::class,
         JohnKrovitch\OrmPack\Providers\PagerfantaTwigProvider::class, // New
     ],
     'aliases' => [
         'pagerfanta.twig' => JohnKrovitch\OrmPack\Twig\PagerfantaExtension::class, // New
     ],
     

4. Multi-ORM Projects with Pagination:

   • Use autoloading aliases to switch between ORMs dynamically and integrate Pagerfanta:

     // config/orm.php
     'default' => env('ORM_DRIVER', 'eloquent'),
     'drivers' => [
         'eloquent' => \JohnKrovitch\OrmPack\Eloquent\Manager::class,
         'doctrine' => \JohnKrovitch\OrmPack\Doctrine\Manager::class,
     ],
     'pagination' => [
         'enabled' => true,
         'adapter' => \Pagerfanta\Adapter\DoctrineORMAdapter::class, // Example for Doctrine
     ],
     

5. Testing:

   • Run PHPUnit tests with mutualized dependencies:

     composer test
     

   • Test Pagerfanta integration:

     phpunit --filter=PagerfantaTest
     

Gotchas and Tips

Pitfalls

1. Version Conflicts:

   • The pack hardcodes versions of mutualized dependencies, including Pagerfanta 3.x.
   • Fix: Check johnkrovitch/orm-pack's composer.json for supported versions before upgrading Laravel/Eloquent.

2. Missing Providers:

   • Some Laravel packages (e.g., spatie/laravel-activitylog) assume direct eloquent or doctrine dependencies.
   • Fix: Use composer require johnkrovitch/orm-pack --with-all-dependencies or manually alias classes.
   • New: Ensure PagerfantaTwigProvider is registered if using Twig pagination.

3. Doctrine Cache Issues:

   • Doctrine’s metadata cache may fail if not configured properly.
   • Fix: Set up cache drivers in config/doctrine.php:

     'metadata_cache' => 'file://' . storage_path('framework/cache/doctrine'),
     'query_cache' => 'array',
     

4. Pagerfanta Twig Integration:

   • If using Twig, ensure the pagerfanta/twig package is installed and the provider is registered.
   • Fix: Add PagerfantaTwigProvider to config/app.php and verify Twig templates render pagination correctly.

5. Eloquent Global Scopes:

   • Global scopes may not load if the pack’s autoloader overrides Laravel’s.
   • Fix: Re-register scopes in a service provider:

     public function boot()
     {
         \JohnKrovitch\OrmPack\Eloquent\Model::preventGlobalScopes();
         // Re-add your scopes
     }
     

Debugging Tips

1. Dependency Tree: Use composer why johnkrovitch/orm-pack to inspect mutualized dependencies, including Pagerfanta.

2. Class Loading: Check if classes are loaded from the pack:

   composer dump-autoload --optimize --classmap-authoritative
   

3. Logging: Enable Doctrine logging to debug queries:

   $config->setSQLLogger(new \Doctrine\DBAL\Logging\EchoSQLLogger());
   

   New: Debug Pagerfanta adapter issues:

   $adapter = new \Pagerfanta\Adapter\DoctrineORMAdapter($query);
   $pagerfanta = new \Pagerfanta\Pagerfanta($adapter);
   

4. Twig Pagination Debugging: Ensure Twig templates render Pagerfanta correctly:

   {% if pagerfanta is iterable %}
       {% for item in pagerfanta %}
           {{ item }}
       {% endfor %}
       {{ pagerfanta|pagerfanta_twig }}
   {% endif %}
   

Extension Points

1. Custom ORM Support: Extend the pack by adding a new ORM manager:

   // app/Providers/OrmPackServiceProvider.php
   public function register()
   {
       $this->app->singleton('orm.cycle', function () {
           return new \JohnKrovitch\OrmPack\Cycle\Manager();
       });
   }
   

2. Configuration Overrides: Override pack configurations via config/orm-pack.php:

   'doctrine' => [
       'entity_paths' => [
           'App\\Entities',
           'Vendor\\Entities',
       ],
   ],
   'pagination' => [
       'default_per_page' => 15,
       'adapters' => [
           'eloquent' => \Pagerfanta\Adapter\DoctrineORMAdapter::class,
           'query_builder' => \Pagerfanta\Adapter\DoctrineORMAdapter::class,
       ],
   ],
   

3. Testing Mutualized Dependencies: Mock the ORM pack in tests:

   $this->partialMock(
       \JohnKrovitch\OrmPack\Eloquent\Model::class,
       ['newQuery']
   );
   

   New: Test Pagerfanta integration:

   $adapter = $this->createMock(\Pagerfanta\Adapter\AdapterInterface::class);
   $adapter->method('getItems')->willReturn([1, 2, 3]);
   $pagerfanta = new \Pagerfanta\Pagerfanta($adapter);
   $this->assertCount(3, $pagerfanta->getCurrentPageResults());