Propel Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require auviis/propel-bundle
   

   Enable the bundle in config/bundles.php:

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

2. Configure Propel Update config/packages/auviis_propel.yaml (auto-generated) with your database connection:

   propel:
       dbal:
           connections:
               default:
                   adapter: pdo_mysql
                   dsn: 'mysql:host=localhost;dbname=your_db'
                   username: your_user
                   password: your_pass
       runtime:
           default: %kernel.project_dir%/vendor/propel/propel/runtime
   

3. Generate Schema Run Propel’s schema generation:

   php bin/console propel:schema:build
   

   (Ensure propel:schema:import is run first if migrating an existing DB.)

4. First Query Use Propel’s QueryBuilder in a controller:

   use Propel\Runtime\ActiveQuery\Criteria;
   
   $users = UserQuery::create()
       ->filterByName('John')
       ->find();
   

First Use Case: CRUD in a Controller

use App\Models\User;
use Symfony\Component\HttpFoundation\Response;

// Create
$newUser = new User();
$newUser->setName('Alice');
$newUser->save();

// Read
$users = UserQuery::create()->find();

// Update
$user = UserQuery::create()->findPk(1);
$user->setName('Alice Updated');
$user->save();

// Delete
$user->delete();

Implementation Patterns

1. Dependency Injection & Services

Inject Propel’s Connection or Runtime via Symfony’s DI:

# config/services.yaml
services:
    App\Service\UserService:
        arguments:
            $connection: '@propel.connection.default'

2. Querying with Criteria

Use Criteria for reusable queries:

$criteria = new Criteria();
$criteria->add(UserQuery::NAME, 'John', Criteria::EQUAL);
$users = UserQuery::create()->add($criteria)->find();

3. Forms & Validation

Bind Propel models to Symfony Forms:

use Symfony\Component\Form\Extension\Core\Type\FormType;
use Symfony\Component\Form\Extension\Core\Type\TextType;

$builder->add('name', TextType::class);
$form->handleRequest($request);
$form->getData()->save(); // Persist model

4. Event Listeners

Hook into Propel lifecycle events (e.g., postSave):

use Propel\Runtime\Connection\ConnectionInterface;
use Propel\Runtime\Model\Event\PostSaveEvent;

$connection->addListener('postSave', function (PostSaveEvent $event) {
    if ($event->getObject() instanceof User) {
        // Log or notify
    }
});

5. Migrations

Use Propel’s schema diff tool:

php bin/console propel:schema:diff
php bin/console propel:schema:update

Integration Tips

• Doctrine Bridge: Use propel:doctrine:convert to migrate from Doctrine.
• Twig Integration: Access Propel models in templates via {{ app.user }}.
• API Platform: Annotate Propel models with @ApiResource for automatic API endpoints.

Gotchas and Tips

Pitfalls

1. Schema Locking

   • Propel locks the schema during generation. Avoid concurrent propel:schema:build runs.
   • Fix: Use --force cautiously or coordinate schema changes.

2. Lazy Loading

   • Propel uses lazy loading by default. Eager-load relations explicitly:

     $user = UserQuery::create()
         ->withColumn('Posts')
         ->findPk(1);
     

3. Symfony Cache Invalidation

   • Propel’s metadata cache (%kernel.cache_dir%/propel) must be cleared after schema changes:

     php bin/console cache:clear
     

4. Transaction Handling

   • Propel transactions don’t play well with Symfony’s EntityManager. Use Propel’s Connection directly:

     $connection->beginTransaction();
     try {
         $user->save();
         $connection->commit();
     } catch (\Exception $e) {
         $connection->rollBack();
     }
     

5. Beta Propel Version

   • The bundle requires Propel 2.0-beta. Test thoroughly; breaking changes may occur.

Debugging Tips

• Enable SQL Logging

  propel:
      runtime:
          default: %kernel.project_dir%/vendor/propel/propel/runtime
          log: true
  

  Logs appear in %kernel.logs_dir%/propel.log.

• Query Debugging Use ->debug() on queries:

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

• Common Errors

  • "Table not found": Run propel:schema:build or check propel:schema:import.
  • Foreign key violations: Use save() with Connection::TRANSACTION_READ_COMMITTED.

Extension Points

1. Custom Query Classes Extend Propel\Runtime\ActiveQuery\ModelCriteria for domain-specific queries:

   class UserQuery extends \Base\UserQuery {
       public static function activeUsers() {
           return self::create()->filterByIsActive(true);
       }
   }
   

2. Behavior Interfaces Implement Propel\Runtime\Model\BehaviorInterface for custom logic (e.g., soft deletes).

3. Console Commands Create custom commands by extending PropelCommand:

   use Symfony\Component\Console\Command\Command;
   use Auviis\PropelBundle\Command\PropelCommand;
   
   class MyPropelCommand extends PropelCommand {
       protected function configure() {
           $this->setName('propel:my:task');
       }
   }
   

4. Event Subscribers Subscribe to Propel events via Symfony’s event dispatcher:

   use Propel\Runtime\Model\Event\PostSaveEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class PropelEventSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               'propel.postSave' => 'onPostSave',
           ];
       }
   
       public function onPostSave(PostSaveEvent $event) { ... }
   }
   

Config Quirks

• Runtime Path: Ensure %kernel.project_dir%/vendor/propel/propel/runtime is correct (adjust if using a custom runtime).
• Environment Variables: Prefer .env for DB credentials (e.g., DATABASE_URL). Override in auviis_propel.yaml:

  propel:
      dbal:
          connections:
              default:
                  dsn: '%env(DATABASE_URL)%'