Entity Angular Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require connectx/entity-angular-bundle in your Symfony 4 project root. If using Symfony Flex, the bundle auto-enables. For older setups, manually enable it in AppKernel.php.

2. First Generation Execute php bin/console cx:gen:ts in the project root. Generated Angular TypeScript files appear in /angular/ (created automatically).

3. Verify Output Check the generated files for:

   • Entity class names as TypeScript interfaces.
   • Properties mapped from Doctrine entity fields (e.g., id: number, name: string).
   • Basic CRUD method stubs (e.g., getId(), setName()).

First Use Case

Frontend Integration

• Copy generated .ts files to your Angular project’s src/app/models/ folder.
• Import the interfaces in your Angular components/services:

  import { User } from '../../models/User';
  

Implementation Patterns

Workflow Integration

1. Entity-Driven Development

   • Use the bundle as a code-generation step in your CI/CD pipeline (e.g., GitHub Actions) to keep Angular models in sync with Doctrine entities.
   • Trigger generation post-entity migration:

     # Example workflow step
     php bin/console doctrine:migrations:migrate
     php bin/console cx:gen:ts
     

2. Partial Generation

   • Override the default behavior by configuring the bundle in config/packages/cx_entity_angular.yaml:

     cx_entity_angular:
         output_dir: '%kernel.project_dir%/src/app/shared/models'
         entities:
             - App\Entity\User
             - App\Entity\Product
     

   • Exclude entities with annotations (if supported; check bundle docs).

3. Custom Templates

   • Extend the default TypeScript template by copying the bundle’s template files (located in vendor/connectx/entity-angular-bundle/Resources/templates/) to config/packages/cx_entity_angular/templates/ and modify them.

Angular-Specific Patterns

• Service Layer Abstraction Generate a base service interface alongside models:

  // Generated via custom template
  export interface UserService {
    getUsers(): Observable<User[]>;
    saveUser(user: User): Observable<User>;
  }
  

  Implement this in Angular with HttpClient.

• Form Integration Use generated interfaces with Angular’s FormBuilder:

  this.userForm = this.fb.group({
    id: [null],
    name: ['', Validators.required]
  });
  

• API Response Handling Map API responses to generated interfaces:

  this.http.get<User[]>('/api/users').subscribe(users => {
    this.users = users;
  });
  

Gotchas and Tips

Pitfalls

1. Outdated Dependencies

   • The bundle was last updated in 2019 and targets PHP 5+ and Symfony 4. Test thoroughly with:
     • PHP 7.4+ (recommended).
     • Symfony 5/6 (may require patches; check issues).
   • Workaround: Fork the repo and update dependencies (e.g., symfony/console, doctrine/orm).

2. Namespace Collisions

   • Generated files use the entity’s fully qualified class name as the TypeScript interface name (e.g., AppEntityUser).
   • Fix: Customize the template to use shorter names (e.g., User) or configure output paths per namespace.

3. Circular Dependencies

   • If entities reference each other (e.g., User has ManyToOne to Role), the generated files may fail to compile.
   • Solution: Manually adjust imports or generate files in a specific order.

4. No Angular-Specific Features

   • The bundle generates plain TypeScript interfaces without:
     • Decorators (@Input(), @Output()).
     • Angular-specific metadata (e.g., serializedName for JSON serialization).
   • Tip: Post-process files with a script or use a custom template.

Debugging

• Check Generation Logs Run with -vvv for verbose output:

  php bin/console cx:gen:ts -vvv
  

  Look for skipped entities or template errors.

• Template Debugging Enable debug mode in config/packages/cx_entity_angular.yaml:

  cx_entity_angular:
      debug: true
  

  This may dump template variables to the console.

Extension Points

1. Custom Field Mappings

   • Override property types in the template. Example:

     {# Override default type mapping #}
     {% set typeMap = {
         'integer': 'number',
         'string': 'string',
         'datetime': 'Date',
         'array': 'any[]'
     } %}
     

2. Add Angular Decorators Modify the template to include decorators:

   export interface {{ interfaceName }} {
       {% for property in properties %}
       @Input() {{ property.name }}: {{ typeMap[property.type] }}{% if property.nullable %} | null{% endif %};
       {% endfor %}
   }
   

3. Pre/Post-Generation Hooks Use Symfony’s event system to run logic before/after generation. Example:

   // config/services.yaml
   services:
       App\EventSubscriber\AngularGenSubscriber:
           tags:
               - { name: kernel.event_subscriber }
   

   // src/EventSubscriber/AngularGenSubscriber.php
   namespace App\EventSubscriber;
   
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   use ConnectX\EntityAngularBundle\Event\PreGenerateEvent;
   
   class AngularGenSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               PreGenerateEvent::NAME => 'onPreGenerate',
           ];
       }
   
       public function onPreGenerate(PreGenerateEvent $event) {
           $event->addEntityExclusion('App\Entity\ExcludedEntity');
       }
   }
   

4. Symfony 5/6 Compatibility

   • Update composer.json to require newer Symfony components:

     "require": {
         "symfony/console": "^5.4|^6.0",
         "symfony/dependency-injection": "^5.4|^6.0"
     }
     

   • Patch the bundle’s EntityAngularGenerator class to use modern DI.

Performance Tips

• Cache Generated Files Add a cache-busting timestamp to imports to avoid unnecessary rebuilds:

  import { User } from '../../models/User?v=20230515';
  

• Exclude Non-CRUD Entities Configure the bundle to skip entities not used in the frontend:

  cx_entity_angular:
      entities:
          - App\Entity\User
          - App\Entity\Product
      exclude:
          - App\Entity\AuditLog