Angular Integration Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dontdrinkandroot/angular-integration-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       DontDrinkAndRoot\AngularIntegrationBundle\DontDrinkAndRootAngularIntegrationBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Create a config file at config/packages/dont_drink_and_root_angular_integration.yaml:

   angular_integration:
       entry_point: 'dist/app'  # Path to your Angular entry JS file
       assets_path: '%kernel.project_dir%/public/dist'  # Angular build output
       enabled: true
   

3. First Use Case: Serve Angular Assets

   • Build your Angular app (ng build --prod).
   • Place built files in public/dist.
   • Clear Symfony cache:

     php bin/console cache:clear
     

   • Access your Angular app via Symfony’s public URL (e.g., http://your-app.dev/dist/index.html).

Implementation Patterns

Workflow: Angular + Symfony Hybrid App

1. Routing Integration Use Symfony’s Router to proxy API calls while letting Angular handle client-side routes:

   {# templates/base.html.twig #}
   <div id="app-root"></div>
   <script src="{{ asset(parameter('angular_integration.entry_point')) }}"></script>
   

2. API Endpoints Expose Symfony routes as REST APIs for Angular to consume:

   # config/routes.yaml
   api_users:
       path: /api/users
       controller: App\Controller\UserController::index
       methods: GET
   

3. Asset Management

   • Configure assets_path to match your Angular build output.
   • Use asset() Twig function to reference Angular files:

     <link rel="stylesheet" href="{{ asset('dist/styles.css') }}">
     

4. Environment-Specific Config Override config per environment (e.g., config/packages/dev/angular_integration.yaml):

   angular_integration:
       entry_point: 'dist/app.dev.js'  # Use non-minified for dev
   

5. Webpack Encore Integration If using Encore, sync build paths with assets_path:

   // webpack.config.js
   Encore.setOutputPath('public/dist/');
   

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear Symfony and Angular caches after changes:

     php bin/console cache:clear
     rm -rf public/dist/*  # Force rebuild Angular
     ng build --prod
     

   • Disable Symfony’s AppCache in config/packages/dev/framework.yaml if Angular routes conflict:

     framework:
         http_cache:
             enabled: false
     

2. Asset Path Conflicts

   • Ensure assets_path in config matches your Angular build output exactly.
   • Use absolute paths in Angular’s base href (e.g., <base href="/dist/">) to avoid 404s.

3. Route Collisions

   • Angular’s client-side routes (e.g., /dashboard) may conflict with Symfony’s server-side routes.
   • Fix: Use Symfony’s requirements to block non-API routes:

     # config/routes.yaml
     _angular_fallback:
         path: /{path}
         controller: App\Controller\AngularFallbackController::index
         requirements:
             path: .*
     

4. Debugging Angular in Symfony

   • Disable Symfony’s debug toolbar for Angular routes by checking request.getPathInfo() in a base controller:

     // src/Controller/BaseController.php
     public function isAngularRoute(Request $request): bool {
         return str_starts_with($request->getPathInfo(), '/dist/');
     }
     

Tips

1. Hot Module Replacement (HMR) For development, use webpack-dev-server alongside Symfony’s built-in server:

   symfony server:start --port=8000
   npm run start  # Angular CLI dev server on port 4200
   

   Proxy API calls in angular.json:

   "serve": {
       "options": {
           "proxyConfig": "proxy.conf.json"
       }
   }
   

2. Extension Points

   • Custom Entry Points: Override the entry_point config dynamically (e.g., per route):

     <script src="{{ asset(app.angular_integration.entry_point_for_route(request.get('_route'))) }}"></script>
     

   • Asset Versioning: Append a hash to Angular files to bust caches:

     angular_integration:
         assets_path: '%kernel.project_dir%/public/dist'
         version: '{{ hash("md5", "contents-of-version-file") }}'
     

     Then reference in Twig:

     <script src="{{ asset('dist/app.' ~ parameter('angular_integration.version') ~ '.js') }}"></script>
     

3. Performance

   • Enable Symfony’s HttpCache for API routes while letting Angular handle static assets.
   • Use Vary: Accept headers for API responses to optimize caching.

4. Testing

   • Test Angular routes via Symfony’s BrowserKit by simulating client-side navigation:

     $client = static::createClient();
     $client->request('GET', '/'); // Loads Angular entry point
     $client->getCrawler()->filter('#app-root')->assertCount(1);