Doctrine1 Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require diablomedia/doctrine1-bundle diablomedia/doctrine1
   

   • The doctrine1 fork is recommended for better PHP compatibility.

2. Enable Bundle: Add to config/app.php under providers:

   DiabloMedia\Bundle\Doctrine1Bundle\Doctrine1Bundle::class,
   

3. Configure Database: Create config/doctrine1.php (or add to config/services.php):

   'doctrine1' => [
       'default_connection' => 'default',
       'connections' => [
           'default' => [
               'url' => env('DATABASE_URL'),
               'cache_class' => 'Doctrine_Cache_Array',
               'enable_query_cache' => true,
               'enable_result_cache' => true,
           ],
       ],
   ],
   

4. First Use Case: Inject the Doctrine1 service in a controller/service:

   use DiabloMedia\Bundle\Doctrine1Bundle\Doctrine1;
   
   public function __construct(private Doctrine1 $doctrine) {}
   
   public function index() {
       $query = $this->doctrine->getConnection()->createQuery('SELECT * FROM users');
       $results = $query->execute();
       return view('users.index', ['users' => $results]);
   }
   

5. Debugging: Enable the Symfony profiler in config/packages/dev/doctrine1.yaml:

   profiler: true
   

   Access the toolbar at /_profiler to inspect Doctrine queries.

Implementation Patterns

Usage Patterns

1. Connection Management:

   • Use named connections (e.g., writer, reader) for read/write separation:

     $writer = $this->doctrine->getConnection('writer');
     $reader = $this->doctrine->getConnection('reader');
     

2. Query Building:

   • Leverage Doctrine1’s query builder for type safety:

     $qb = $this->doctrine->getConnection()->createQueryBuilder();
     $qb->select('u.*')->from('users', 'u')->where('u.active = 1');
     $users = $qb->execute()->fetchAll();
     

3. Entity Mapping:

   • Define mappings in config/doctrine1.php:

     'mappings' => [
         'App\Entity' => [
             'type' => 'annotation',
             'dir' => __DIR__.'/../src/Entity',
             'namespace' => 'App\Entity',
         ],
     ],
     

   • Use annotations (e.g., @Table, @Column) in your entities.

4. Caching:

   • Configure caching per connection (e.g., Doctrine_Cache_Apc, Doctrine_Cache_Memcache):

     cache_class: 'Doctrine_Cache_Memcache'
     memcache_host: '%env(MEMCACHE_HOST)%'
     

5. Migrations:

   • Use doctrine1:migrations:execute (if integrated) or raw SQL for schema changes:

     php bin/console doctrine1:migrations:execute
     

Workflows

1. Repository Pattern:

   • Create a repository service for complex queries:

     class UserRepository {
         public function __construct(private Doctrine1 $doctrine) {}
     
         public function findActiveUsers() {
             return $this->doctrine->getConnection()
                 ->createQuery('SELECT * FROM users WHERE active = 1')
                 ->execute()
                 ->fetchAll();
         }
     }
     

2. Transaction Management:

   • Wrap operations in transactions:

     $conn = $this->doctrine->getConnection();
     $conn->beginTransaction();
     try {
         $conn->execute('UPDATE accounts SET balance = balance - 100 WHERE id = ?', [1]);
         $conn->execute('UPDATE accounts SET balance = balance + 100 WHERE id = ?', [2]);
         $conn->commit();
     } catch (\Exception $e) {
         $conn->rollBack();
         throw $e;
     }
     

3. Event Listeners:

   • Attach listeners for lifecycle events (e.g., postInsert):

     $conn->listen('postInsert', function ($event) {
         // Post-save logic
     });
     

4. Symfony Integration:

   • Use dependency injection for services:

     # config/services.yaml
     services:
         App\Service\UserService:
             arguments:
                 $doctrine: '@doctrine1'
     

Integration Tips

1. Laravel-Specific:

   • Override the bundle’s profiler template to match Laravel’s toolbar: Copy vendor/diablomedia/doctrine1-bundle/Resources/views/Profiler/doctrine1.html.twig to resources/views/vendor/doctrine1/profiler.html.twig.

2. Testing:

   • Use Doctrine1TestCase for unit tests:

     use DiabloMedia\Bundle\Doctrine1Bundle\Testing\Doctrine1TestCase;
     
     class UserTest extends Doctrine1TestCase {
         public function testFindUser() {
             $user = $this->getDoctrine1()->getConnection()->fetchRow('SELECT * FROM users WHERE id = 1');
             $this->assertEquals('John', $user['name']);
         }
     }
     

3. Performance:

   • Enable query caching for read-heavy apps:

     enable_query_cache: true
     cache_class: 'Doctrine_Cache_Redis'
     redis_host: '%env(REDIS_HOST)%'
     

4. Legacy Code:

   • Use Doctrine_Connection directly for compatibility:

     $conn = $this->doctrine->getConnection();
     $result = $conn->fetchAll('SELECT * FROM legacy_table');
     

Gotchas and Tips

Pitfalls

1. Profiler in Production:

   • The profiler is automatically disabled in non-dev environments (check APP_ENV). If you need it in staging, explicitly enable it in config/packages/staging/doctrine1.yaml:

     profiler: true
     

2. Deprecated Twig Functions:

   • Avoid using {{ deprecated() }} in templates (removed in v1.1.4). Replace with @deprecated tags or modern Twig syntax.

3. Connection Pooling:

   • Doctrine1 does not support connection pooling out of the box. For high-traffic apps, use a connection manager like Doctrine_Connection_Manager or a PDO wrapper.

4. Case-Sensitive Schema:

   • Doctrine1 defaults to case-sensitive schema names. Use quotes in queries for reserved keywords:

     $query = 'SELECT `id`, `name` FROM `users`'; // Backticks for MySQL
     

5. Symfony 6+ Profiler:

   • The profiler template assumes Symfony 6’s redesigned toolbar. If using Symfony 5, override the template to avoid Twig\Error\RuntimeError.

6. Entity Metadata:

   • Doctrine1 does not auto-detect entity metadata in src/. Explicitly define mappings in config/doctrine1.php:

     'mappings' => [
         'App\Entity' => ['dir' => __DIR__.'/../../src/Entity'],
     ],
     

7. Transactions and PDO:

   • Doctrine1 transactions do not nest by default. Use PDO::ATTR_AUTOCOMMIT = false for nested transactions:

     $conn->getWrappedConnection()->exec('SET AUTOCOMMIT = 0');
     

Debugging

1. Query Logging:

   • Enable SQL logging in config/doctrine1.yaml:

     logging: true
     log_path: '%kernel.logs_dir%/doctrine1.log'
     

2. Profiler Data:

   • Clear the profiler cache if data doesn’t update:

     php bin/console cache:clear
     

3. Connection Issues:

   • Verify url format in config (e.g., mysql://user:pass@host/db or postgresql://user:pass@host/db).
   • Check for typos in cache_class (e.g., Doctrine_Cache_Array vs. Doctrine\Cache\ArrayCache).

4. Entity Errors:

   • Use doctrine1:schema:validate to check mappings:

     php bin/console doctrine1:schema:validate
     

5. Deprecation Warnings:

   • Suppress warnings in config/bootstrap.php (temporarily):

     error_reporting(E_ALL & ~E_DEPRECATED);
     

Tips

1. Environment-Specific Configs:
   • Use `config/packages/{env}/do