Generate Ts Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require codebuds/ts-generator-bundle --dev
   

   Add the bundle to config/bundles.php if not auto-discovered:

   CodeBuds\TsGeneratorBundle\CodeBudsTsGeneratorBundle::class => ['dev' => true],
   

2. Basic Configuration Override defaults in config/packages/codebuds_ts_generator.yaml:

   codebuds_ts_generator:
       namespace: 'App\\Entity\\'
       interface_output_directory: '%kernel.project_dir%/assets/ts/interfaces'
       type_output_directory: '%kernel.project_dir%/assets/ts/types'
       enum_output_directory: '%kernel.project_dir%/assets/ts/enums'
       entity_input_directory: '%kernel.project_dir%/src/Entity'
   

3. First Use Case Run the generator via CLI:

   php bin/console codebuds:ts-generator:generate
   

   Verify output in assets/ts/ (default paths). For a single entity:

   php bin/console codebuds:ts-generator:generate --entity=User
   

Implementation Patterns

Core Workflows

1. Entity-to-TypeScript Pipeline

   • Scan & Generate: Use generate command to process all entities in entity_input_directory.
   • Incremental Updates: Add --force flag to regenerate all files or omit to skip unchanged entities.
   • Selective Generation: Target specific entities/classes with --entity=ClassName or --directory=path/to/Entity.

2. Integration with Build Tools

   • Webpack/Vite: Configure tsconfig.json to include generated paths:

     {
       "include": ["assets/ts/**/*"]
     }
     

   • Hot Reloading: Trigger generation via post-update-cmd in composer.json:

     "scripts": {
       "post-update-cmd": "php bin/console codebuds:ts-generator:generate --quiet"
     }
     

3. TypeScript Usage Patterns

   • Interfaces: Use generated interfaces in frontend services:

     interface User extends GeneratedUserInterface { ... } // Extend for custom props
     

   • Enums: Import generated enums directly:

     import { UserRole } from './enums/UserRole';
     

4. Custom Templates

   • Override default templates by copying vendor/codebuds/ts-generator-bundle/templates/ to config/codebuds/ts-generator/templates/ and modifying.

Gotchas and Tips

Common Pitfalls

1. Namespace Mismatches

   • Issue: Generated files use incorrect namespace if namespace config doesn’t match entity paths.
   • Fix: Use absolute paths in entity_input_directory (e.g., %kernel.project_dir%/src/Entity) and verify the namespace config matches your App\Entity root.

2. Circular Dependencies

   • Issue: Complex entity relationships (e.g., User ↔ Role ↔ Permission) may cause infinite loops in type generation.
   • Fix: Exclude problematic entities with --exclude=EntityName or adjust template logic to handle self-references.

3. File Overwrites

   • Issue: Manual edits to generated files are lost on regeneration.
   • Fix: Use --force sparingly; prefer extending generated types/interfaces in separate files.

4. Doctrine Proxy Classes

   • Issue: Proxy classes (e.g., __CG__\App\Entity\User) break generation.
   • Fix: Exclude proxy directories from entity_input_directory or filter them via custom logic in a service extension.

Debugging Tips

• Dry Run: Use --dry-run to preview changes without writing files.
• Verbose Output: Add -v to CLI commands for detailed scanning logs.
• Template Debugging: Enable debug: true in config to log template rendering:

  codebuds_ts_generator:
      debug: true
  

Extension Points

1. Custom Generators

   • Extend the bundle by creating a custom command or service that implements CodeBuds\TsGeneratorBundle\Generator\GeneratorInterface.
   • Example: Add support for generating React hooks from PHP services.

2. Service Overrides

   • Override the TsGenerator service to modify generation logic:

     # config/services.yaml
     CodeBuds\TsGeneratorBundle\Generator\TsGenerator:
         arguments:
             $customTemplatePath: '%kernel.project_dir%/custom/templates'
     

3. Event Listeners

   • Listen to codebuds.ts_generator.generate events to hook into the generation process:

     // src/EventListener/CustomTsGeneratorListener.php
     public function onGenerate(EntityEvent $event) {
         $event->getEntity()->addCustomProperty('frontendName', 'user');
     }
     

4. Configuration Overrides

   • Dynamically adjust paths/namespaces per environment:

     # config/packages/dev/codebuds_ts_generator.yaml
     codebuds_ts_generator:
         interface_output_directory: '%kernel.project_dir%/var/ts/interfaces'
     

Performance

• Exclude Directories: Use entity_input_directory to limit scanning to relevant paths (e.g., exclude tests/ or Migrations/).
• Cache Generated Files: Add generated files to .gitignore and regenerate only when PHP entities change (e.g., via post-autoload-dump in composer.json).