Propel1 Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation:

   composer require propel/propel1
   

   Propel1 requires manual schema configuration (unlike Propel2, which is more modern). Start by defining your database schema in an XML file (e.g., schema.xml) in config/propel/schema/.

2. First Use Case: Generate a base model and CRUD operations via CLI:

   vendor/bin/propel-gen model build
   vendor/bin/propel-gen sql build
   vendor/bin/propel-gen convert --output=app/Models
   

   This creates PHP classes for your tables (e.g., UserQuery, UserPeer).

3. Basic Query:

   use Models\UserQuery;
   
   $users = UserQuery::create()->find();
   foreach ($users as $user) {
       echo $user->getName();
   }
   

4. Database Connection: Configure config/propel/propel.ini with your Laravel .env credentials (e.g., dsn=mysql:host=127.0.0.1;dbname=laravel).

Implementation Patterns

Workflows

1. Schema-First Development:

   • Define your schema in XML first, then generate models. Modify the schema and regenerate models as needed:

     vendor/bin/propel-gen model build
     vendor/bin/propel-gen convert
     

2. Querying Data:

   • Criteria API (recommended for complex queries):

     $criteria = new Criteria();
     $criteria->add(UserPeer::NAME, 'John', Criteria::EQUAL);
     $users = UserPeer::doSelect($criteria);
     

   • Query Objects (fluent interface):

     $users = UserQuery::create()
         ->filterByName('John')
         ->find();
     

3. Relationships:

   • Propel handles relationships (e.g., hasMany, belongsTo) via generated methods:

     $user = UserQuery::create()->findOneById(1);
     $posts = $user->getPosts(); // Assuming a hasMany relationship
     

4. Transactions:

   use Propel\Runtime\Connection\ConnectionManager;
   
   $conn = ConnectionManager::getConnection('default');
   $conn->beginTransaction();
   try {
       // Business logic
       $conn->commit();
   } catch (\Exception $e) {
       $conn->rollBack();
   }
   

5. Integration with Laravel:

   • Use Propel’s Peer classes alongside Laravel’s service container:

     $this->app->bind('propel.connection', function () {
         return ConnectionManager::getConnection('default');
     });
     

Integration Tips

1. Migrations: Propel1 lacks built-in migrations. Use Laravel’s migrations to alter the database, then update the XML schema manually and regenerate models.

2. Validation: Propel1 doesn’t include validation rules. Use Laravel’s built-in validation or extend Propel’s BaseObject to add custom logic.

3. Caching: Enable Propel’s query caching in propel.ini:

   propel.query.cache.enabled = true
   propel.query.cache.lifetime = 3600
   

4. Events: Extend Propel’s BaseObject to trigger Laravel events:

   class User extends BaseUser {
       public function save() {
           event(new UserSaved($this));
           return parent::save();
       }
   }
   

Gotchas and Tips

Pitfalls

1. Outdated Ecosystem:

   • Propel1 is abandoned (last release: 2019). Avoid for new projects; consider Propel2 or Eloquent.
   • No Laravel-specific integrations (e.g., no propel:install artisan command).

2. XML Schema Rigidity:

   • Schema changes require manual XML edits and regeneration. Use tools like propel:diff-schema sparingly—it’s not foolproof.
   • Tip: Back up your XML schema before major changes.

3. Naming Conflicts:

   • Propel generates Peer and Query classes that may clash with Laravel’s autoloading. Exclude them from PSR-4 autoloading in composer.json:

     "autoload-exclude": ["app/Models/*Peer.php", "app/Models/*Query.php"]
     

4. Lazy Loading:

   • Propel1 loads relationships lazily by default. Eager-load related data to avoid N+1 queries:

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

5. Connection Management:

   • Propel1 uses its own connection handling. Override Laravel’s default connection if needed:

     $conn = ConnectionManager::getConnection('default');
     // Use $conn directly instead of DB facade
     

Debugging

1. SQL Logging: Enable Propel’s debug mode in propel.ini:

   propel.logger.level = debug
   

   Logs appear in storage/logs/propel.log.

2. Common Errors:

   • "Table [table] does not exist": Regenerate models after schema changes.
   • Class not found: Clear Composer’s cache (composer dump-autoload) and regenerate models.
   • Stale schema: Delete app/Models/ and regenerate if the schema XML is updated.

Extension Points

1. Custom Behavior: Extend Propel’s BaseObject to add Laravel-specific logic:

   class User extends BaseUser {
       public function getFullName() {
           return "{$this->getFirstName()} {$this->getLastName()}";
       }
   }
   

2. Plugins: Propel1 supports plugins (e.g., for behaviors). Example: Add a SoftDelete trait to BaseObject.

3. Custom Query Methods: Add static methods to Query classes for reusable queries:

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

Performance Tips

1. Batch Operations: Use doBulkInsert() or doBulkUpdate() for bulk operations instead of loops.

2. Indexing: Define indexes in your XML schema to optimize queries:

   <table name="users">
       <column name="email" type="VARCHAR" size="255" primaryKey="true" />
       <index name="idx_email">
           <column name="email" />
       </index>
   </table>
   

3. Avoid find() in Loops: Cache results or use iterate() for large datasets:

   UserQuery::create()->find()->each(function ($user) {
       // Process user
   });