Getting Started

Minimal Setup

Installation Add the package via Composer:

composer require deviscoding/propel1-bundle

Enable the bundle in config/bundles.php:

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

Configuration Update config/packages/deviscoding_propel.yaml (or create it) with your database connection:

deviscoding_propel:
    dbal:
        connections:
            default:
                wrapper_class: Propel\Runtime\Connection\ConnectionWrapper
                params:
                    dsn: 'mysql:host=localhost;dbname=your_db'
                    user: 'your_user'
                    password: 'your_password'

First Use Case Generate a model from an existing database table:

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

Then generate a CRUD controller:

php bin/console propel:generate:crud User

Implementation Patterns

Model Generation & Management

Schema Updates Modify your database schema, then regenerate models:
```
php bin/console propel:model:build --no-confirmation
```
Use --write-sql to preview SQL changes before applying them:
```
php bin/console propel:model:build --write-sql
```

Querying Data Use Propel’s QueryBuilder for type-safe queries:

use App\Models\UserQuery;

$users = UserQuery::create()
    ->filterByActive(true)
    ->find();

Relationships Define relationships in YAML (e.g., schema.xml) and leverage Propel’s lazy-loading:
```
$user = UserQuery::create()->findPk(1);
$posts = $user->getPosts(); // Lazy-loaded collection
```

Integration with Symfony

Forms Use Propel’s ModelForm for seamless form integration:

use Propel\Runtime\Form\ModelForm;

$form = ModelForm::createForm(User::class, $user);

Validation Define validation rules in schema.xml or use Propel’s built-in validators:

<column name="email" type="VARCHAR" size="255" required="true">
    <validator type="email" message="Invalid email format" />
</column>

Events & Listeners Subscribe to Propel events (e.g., postSave) in Symfony’s EventDispatcher:

$dispatcher->addListener('propel.post_save', function ($event) {
    // Handle post-save logic
});

Workflows

Database-First Development
- Design schema → Generate models → Build application logic.
- Use propel:model:diff to compare schema changes:
```
php bin/console propel:model:diff
```
Test-Driven Propel
- Write tests against Propel models (e.g., using PHPUnit).
- Use transactions to roll back data after tests:
```
$connection = Propel::getConnection();
$connection->beginTransaction();
// Test logic
$connection->rollBack();
```
Migration Strategy
- For schema changes, use Propel’s propel:model:build with --write-sql to generate migration scripts manually.

Gotchas and Tips

Common Pitfalls

PHP 7.x/Symfony 3.x Compatibility
- Some Propel 1.x features may behave differently in PHP 7.x. Test thoroughly, especially with:
  - Closures in queries (use createCallable() for anonymous functions).
  - Deprecated Propel::getConnection() (prefer dependency injection).
- Example fix for closures:
```
$query->filterById(Propel::createCallable(function ($id) {
    return $id > 10;
}));
```
Caching Issues
- Propel caches query results and metadata. Clear caches after schema changes:
```
php bin/console cache:clear
```
- Disable caching during development (set propel.runtime.conf.cache_enabled = false in app/config/properties.ini).
Relationship Loading
- Avoid N+1 queries by using withColumn() or eager-loading:
```
$users = UserQuery::create()->withColumn('Posts')->find();
```

Transaction Handling

Propel 1.x transactions may not play well with Symfony’s DoctrineBridge. Use Propel’s native transactions:

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

Debugging Tips

Enable Propel Logging Add to config/packages/monolog.yaml:

handlers:
    propel:
        type: stream
        path: "%kernel.logs_dir%/propel.log"
        level: debug
        channels: ["propel"]

Then configure Propel to use the channel in app/config/properties.ini:

propel.logger = PropelLogger
propel.logger.level = debug

SQL Query Inspection Enable SQL logging in app/config/properties.ini:
```
propel.logger.sql = true
```
Schema Validation Validate your schema before generating models:
```
php bin/console propel:model:validate
```

Extension Points

Custom Query Classes Extend Propel\Runtime\ActiveQueryModel to add reusable query methods:

class UserQuery extends \BaseUserQuery {
    public function activeOnly() {
        return $this->filterByActive(true);
    }
}

Behavior Classes Use Propel’s behavior system (e.g., Timestampable, Sluggable) via schema.xml:

<behavior name="timestampable">
    <parameter name="column_create" value="created_at" />
    <parameter name="column_update" value="updated_at" />
</behavior>

Event Listeners Create custom listeners for Propel events (e.g., postInsert, preUpdate):

class UserListener {
    public function postInsert($event) {
        $user = $event->getObject();
        // Custom logic
    }
}

propel.behaviors.User.post_insert = [UserListener, postInsert]

Configuration Quirks

Connection Management Ensure your Symfony database_url in .env matches the Propel connection config. Example:
```
DATABASE_URL="mysql://user:pass@localhost/db_name"
```
Propel will use this for its default connection unless overridden.
Case Sensitivity Propel 1.x is case-sensitive for column/table names. Stick to lowercase or configure case-insensitive queries:
```
UserQuery::create()->setFormatter(ModelCriteria::FORMAT_PHPCAS);
```

Legacy Propel 1.x Features Some features (e.g., Propel::getSingle()) are deprecated. Use alternatives:

// Instead of:
$user = Propel::getSingle(UserQuery::create()->findPk(1));

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

Propel1 Bundle Laravel Package