Symfony Laravel Package

Getting Started

Minimal Steps

1. Install the Package

   composer require cnd-api-maker/symfony
   

   Ensure cnd-api-maker/core is also installed (required dependency).

2. Configure the Bundle Add the bundle to config/bundles.php:

   return [
       // ...
       Cnd\ApiMaker\Symfony\CndApiMakerBundle::class => ['all' => true],
   ];
   

3. Create a JDL File Define your entities and relationships in a .jdl file (e.g., src/main/resources/example.jdl):

   entity Employee {
     firstName String required
     lastName String required
   }
   

4. Generate Code Run the console command to generate entities, repositories, and optionally API Platform resources:

   php bin/console cnd:api-maker:generate --input=src/main/resources/example.jdl
   

5. Verify Output Check the generated files in src/Entity/, src/Repository/, and optionally src/ApiResource/ (if API Platform is enabled).

First Use Case

Generate a CRUD API for an Employee Entity

1. Create a JDL file with an Employee entity (as above).
2. Enable API Platform in config/packages/api_platform.yaml (if needed):

   api_platform:
       formats:
           jsonld:
               mime_types: ['application/ld+json']
   

3. Run the generator with API Platform support:

   php bin/console cnd:api-maker:generate --input=src/main/resources/example.jdl --with-api-platform
   

4. Access the API at /api/employees (or /api/employee if singular naming is configured).

Implementation Patterns

Workflows

1. Iterative Development with JDL

• Start Small: Begin with a minimal JDL file (e.g., 1-2 entities) and expand incrementally.
• Regenerate Safely: Use --overwrite to regenerate files without losing custom logic in non-generated blocks (e.g., add @ORM\GeneratedValue to an auto-increment field).

  php bin/console cnd:api-maker:generate --input=example.jdl --overwrite
  

2. API Platform Integration

• Enable Modules: Use --with-api-platform to generate API resources, DTOs, and filters.
• Customize Serialization: Extend generated ApiResource classes to add custom serialization groups or metadata:

  // src/ApiResource/EmployeeApiResource.php (generated)
  public function getOperations(EntityManagerInterface $manager): array
  {
      $reflection = new \ReflectionClass($this);
      return [
          new Get(),
          new Post(
              input: 'App\\ApiResource\\Dto\\EmployeeInput',
              output: $reflection->getName() . 'Output'
          ),
          // ...
      ];
  }
  

3. Fixtures and Tests

• Generate Fixtures: Use --with-fixtures to create Doctrine fixtures for testing:

  php bin/console cnd:api-maker:generate --input=example.jdl --with-fixtures
  

• Test Templates: Leverage generated PHPUnit tests in tests/Entity/ to bootstrap test suites.

4. Custom Generators

• Extend Templates: Override default templates by copying them from vendor/cnd-api-maker/symfony/templates to templates/cnd-api-maker in your project.
• Add New Generators: Implement custom generators by extending Cnd\ApiMaker\Core\Generator\AbstractGenerator and register them in the Symfony bundle’s configuration.

Integration Tips

Symfony Services

• Access the Generator Service: Inject Cnd\ApiMaker\Symfony\Generator\Generator to trigger generation programmatically:

  use Cnd\ApiMaker\Symfony\Generator\Generator;
  
  class MyCommand extends Command {
      public function __construct(private Generator $generator) {}
  
      protected function execute(InputInterface $input, OutputInterface $output): int {
          $this->generator->generateFromFile('path/to/file.jdl');
          return Command::SUCCESS;
      }
  }
  

Doctrine and API Platform

• Database Migrations: Run migrations after generation:

  php bin/console make:migration && php bin/console doctrine:migrations:migrate
  

• API Platform Configuration: Customize api_platform.yaml to control:
  • Pagination (enable_pagination).
  • Security (resource_classes).
  • Formats (formats).

Event Listeners

• Post-Generation Hooks: Subscribe to cnd.api_maker.generate events to run custom logic after generation:

  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  use Cnd\ApiMaker\Symfony\Event\GenerateEvent;
  
  class MySubscriber implements EventSubscriberInterface {
      public static function getSubscribedEvents(): array {
          return [
              'cnd.api_maker.generate' => 'onGenerate',
          ];
      }
  
      public function onGenerate(GenerateEvent $event) {
          // Modify generated files or trigger side-effects
      }
  }
  

Gotchas and Tips

Pitfalls

1. Template Overrides

   • Issue: Custom templates in templates/cnd-api-maker may not be picked up if the bundle’s cache is not cleared.
   • Fix: Run php bin/console cache:clear after adding new templates.

2. API Platform Conflicts

   • Issue: Generating API Platform resources without api-platform/core installed will fail silently.
   • Fix: Ensure api-platform/core is required in composer.json if using --with-api-platform.

3. JDL Parsing Errors

   • Issue: Complex JDL syntax (e.g., nested relationships) may cause parsing errors.
   • Fix: Validate JDL using JDL Studio before generation.

4. Overwriting Custom Code

   • Issue: Regenerating files may overwrite manual changes in generated blocks.
   • Fix: Use @generated docblocks to mark auto-generated sections and avoid editing them:

     /**
      * @generated This code is auto-generated by Cnd API Maker. Do not edit manually.
      */
     

5. Doctrine Annotations vs. Attributes

   • Issue: The generator may use use Doctrine\ORM\Mapping as ORM; (annotations) instead of attributes (#[ORM\...]).
   • Fix: Configure the generator to use attributes in config/packages/cnd_api_maker.yaml:

     cnd_api_maker:
         use_attributes: true
     

Debugging

1. Verbose Output Enable debug mode for the generator:

   php bin/console cnd:api-maker:generate --input=example.jdl --debug
   

2. Dry Run Test generation without writing files:

   php bin/console cnd:api-maker:generate --input=example.jdl --dry-run
   

3. Log Generation Steps Enable Symfony’s debug toolbar to inspect the generator’s internal state during execution.

Tips

1. Partial Generations Use --entity to generate only specific entities:

   php bin/console cnd:api-maker:generate --input=example.jdl --entity=Employee
   

2. Environment-Specific Configs Override generator settings per environment (e.g., dev vs. prod) in config/packages/cnd_api_maker.yaml:

   when@dev:
       cnd_api_maker:
           with_fixtures: true
           with_tests: true
   

3. JDL Includes Reuse JDL snippets across projects by using include directives:

   include ../shared/jdl/common_entities.jdl
   entity Project {
       name String required
   }
   

4. Custom Naming Strategies Override default naming conventions (e.g., pluralization) by extending Cnd\ApiMaker\Core\Naming\NamingStrategy and configuring it in the bundle.

5. Performance For large JDL files, pre-compile templates to reduce generation time:

   php bin/console cnd:api-maker:compile-templates