Propel Schema Converter Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require creonit/propel-schema-converter-bundle
   

   Register the bundle in config/bundles.php (Laravel) or AppKernel.php (Symfony):

   Creonit\PropelSchemaConverterBundle\CreonitPropelSchemaConverterBundle::class => ['all' => true],
   

2. First Schema File: Create config/propel/schema.yml (or src/YourBundle/Resources/config/schema.yml for bundle-specific schemas):

   config:
     database:
       name: default
       namespace: App\Models
       package: src/Models
   

3. Generate Models:

   php bin/console propel:schema:convert
   

   This generates schema.xml in the same directory.

4. Build Models/Migrations:

   php bin/console propel:build --no-confirm
   

First Use Case: Quick Table Definition

Define a simple users table in schema.yml:

users:
  id: integer ~pk
  name: varchar(255)
  email: varchar(255) ~uniq
  created_at: timestamp

Run propel:schema:convert and propel:build to generate models and migrations.

Implementation Patterns

Schema Organization

1. Modular Schema Files: Split schemas by domain (e.g., users.yml, products.yml) and merge them in a root schema.yml:

   # config/propel/schema.yml
   import:
     - { resource: "users.yml" }
     - { resource: "products.yml" }
   

2. Reusable Config Blocks: Define shared configurations (e.g., config/database.yml) and include them:

   config:
     +: { resource: "database.yml" }
     namespace: App\Models\Users
   

Workflows

1. Schema-First Development:

   • Define schema in YAML → Generate schema.xml → Build models.
   • Use propel:schema:diff to compare changes before migrations:

     php bin/console propel:schema:diff --write-sql
     

2. Behavior Integration: Attach Propel behaviors (e.g., timestampable, sortable) directly in YAML:

   users:
     +behavior:
       - timestampable
       - sortable: { column: name }
   

3. Foreign Key Relationships: Define relationships declaratively:

   orders:
     user_id: int ~fk:users.id
     product_id: int ~fk:products.id
   

4. Migration Generation: Use propel:migrate:diff to generate migrations from schema changes:

   php bin/console propel:migrate:diff --write-sql > migrations/20230101000000_create_users.sql
   

Integration Tips

1. Laravel-Specific:

   • Place schema files in config/propel/ and update config/propel.php to point to the bundle.
   • Use Laravel’s service container to bind Propel’s Manager:

     $this->app->bind('propel.manager', function () {
         return Propel::getConnectionManager()->getConnection('default')->getManager();
     });
     

2. Testing:

   • Use PropelTestCase for database-agnostic tests:

     use Creonit\PropelSchemaConverterBundle\Tests\PropelTestCase;
     
     class UserTest extends PropelTestCase {
         public function testUserCreation() {
             $user = new User();
             $user->setName('Test');
             $user->save();
             $this->assertEquals(1, UserQuery::create()->count());
         }
     }
     

3. CI/CD:

   • Add propel:build to your deployment script to ensure schemas are up-to-date.
   • Use propel:schema:validate to catch schema issues early:

     php bin/console propel:schema:validate
     

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Ensure namespace in config matches your actual model directory (e.g., App\Models).
   • If using bundles, prefix namespaces (e.g., AppBundle\Model).

2. Behavior Misconfiguration:

   • Behaviors like timestampable require specific column names (e.g., created_at, updated_at). Mismatches cause runtime errors.
   • Validate behaviors with propel:schema:validate:

     php bin/console propel:schema:validate --behaviors
     

3. Foreign Key Syntax:

   • Incorrect foreign key syntax (e.g., ~fk:table.column) may not generate proper constraints. Use:

     user_id: int ~fk:users.id(onDelete: CASCADE)
     

4. YAML Parsing Errors:

   • Indentation matters in YAML. Use a linter (e.g., yamllint) to catch issues early.
   • Avoid special characters in table/column names (e.g., -, +). Use underscores instead.

5. Schema Overwrites:

   • Running propel:schema:convert overwrites schema.xml. Back up or use version control for this file.

Debugging

1. Dry Runs: Use --dry-run to preview changes:

   php bin/console propel:schema:convert --dry-run
   

2. Log Output: Enable verbose mode for detailed logs:

   php bin/console propel:build -vvv
   

3. SQL Generation: Generate SQL without executing to verify migrations:

   php bin/console propel:migrate:diff --write-sql > migration.sql
   

Tips

1. Partial Updates: Use propel:schema:convert --only=table_name to regenerate a single table’s schema.

2. Custom Types: Extend Propel’s types by defining custom mappings in config/propel.php:

   'types' => [
       'json' => ['class' => 'Propel\Runtime\Connection\ConnectionInterface::TYPE_VARCHAR'],
   ],
   

3. Environment-Specific Schemas: Override schemas per environment (e.g., schema.dev.yml, schema.prod.yml) and load them conditionally:

   # config/propel/schema.yml
   config:
     +: { resource: "schema.${APP_ENV}.yml" }
   

4. IDE Support:

   • Use PHPStorm’s Propel plugin for autocompletion and navigation.
   • Generate PHPDoc blocks for models to enable IDE hints:

     php bin/console propel:build --write-doc
     

5. Performance:

   • For large schemas, pre-generate schema.xml in CI to avoid runtime conversion.
   • Use propel:build --no-confirm in scripts to skip interactive prompts.

6. Extending the Bundle:

   • Override the converter service to add custom logic:

     # config/services.yaml
     Creonit\PropelSchemaConverterBundle\Converter\YamlSchemaConverter:
       arguments:
         $customLogic: '@your.custom_service'