Propel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require berduj/propel-bundle
   

   Enable it in config/bundles.php:

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

2. Configuration Update config/packages/berduj_propel.yaml (if it exists) or create a custom config file:

   berduj_propel:
       dbal_driver: "pdo_mysql"
       database_name: "your_db"
       user: "your_user"
       password: "your_password"
       host: "localhost"
       port: "3306"
       charset: "utf8"
       path: "%kernel.project_dir%/src/Propel"
       model_namespace: "App\Model"
   

3. Generate Models Run Propel’s schema generation:

   php bin/console propel:build --no-confirmation
   

   This creates models in src/Propel/ (or your configured path).

4. First Query Use the generated model classes in a controller or service:

   use App\Model\UserQuery;
   
   $users = UserQuery::create()->find();
   

Implementation Patterns

Workflow Integration

1. Symfony Dependency Injection Register Propel models as services (if needed) in services.yaml:

   services:
       App\Model\UserQuery:
           tags: ['propel.query']
   

2. Repository Pattern Extend Propel’s BaseQuery to encapsulate logic:

   namespace App\Repository;
   
   use App\Model\UserQuery;
   
   class UserRepository
   {
       public function findActiveUsers()
       {
           return UserQuery::create()->filterByIsActive(true)->find();
       }
   }
   

3. Event Listeners Use Symfony’s event system with Propel lifecycle callbacks:

   // config/services.yaml
   App\EventListener\UserListener:
       tags:
           - { name: kernel.event_listener, event: propel.post_save, method: onPostSave }
   

4. Migrations Use Propel’s schema diff tool for migrations:

   php bin/console propel:diff --output=sql
   

Common Use Cases

• CRUD Operations

  // Create
  $user = new \App\Model\User();
  $user->setName('John Doe')->save();
  
  // Read
  $user = \App\Model\UserQuery::create()->findOneById(1);
  
  // Update
  $user->setName('Jane Doe')->save();
  
  // Delete
  $user->delete();
  

• Relationships

  $posts = $user->getPosts(); // One-to-Many
  $user->getAuthor();         // Many-to-One
  

• Criteria API

  $query = UserQuery::create()
      ->filterByName('John', Criteria::LIKE)
      ->orderByName()
      ->limit(10);
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts Ensure model_namespace in config matches your autoloader (e.g., App\Model). Fix: Verify composer dump-autoload runs after model generation.

2. Schema Updates Propel does not auto-migrate. Always run propel:diff before propel:build. Tip: Use --output=sql to review changes before applying.

3. Caching Issues Propel caches queries aggressively. Clear cache after schema changes:

   php bin/console cache:clear
   

4. Symfony Cache vs. Propel Cache Propel uses its own cache (e.g., runtime/). Disable it in propel.ini if needed:

   propel.runtime = false
   

Debugging

• Query Logging Enable SQL logging in propel.ini:

  propel.log.builder = true
  propel.log.sql = true
  

  Check logs in var/logs/propel.log.

• Model Generation Errors Ensure path in config points to an empty directory or matches existing models.

Extension Points

1. Custom Query Classes Extend BaseQuery to add reusable methods:

   namespace App\Model;
   
   use Propel\Runtime\ActiveQuery\ModelCriteria;
   
   class UserQuery extends \BaseUserQuery
   {
       public function activeOnly()
       {
           return $this->filterByIsActive(true);
       }
   }
   

2. Behavior Classes Use Propel’s behaviors (e.g., Timestampable, Sluggable) via propel:build --behaviors.

3. Custom Validators Override validate() in model classes:

   public function validate()
   {
       if (strlen($this->name) < 3) {
           $this->setError('name', 'Name too short');
       }
   }
   

Performance Tips

• Batch Operations Use doInsert() or doUpdate() for bulk inserts/updates.
• Lazy Loading Avoid N+1 queries by using withColumn() or eager-loading:

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