Bricks Custom Acme Demo Angular Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require 20steps/bricks-custom-acme-demo-angular-bundle
   

   Ensure your composer.json includes "20steps/bricks-custom-acme-demo-angular-bundle": "^1.0" under require.

2. Publish Assets Run the bundle’s asset publisher (if applicable):

   php artisan vendor:publish --provider="20steps\BricksCustomAcmeDemoBundle\BricksCustomAcmeDemoBundle" --tag=public
   

   Check resources/views/vendor/bricks-demo/ for Angular templates or directives.

3. First Use Case: Embedding Angular in Laravel Blade Add the bundle’s Angular entry point to your Blade template:

   @include('bricks-demo::angular-entry')
   

   This typically loads the Angular module and initializes it with Laravel’s API endpoints (e.g., /api/auth).

Implementation Patterns

Workflows

1. Laravel-Angular API Integration

   • Use Laravel’s API routes (routes/api.php) to expose endpoints consumed by Angular services.
   • Example:

     Route::get('/api/data', [DataController::class, 'index']);
     

   • Angular services (e.g., DataService) call these endpoints via $http.get('/api/data').

2. Blade + Angular Hybrid Views

   • Use @verbatim or @once directives to embed Angular components in Blade:

     @verbatim
     <app-dashboard></app-dashboard>
     @endverbatim
     

   • Ensure the Angular module declares the component (app-dashboard) in its entryComponents.

3. Dynamic Configuration

   • Pass Laravel data to Angular via window.Laravel (global JS object):

     // In Laravel (Blade)
     <script>
       window.Laravel = {!! json_encode(['csrfToken' => csrf_token()]) !!};
     </script>
     

   • Access in Angular:

     const csrfToken = window.Laravel.csrfToken;
     

4. Service Communication

   • Share Laravel services with Angular via a shared interface (e.g., AuthService):

     // Angular
     @Injectable()
     export class AuthService {
       login(credentials: any) {
         return this.http.post('/api/login', credentials);
       }
     }
     

   • Register the service in Angular’s providers array.

Integration Tips

• Webpack/Mix: If the bundle includes Webpack config, extend webpack.mix.js to bundle Angular assets:

  mix.js('resources/js/bricks-demo/app.module.ts', 'public/js')
     .angular()
     .version();
  

• Authentication: Use Laravel Sanctum/Passport for API auth. Angular services should include the token in headers:

  this.http.post('/api/login', { email, password }, { withCredentials: true });
  

• State Management: Pair with NgRx or Laravel’s session for shared state (e.g., user auth).

Gotchas and Tips

Pitfalls

1. Asset Loading Order

   • Ensure Angular’s runtime scripts load after jQuery/Prototype (if used) to avoid $ is not defined errors.
   • Use Blade @stack directives to manage script ordering:

     @stack('scripts')
     

     // In a layout file
     @push('scripts')
       <script src="{{ asset('js/bricks-demo.bundle.js') }}"></script>
     @endpush
     

2. CSRF Token Mismatch

   • Angular’s $http requests must include the CSRF token. Use a request interceptor:

     // Angular HTTP Interceptor
     intercept(req: HttpRequest<any>, next: HttpHandler) {
       const token = window.Laravel.csrfToken;
       req = req.clone({ setHeaders: { 'X-CSRF-TOKEN': token } });
       return next.handle(req);
     }
     

3. Route Conflicts

   • Avoid naming Laravel routes (e.g., /dashboard) that conflict with Angular routes. Use Laravel’s prefix or Angular’s pathLocationStrategy.

4. Dependency Hell

   • If the bundle relies on specific Angular versions (e.g., v6+), ensure your package.json matches:

     "dependencies": {
       "@angular/core": "^12.0.0",
       "@angular/common": "^12.0.0"
     }
     

Debugging

• Console Errors: Check browser console for ERROR Error: ... messages. Common causes:
  • Missing Angular modules (ModuleNotFoundError).
  • Undefined Laravel variables (window.Laravel is undefined).
• Network Tab: Verify API endpoints return 200 OK and CORS headers (Access-Control-Allow-Origin).

Extension Points

1. Custom Directives Extend the bundle’s Angular directives by creating a child module:

   @NgModule({
     declarations: [CustomDirective],
     imports: [BricksDemoModule],
     exports: [CustomDirective]
   })
   export class CustomBricksModule {}
   

   Register it in app.module.ts.

2. Laravel Service Providers Bind Angular-specific services to Laravel’s container:

   // In a ServiceProvider
   $this->app->singleton('angular.auth', function () {
       return new AngularAuthService();
   });
   

   Access via app('angular.auth') in controllers.

3. Configuration Overrides Publish the bundle’s config and override defaults:

   php artisan vendor:publish --tag=bricks-demo-config
   

   Modify config/bricks-demo.php (e.g., API base URL).

4. Testing

   • Use Laravel’s Http facade to test API endpoints:

     $response = $this->getJson('/api/data');
     $response->assertStatus(200);
     

   • Test Angular components with TestBed in a separate test suite.