Bdf Prime Persistence Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require b2pweb/bdf-prime-persistence
   

   Ensure b2pweb/bdf-prime-persistence is listed in composer.json under require.

2. Register the Service Provider Add to config/app.php under providers:

   B2PWeb\BDFPersistence\PrimePersistenceServiceProvider::class,
   

3. Configure Doctrine Adapter Publish the config file:

   php artisan vendor:publish --provider="B2PWeb\BDFPersistence\PrimePersistenceServiceProvider" --tag="config"
   

   Update config/prime-persistence.php with your Doctrine DBAL connection settings.

4. First Use Case: Basic Query

   use B2PWeb\BDFPersistence\PrimePersistence;
   use Prime\ORM;
   
   $persistence = app(PrimePersistence::class);
   $user = $persistence->find(ORM\User::class, 1); // Fetch user with ID 1
   

Implementation Patterns

Adapter Integration Workflow

1. Replace Prime’s Default Persistence Override Prime’s default persistence layer by binding the adapter in AppServiceProvider:

   public function register()
   {
       $this->app->bind(
           \Prime\Persistence\PersistenceInterface::class,
           \B2PWeb\BDFPersistence\PrimePersistence::class
       );
   }
   

2. Leverage Doctrine DBAL for Complex Queries Use Doctrine’s query builder for advanced SQL operations:

   $queryBuilder = $persistence->getQueryBuilder();
   $results = $queryBuilder
       ->select('u.*')
       ->from('users', 'u')
       ->where('u.active = :active')
       ->setParameter('active', 1)
       ->fetchAllAssociative();
   

3. Hybrid ORM + Raw SQL Combine Prime’s ORM features with raw SQL via the adapter:

   // Fetch a model using ORM
   $user = ORM::forTable('users')->find(1);
   
   // Use Doctrine for a custom query
   $stats = $persistence->executeQuery('SELECT COUNT(*) FROM users WHERE created_at > ?', [now()->subDays(7)]);
   

4. Transaction Management Wrap operations in transactions for atomicity:

   $persistence->getConnection()->beginTransaction();
   try {
       ORM::forTable('users')->create(['name' => 'John']);
       ORM::forTable('posts')->create(['user_id' => 1, 'title' => 'Hello']);
       $persistence->getConnection()->commit();
   } catch (\Exception $e) {
       $persistence->getConnection()->rollBack();
       throw $e;
   }
   

5. Schema Migrations Use Doctrine’s SchemaTool for migrations (if needed):

   $schemaManager = $persistence->getSchemaManager();
   $schemaManager->createTable(new \Doctrine\DBAL\Schema\Table('new_table'));
   

Gotchas and Tips

Pitfalls

1. Connection Configuration

   • Ensure prime-persistence.php matches your Doctrine DBAL connection settings.
   • Gotcha: If using multiple databases, explicitly set the connection name in the config:

     'connection' => 'mysql_secondary',
     

2. Query Builder vs. ORM

   • Gotcha: The adapter bridges Prime’s ORM and Doctrine’s DBAL. Avoid mixing raw SQL with ORM methods in the same transaction without proper error handling.
   • Tip: Use ORM::forTable() for model-specific operations and the adapter’s QueryBuilder for complex joins/aggregations.

3. Transaction Isolation

   • Gotcha: Prime’s ORM transactions may not align with Doctrine’s. Explicitly use the adapter’s connection for transactions:

     $persistence->getConnection()->beginTransaction(); // Use this, not ORM::transaction()
     

4. Schema Differences

   • Gotcha: Doctrine’s schema tools may not auto-detect Prime’s table structures. Manually define schemas if using migrations:

     $table = $schemaManager->createTable('users');
     $table->addColumn('id', 'integer', ['autoincrement' => true]);
     

5. Performance

   • Tip: For bulk operations, use Doctrine’s batch inserts:

     $conn = $persistence->getConnection();
     $conn->transactional(function () use ($conn, $users) {
         $conn->insert('users', $users);
     });
     

Debugging

1. Enable Doctrine Logging Add to config/prime-persistence.php:

   'logging' => true,
   

   Logs will appear in storage/logs/laravel.log.

2. Query Profiling Use Doctrine’s profiler to analyze slow queries:

   $profiler = $persistence->getConnection()->getConfiguration()->getSQLLogger();
   $profiler->startLogging();
   

Extension Points

1. Custom Query Builders Extend the adapter to add domain-specific query methods:

   class CustomPersistence extends PrimePersistence {
       public function findActiveUsers() {
           return $this->getQueryBuilder()
               ->select('*')
               ->from('users')
               ->where('active = 1')
               ->fetchAllAssociative();
       }
   }
   

2. Event Listeners Attach Doctrine events (e.g., postInsert) via the adapter’s connection:

   $connection->getEventManager()->addEventListener(
       \Doctrine\DBAL\Connection::EVENT_POST_INSERT,
       function ($eventArgs) {
           // Post-insert logic
       }
   );
   

3. Repository Pattern Combine with Laravel’s repositories for cleaner architecture:

   class UserRepository {
       protected $persistence;
   
       public function __construct(PrimePersistence $persistence) {
           $this->persistence = $persistence;
       }
   
       public function findByEmail($email) {
           return $this->persistence->find(ORM\User::class, ['email' => $email]);
       }
   }