Doctrine2 Exporter Laravel Package

Getting Started

Minimal Steps to Begin

1. Install the Package

   composer require --dev mysql-workbench-schema-exporter/doctrine2-exporter
   

   This installs both the exporter and its dependency (mysql-workbench-schema-exporter).

2. Locate the CLI Tool The exporter is available at:

   vendor/bin/mysql-workbench-schema-export
   

3. First Use Case: Export a .mwb File to Doctrine YAML

   vendor/bin/mysql-workbench-schema-export \
     --input=path/to/schema.mwb \
     --output=app/config/doctrine/Entity.yaml \
     --format=doctrine2-yaml \
     --entityNamespace=App\Entity
   

Where to Look First

• Configuration Options: Focus on the Doctrine 2.0 YAML/Annotation setup options to align with your project’s needs.
• Model Comments: Review the model comment behavior for fine-tuning relations (e.g., {d:unidirectional}true).
• CLI Documentation: Refer to the parent package’s CLI docs for input/output handling.

Implementation Patterns

Core Workflow: Exporting .mwb to Doctrine Entities

1. Define Configuration Use a config/doctrine-exporter.php file to centralize settings:

   return [
       'format' => 'doctrine2-annotation',
       'entityNamespace' => 'App\Entity',
       'bundleNamespace' => 'AppBundle',
       'useAutomaticRepository' => true,
       'nullableAttribute' => 'auto',
       'quoteIdentifierStrategy' => 'auto',
       'generateExtendableEntity' => false,
   ];
   

2. Integrate into Build Process Add a script to package.json or composer.json to auto-generate entities on post-install:

   {
     "scripts": {
       "post-install-cmd": "php vendor/bin/mysql-workbench-schema-export --input=db/schema.mwb --output=src/Entity --format=doctrine2-annotation --config=config/doctrine-exporter.php"
     }
   }
   

3. Leverage Model Comments for Custom Logic Annotate tables/foreign keys in MySQL Workbench to override defaults:

   {d:unidirectional}true{/d:unidirectional}  // Force unidirectional relation
   {d:cascade}persist,remove{/d:cascade}      // Custom cascade rules
   

Integration Tips

• Symfony Projects: Place generated entities in src/Entity and update config/packages/doctrine.yaml to auto-discover them.

  doctrine:
      orm:
          mappings:
              App:
                  is_bundle: false
                  dir: '%kernel.project_dir%/src/Entity'
                  prefix: 'App\Entity'
                  alias: App
  

• ZF2 Projects: Use the doctrine2-annotation-zf2 formatter to generate input filter classes alongside entities.

• CI/CD Pipelines: Trigger exports in GitHub Actions/GitLab CI to sync .mwb changes with code:

  - name: Export Doctrine Entities
    run: php vendor/bin/mysql-workbench-schema-export --input=db/latest.mwb --output=src/Entity --format=doctrine2-annotation
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • Issue: Generated entities may clash with existing classes if entityNamespace isn’t unique.
   • Fix: Use a sub-namespace (e.g., App\Generated\Entity) and exclude generated files from autoloading via composer.json:

     "autoload-exclude": ["src/Generated/**"]
     

2. Reserved Keywords in Identifiers

   • Issue: Columns/tables named after PHP/Doctrine keywords (e.g., class, table) may break parsing.
   • Fix: Enable quoteIdentifierStrategy: always in config or rename identifiers in MySQL Workbench.

3. Many-to-Many Guessing

   • Issue: The exporter auto-detects M2M tables but may misclassify them.
   • Fix: Add {d:m2m}false to table comments for false positives.

4. Annotation vs. YAML

   • Issue: YAML output lacks type hints and modern Doctrine features (e.g., GeneratedValue strategies).
   • Tip: Prefer doctrine2-annotation for new projects.

Debugging

• Dry Runs: Use --dry-run to preview output without writing files:

  vendor/bin/mysql-workbench-schema-export --input=schema.mwb --format=doctrine2-annotation --dry-run
  

• Verbose Logging: Enable debug mode for detailed parsing logs:

  vendor/bin/mysql-workbench-schema-export --debug
  

• Partial Exports: Export specific tables using --tables=table1,table2 to isolate issues.

Extension Points

1. Custom Formatters Extend the exporter by creating a new formatter class (e.g., for XML or PHP arrays) by implementing MysqlWorkbenchSchemaExporter\FormatterInterface.

2. Post-Processing Hooks Use Symfony’s EventDispatcher or a custom script to modify generated files:

   // Example: Add a timestamp to all entities
   $entities = file_get_contents('src/Entity/User.php');
   $entities = preg_replace('/class User/', 'class User { public function getCreatedAt() { return new \DateTime(); }', $entities);
   file_put_contents('src/Entity/User.php', $entities);
   

3. Template Overrides Replace default Doctrine annotations/templates by extending the Doctrine2AnnotationFormatter class and overriding methods like generateProperty().

Configuration Quirks

• generatedValueStrategy: Set to AUTO (Doctrine default) or explicitly define (e.g., IDENTITY, SEQUENCE).

  'generatedValueStrategy' => 'SEQUENCE',
  

• extendsClass: Use to enforce a base entity (e.g., App\Entity\BaseEntity) for shared methods:

  'extendsClass' => 'App\Entity\BaseEntity',
  

• propertyTypehint: Enable for stricter typing (PHP 7.4+):

  'propertyTypehint' => true,
  

  Outputs:

  /** @ORM\ManyToOne(targetEntity="App\Entity\User") */
  private ?User $owner = null;