Doctrine Table Prefix Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require cleentfaar/doctrine-table-prefix-bundle
   

2. Enable the Bundle: Add to config/bundles.php:

   Cleentfaar\DoctrineTablePrefixBundle\CleentfaarDoctrineTablePrefixBundle::class => ['all' => true],
   

3. Configure Prefixes: Add to config/packages/doctrine.yaml:

   cleentfaar_doctrine_table_prefix:
       prefixes: ['acme_', 'legacy_']  # List of prefixes to recognize
   

4. First Use Case:
   • Run migrations or schema updates to verify Doctrine now recognizes prefixed tables (e.g., acme_users instead of users).

Implementation Patterns

Workflow Integration

1. Migrations:

   • Use prefixes in doctrine.yaml to ensure all migrations align with the schema. Example:

     // src/Migrations/VersionYYYYMMDDHHMMSS.php
     public function up(Schema $schema)
     {
         $this->addSql('CREATE TABLE acme_users (...)');
     }
     

   • Run:

     php bin/console doctrine:migrations:migrate
     

2. Entity Mapping:

   • Annotate entities with @Table(name="acme_users") or use setTable() in buildTableDefinition():

     // src/Entity/User.php
     /** @ORM\Table(name="acme_users") */
     class User { ... }
     

   • Or dynamically in EntityListener:

     $em->getClassMetadata(User::class)->setTableName('acme_users');
     

3. Query Builder:

   • Prefixes are automatically resolved in queries:

     $users = $entityManager->createQueryBuilder()
         ->select('u')
         ->from('App\Entity\User', 'u')
         ->where('u.id = :id')
         ->getQuery()
         ->getResult();
     

   • Under the hood, Doctrine translates User to acme_users seamlessly.

4. Multi-Environment Prefixes:

   • Override prefixes per environment in config/packages/dev/doctrine.yaml or prod/doctrine.yaml:

     cleentfaar_doctrine_table_prefix:
         prefixes: ['dev_']  # Environment-specific
     

5. Schema Updates:

   • Use doctrine:schema:update with --complete to sync prefixed tables:

     php bin/console doctrine:schema:update --complete
     

Gotchas and Tips

Pitfalls

1. Case Sensitivity:

   • Prefixes are case-sensitive. Ensure acme_ matches exactly (e.g., ACME_ won’t work unless configured).

2. Existing Schema Conflicts:

   • If tables exist without prefixes, Doctrine may fail to map entities. Solution:
     • Use prefixes: ['', 'acme_'] to include empty prefix (default tables).
     • Or manually set table names in entities.

3. Caching Issues:

   • Clear Doctrine metadata cache after changing prefixes:

     php bin/console cache:clear
     php bin/console doctrine:cache:clear-metadata
     

4. Third-Party Bundles:

   • Some bundles (e.g., EasyAdmin, API Platform) may hardcode table names. Workaround:
     • Patch their entity mappings or override their services to inject the prefix logic.

5. Composite Prefixes:

   • Avoid overlapping prefixes (e.g., acme_ and acme_test_). Solution:
     • Use regex patterns in future versions (check GitHub issues).

Debugging

• Enable SQL Logging:

  # config/packages/dev/doctrine.yaml
  doctrine:
      dbal:
          logging: true
  

  • Verify queries use prefixed tables (e.g., SELECT * FROM acme_users).

• Metadata Dump:

  php bin/console debug:container --parameter=cleentfaar_doctrine_table_prefix.prefixes
  

  • Confirm prefixes are loaded.

Extension Points

1. Dynamic Prefixes:

   • Override the prefix logic by extending the bundle’s PrefixResolver service:

     # config/services.yaml
     Cleentfaar\DoctrineTablePrefixBundle\Resolver\PrefixResolverInterface: '@custom.prefix_resolver'
     

     // src/Resolver/CustomPrefixResolver.php
     class CustomPrefixResolver implements PrefixResolverInterface {
         public function resolve(string $entityClass): string {
             return $entityClass === User::class ? 'dynamic_' . date('Ymd') . '_users' : '';
         }
     }
     

2. Event Listeners:

   • Hook into entity.load_class_metadata to modify table names dynamically:

     // src/EventListener/PrefixListener.php
     public function loadClassMetadata(LoadClassMetadataEventArgs $eventArgs) {
         $metadata = $eventArgs->getClassMetadata();
         $metadata->setTableName('acme_' . $metadata->getTableName());
     }
     

     Register in services.yaml:

     services:
         App\EventListener\PrefixListener:
             tags: ['doctrine.event_listener', { event: 'loadClassMetadata' }]
     

3. Database-Specific Quirks:

   • For PostgreSQL, ensure search_path includes the schema with prefixed tables:

     ALTER DATABASE your_db SET search_path TO public, acme_schema;