Propel1 Laravel Package

Getting Started

Minimal Setup

1. Installation Add Propel to your Laravel project via Composer:

   composer require dsdeboer/propel1
   

   Ensure your composer.json includes "propel/propel": "1.6.*" (or the latest stable version).

2. Schema Configuration Define your database schema in an XML file (e.g., schema.xml) under config/propel/schema/. Example:

   <database name="default" connection="mysql:host=localhost;dbname=test">
       <table name="users">
           <column name="id" type="INTEGER" primaryKey="true" autoIncrement="true" />
           <column name="name" type="VARCHAR" size="255" />
       </table>
   </database>
   

3. Build the Model Layer Generate Propel models from your schema:

   php vendor/bin/propel-gen build --config=config/propel/schema.xml
   

4. First Query Use Propel’s Query API in a Laravel controller or service:

   use Propel\Runtime\Connection\ConnectionManagerSingle;
   use Propel\Runtime\Propel;
   
   $users = UserQuery::create()->find();
   return response()->json($users);
   

Implementation Patterns

Integration with Laravel

1. Service Layer Abstraction Create a service class to encapsulate Propel queries:

   namespace App\Services;
   
   use Propel\Runtime\ActiveQuery\ModelCriteria;
   
   class UserService {
       public function getAllUsers(): array {
           return UserQuery::create()->find();
       }
   }
   

2. Dependency Injection Bind Propel’s ConnectionManager to Laravel’s IoC container in AppServiceProvider:

   public function register() {
       $this->app->singleton('propel.connection', function () {
           return ConnectionManagerSingle::getInstance();
       });
   }
   

3. Eloquent-like Facade Extend Laravel’s Facade to simplify Propel usage:

   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   
   class Propel extends Facade {
       protected static function getFacadeAccessor() {
           return 'propel.connection';
       }
   }
   

Common Workflows

1. CRUD Operations

   • Create:

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

   • Read:

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

   • Update:

     $user->setName('Updated Name')->save();
     

   • Delete:

     $user->delete();
     

2. Complex Queries Use Propel’s Criteria for filtering:

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

3. Transactions Wrap Propel operations in Laravel transactions:

   DB::transaction(function () {
       $user = new User();
       $user->setName('Alice')->save();
       // Additional Propel operations...
   });
   

4. Migrations Sync Propel schema with Laravel migrations by extending SchemaBuilder:

   Schema::create('users', function (Blueprint $table) {
       $table->increments('id');
       $table->string('name');
       // Propel-specific logic here
   });
   

Gotchas and Tips

Pitfalls

1. Schema Synchronization

   • Propel does not auto-generate migrations. Manually sync schema changes:

     php vendor/bin/propel-gen build --config=config/propel/schema.xml
     

   • Tip: Use propel-gen diff-schema to compare schema changes.

2. Lazy Loading Propel’s lazy loading can cause N+1 queries. Use withColumn() or join():

   $users = UserQuery::create()
       ->withColumn('UserProfile', 'ProfileQuery')
       ->find();
   

3. Connection Management Propel’s ConnectionManager may conflict with Laravel’s DB facade. Explicitly specify connections:

   ConnectionManager::getInstance()->setDefaultDSN('mysql:host=localhost;dbname=laravel_db');
   

4. Caching Queries Propel caches queries aggressively. Clear cache after schema changes:

   php vendor/bin/propel-gen build --clear-cache
   

Debugging

1. Query Logging Enable Propel’s debug mode in config/propel/runtime/propel.ini:

   propel.debug = true
   propel.log.level = debug
   

2. Common Errors

   • Table Not Found: Ensure schema.xml matches your database.
   • Column Not Found: Verify column names in schema.xml (Propel is case-sensitive).
   • Primary Key Issues: Define primaryKey="true" in schema.xml.

Extension Points

1. Custom Behavior Extend Propel’s BaseModel for reusable logic:

   namespace App\Models;
   
   use Propel\Runtime\ActiveRecord\ActiveRecordInterface;
   
   class BaseUser extends \BaseUser implements ActiveRecordInterface {
       public function isAdmin() {
           return $this->getRole() === 'admin';
       }
   }
   

2. Event Listeners Use Propel’s Peer classes to hook into lifecycle events:

   UserPeer::doSave($user);
   // Add custom logic before/after save
   

3. Validation Integrate Laravel’s validation with Propel:

   $validator = Validator::make($request->all(), [
       'name' => 'required|string',
   ]);
   if ($validator->fails()) {
       throw new \PropelException('Validation failed');
   }