Propel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dsdeboer/propel-bundle
   

   Enable it in config/bundles.php:

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

2. Configuration Update config/packages/dsdeboer_propel.yaml with your Propel schema paths:

   dsdeboer_propel:
       schema_dirs: ['%kernel.project_dir%/config/propel/schema']
       schema_files: ['xml/schema.xml']
   

3. First Use Case Generate a model from your schema:

   php bin/console propel:build:model
   

   Use the model in a controller:

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

Implementation Patterns

Querying Data

Basic Querying

// Find all records
$users = UserQuery::create()->find();

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

// Ordering & Limiting
$recentUsers = UserQuery::create()
    ->orderByCreatedAt('DESC')
    ->limit(10)
    ->find();

Relationships

// Eager loading
$postsWithAuthors = PostQuery::create()
    ->withColumn('Author', true)
    ->find();

// Joining
$posts = PostQuery::create()
    ->joinWith('Author')
    ->where('Author.name = ?', 'John')
    ->find();

CRUD Operations

Create

$user = new User();
$user->setName('Jane Doe');
$user->save();

Update

$user = UserQuery::create()->findPk(1);
$user->setEmail('jane.doe@example.com');
$user->save();

Delete

$user = UserQuery::create()->findPk(1);
$user->delete();

Integration with Symfony Forms

# config/packages/twig.yaml
twig:
    form_themes: ['DsdeboerPropelBundle:Form:fields.html.twig']

{{ form_start(form) }}
    {{ form_widget(form) }}
    <button type="submit">Save</button>
{{ form_end(form) }}

Event Listeners

// src/EventListener/PropelListener.php
namespace App\EventListener;

use Dsdeboer\PropelBundle\Event\PropelEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class PropelListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            PropelEvents::MODEL_POST_BUILD => 'onModelPostBuild',
        ];
    }

    public function onModelPostBuild($event)
    {
        // Custom logic after model generation
    }
}

Gotchas and Tips

Common Pitfalls

1. Schema Mismatch

   • Ensure propel:build:model is run after schema changes.
   • Use --no-backup cautiously; it skips schema backup.

2. Caching Issues

   • Clear Propel cache after schema updates:

     php bin/console cache:clear
     php bin/console propel:cache:clear
     

3. Transaction Handling

   • Propel transactions work with Symfony’s TransactionAwareInterface:

     $connection = Propel::getConnection();
     $connection->beginTransaction();
     try {
         // Operations
         $connection->commit();
     } catch (\Exception $e) {
         $connection->rollBack();
     }
     

Debugging Tips

• Query Logging Enable SQL logging in config/packages/dsdeboer_propel.yaml:

  dsdeboer_propel:
      debug: true
  

  Logs appear in var/log/propel.log.

• Model Generation Errors Check var/log/propel_build.log for detailed errors during model generation.

Performance Optimization

• Batch Operations Use doSelect() for bulk queries:

  $ids = UserQuery::create()->select(['id'])->find();
  

• Lazy Loading Avoid withColumn() for large datasets; use explicit joins instead.

Extension Points

1. Custom Query Classes Extend Propel\Runtime\ActiveQuery\ModelCriteria for reusable queries:

   class CustomUserQuery extends UserQuery
   {
       public function activeUsers()
       {
           return $this->filterByIsActive(true);
       }
   }
   

2. Schema Customization Override Propel behavior via propel.ini:

   [propel]
   model.classname_format = %sModel
   

3. Event-Driven Workflows Listen to PropelEvents::MODEL_POST_INSERT for post-save logic:

   public function onPostInsert($event)
   {
       $model = $event->getModel();
       // Custom logic
   }
   

Configuration Quirks

• Environment-Specific Schemas Use %kernel.environment% in schema_dirs to load environment-specific schemas:

  schema_dirs: ['%kernel.project_dir%/config/propel/schema/%kernel.environment%']
  

• Database Connections Configure multiple connections in config/packages/dsdeboer_propel.yaml:

  dsdeboer_propel:
      connections:
          default: { dsn: "mysql:host=localhost;dbname=app" }
          slave: { dsn: "mysql:host=slave;dbname=app" }