Propel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dayspring-tech/propel-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Dayspring\PropelBundle\PropelBundle::class => ['all' => true],
   ];
   

2. Configuration Update config/packages/propel.yaml (auto-generated on first run):

   propel:
       dbal:
           driver:   "%env(DATABASE_DRIVER)%"
           host:     "%env(DATABASE_HOST)%"
           dbname:   "%env(DATABASE_NAME)%"
           user:     "%env(DATABASE_USER)%"
           password: "%env(DATABASE_PASSWORD)%"
           port:     "%env(DATABASE_PORT)%"
   

   Run schema initialization:

   php bin/console propel:schema:init
   

3. First Use Case Generate a model from an existing table:

   php bin/console propel:model:build --schema=your_schema
   

   Use the model in a controller:

   use App\Models\YourModel;
   
   public function index()
   {
       $records = YourModelQuery::create()->find();
       return $this->render('template.html.twig', ['records' => $records]);
   }
   

Implementation Patterns

Workflows

1. Schema Management

   • Migrations: Use propel:schema:diff and propel:schema:update for version-controlled schema changes.
   • Reverse Engineering: Generate models from an existing DB:

     php bin/console propel:model:build --schema=public --output-dir=src/Models
     

2. Querying Data

   • Criteria API: Chain methods for complex queries:

     $activeUsers = UserQuery::create()
         ->filterByIsActive(true)
         ->orderByLastLoginDesc()
         ->find();
     

   • Hydration: Use findOneBy(), findBy(), or create() for direct hydration.

3. Relationships

   • Lazy Loading: Access related objects via getX() (e.g., $user->getPosts()).
   • Eager Loading: Optimize with with():

     $users = UserQuery::create()->with('Posts')->find();
     

4. Transactions Wrap operations in a transaction:

   $conn = Propel::getConnection();
   $conn->beginTransaction();
   try {
       $user->save();
       $post->save();
       $conn->commit();
   } catch (\Exception $e) {
       $conn->rollBack();
       throw $e;
   }
   

5. Custom Queries Extend BaseQuery for reusable logic:

   class UserQuery extends BaseUserQuery
   {
       public function activeAndRecent()
       {
           return $this->filterByIsActive(true)->filterByCreatedAt('>=', date('Y-m-d', strtotime('-30 days'))));
       }
   }
   

Integration Tips

• Symfony Forms: Bind Propel models to forms using ModelType:

  use Dayspring\PropelBundle\Form\ModelType;
  
  $builder->add('user', ModelType::class, [
      'class' => User::class,
      'property' => 'profile',
  ]);
  

• API Platform: Use @ApiResource with Propel entities (requires custom hydration).
• Event Listeners: Attach to Propel events (e.g., postSave, postDelete) via Symfony’s event dispatcher.

Gotchas and Tips

Pitfalls

1. Schema Locking

   • Propel locks the schema during migrations. Avoid concurrent schema:update runs.
   • Fix: Use --no-lock for testing (not production):

     php bin/console propel:schema:update --no-lock
     

2. Model Generation Overwrites

   • Regenerating models overwrites custom logic in Base*Query or Base*Peer classes.
   • Fix: Extend models in src/Models/ (auto-loaded) instead of generated-models/.

3. Caching Quirks

   • Propel caches queries aggressively. Clear cache after schema changes:

     php bin/console cache:clear
     

   • Disable caching for development:

     # config/packages/propel.yaml
     propel:
         runtime:
             cache: false
     

4. Relationship Ambiguity

   • One-to-one/many relationships with identical column names cause conflicts.
   • Fix: Use localField and foreignField in schema.xml:

     <column name="user_id" type="integer" required="true" primaryKey="false" foreignTable="users" foreignReference="id" />
     

5. Symfony Dependency Injection

   • Propel’s Connection is not a Symfony service by default. Bind it manually:

     # config/services.yaml
     services:
         App\PropelConnection:
             class: Propel\Runtime\Connection\ConnectionWrapper
             factory: ['@propel.connection', 'getConnection']
     

Debugging Tips

• Enable SQL Logging:

  # config/packages/propel.yaml
  propel:
      runtime:
          log: true
  

  Logs appear in var/log/propel.log.

• Query Debugging: Use ->debug() to dump SQL:

  $query = UserQuery::create()->filterByName('John');
  $query->debug(); // Outputs SQL to console
  

• Common Errors:

  • "Table not found": Run propel:schema:init or check schema.xml.
  • "Column not found": Regenerate models or update schema.xml.
  • Foreign key violations: Use transactions or check constraints in schema.xml.

Extension Points

1. Custom Behavior Override Base*Query methods (e.g., postInsert()) for hooks:

   class UserQuery extends BaseUserQuery
   {
       protected function postInsert($con, $obj)
       {
           // Add custom logic after insert
       }
   }
   

2. Schema Customization Extend schema.xml in config/propel/schema.xml for global changes.

3. Event Listeners Listen to Propel events via Symfony’s event system:

   // src/EventListener/PropelListener.php
   public static function getSubscribedEvents()
   {
       return [
           PropelEvents::POST_SAVE => 'onPostSave',
       ];
   }
   

4. Custom Validators Add validation in Base*Peer:

   class BaseUserPeer
   {
       public static function validate($con, $obj)
       {
           if (strlen($obj->getEmail()) > 255) {
               throw new \PropelException('Email too long');
           }
       }
   }