Propel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Replace with the maintained fork:

   composer require skfoxvn/propel-bundle
   

   Add to config/bundles.php:

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

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

   propel:
       dbal_connection: default
       runtime: ~ # Auto-detected or set to 'php'/'xml'
       schema_dir: '%kernel.project_dir%/src/Resources/schema'
       migrations_dir: '%kernel.project_dir%/src/Migrations'
   

3. First Use Case: Generate Models Run schema generation from XML:

   php bin/console propel:build --schema=src/Resources/schema.xml
   

   Verify models in src/Entity/ (Propel-generated).

Implementation Patterns

Core Workflows

1. Schema-Driven Development

   • Store schema in BundleName/Resources/schema.xml (XML-only, no YAML).
   • Regenerate models after changes:

     php bin/console propel:build --schema=path/to/schema.xml --write-sql
     

2. Database Operations

   • Migrations: Use Propel’s native migrations:

     php bin/console propel:migration:diff
     php bin/console propel:migration:migrate
     

   • Reverse Engineering: Convert existing DB to schema:

     php bin/console propel:reverse --connection=default --output-dir=src/Resources
     

3. Querying

   • Use Propel’s Criteria API (e.g., UserQuery::create()->find()).
   • Integrate with Symfony’s ParamConverter for actions:

     use Propel\Runtime\ParamConverter\PropelParamConverter;
     
     // services.yaml
     Sensio\Bundle\FrameworkExtraBundle\EventListener\ParamConverterListener:
         arguments:
             - ['propel' => PropelParamConverter]
     

4. Forms & Validation

   • Bind Propel models to Symfony Forms:

     $form = $this->createForm(PropelFormType::class, $user);
     

   • Use Propel’s validation rules (e.g., @assert("email", "NotBlank")).

5. Fixtures

   • Load data via SQL/YAML/XML:

     php bin/console propel:fixtures:load --append
     

Integration Tips

• Doctrine Bridge: Use PropelBundle\Bridge\Doctrine\PropelEntityManager for hybrid apps.
• Security: Leverage Propel’s UserQuery with Symfony’s security component:

  # security.yaml
  providers:
      propel_user_provider:
          entity: { class: User, property: username }
  

• Profiler: Enable Propel’s profiler tab via propel.profiler.enabled: true in config.

Gotchas and Tips

Pitfalls

1. Deprecation Warning

   • This bundle is unmaintained; migrate to SkyFoxvn’s fork (Propel2 support).
   • Propel 1.x (used here) is EOL; prefer Propel 2.x for new projects.

2. Schema Generation Quirks

   • XML-Only: Avoid YAML schemas (not supported).
   • Namespace Conflicts: Ensure schema.xml namespaces match your bundle’s autoloader.
   • Regeneration: Always run --write-sql first to preview SQL changes.

3. Runtime Configuration

   • runtime: php vs xml:
     • php: Faster (runtime parsing), but requires propel.php config.
     • xml: Slower (parses schema on each request), but avoids PHP config.
   • Debug runtime issues with:

     php bin/console debug:config propel
     

4. Migrations Gotchas

   • Connection Locks: Run migrations in a single process to avoid conflicts.
   • Schema Drift: Migrations assume schema matches DB; validate with:

     php bin/console propel:migration:check
     

5. Symfony Integration

   • ParamConverter: Requires sensio_framework_extra bundle.
   • Forms: Propel models must implement Symfony\Component\Form\FormInterface (use PropelFormType).

Debugging Tips

• Query Logging: Enable with:

  propel:
      logging: true
  

• Schema Validation: Use:

  php bin/console propel:schema:validate
  

• Autoloader Issues: Clear cache after model generation:

  php bin/console cache:clear
  

Extension Points

1. Custom Query Classes Extend BaseQuery for reusable queries:

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

2. Event Listeners Hook into Propel’s lifecycle (e.g., postInsert):

   use Propel\Runtime\Connection\ConnectionInterface;
   
   class MyListener {
       public function postInsert(ConnectionInterface $con, Model $obj) {
           // Custom logic
       }
   }
   

   Register in services.yaml:

   services:
       App\Listener\MyListener:
           tags:
               - { name: propel.listener, event: postInsert }
   

3. Custom Fixtures Extend PropelFixturesLoader for complex data:

   use Propel\Runtime\Connection\ConnectionInterface;
   
   class CustomFixturesLoader extends PropelFixturesLoader {
       protected function load(ConnectionInterface $con) {
           // Custom fixture logic
       }
   }