App Integration Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require dontdrinkandroot/app-integration-bundle
   

   Add the bundle to config/bundles.php:

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

2. Basic Configuration Publish the default config:

   php bin/console dontdrink-and-root:install
   

   This generates:

   • API Platform resources (if not already present).
   • Angular PWA scaffolding in public/angular-pwa/.
   • A config/packages/dontdrink_and_root_app_integration.yaml file.

3. First Use Case: Quick API + PWA Setup

   • Ensure you have API Platform installed (api bundle).
   • Run migrations (php bin/console doctrine:migrations:migrate).
   • Serve the app:

     symfony serve
     

   • Navigate to http://localhost:8000/angular-pwa/ to see the pre-built Angular PWA shell.

Where to Look First

• Bundle Docs: Check README.md in the package repo for setup instructions and examples.
• Configuration: Review config/packages/dontdrink_and_root_app_integration.yaml for API/PWA settings.
• Generated Files:
  • config/packages/api_platform.yaml (auto-generated API Platform config).
  • public/angular-pwa/ (Angular PWA skeleton).
• Console Commands:

  php bin/console list dontdrink-and-root
  

  Key commands:
  • dontdrink-and-root:install: Sets up initial config.
  • dontdrink-and-root:generate:angular: Regenerates Angular assets (if modified).

Implementation Patterns

Workflow: API + PWA Development Loop

1. Define API Resources Create API Platform resources (e.g., src/Entity/Post.php with #[ApiResource]). The bundle auto-detects these and updates API Platform config.

2. Generate Angular Services Use the bundle’s CLI to scaffold Angular services for your API:

   php bin/console dontdrink-and-root:generate:angular:service --entity=Post
   

   This creates:

   • public/angular-pwa/src/app/services/post.service.ts (API client).
   • Mock data for development.

3. Integrate with Angular PWA

   • Extend the generated AppModule in public/angular-pwa/src/app/app.module.ts.
   • Use the auto-generated services to fetch data:

     this.postService.query().subscribe(posts => {
       this.posts = posts;
     });
     

4. Deploy Static Assets Build the Angular PWA:

   cd public/angular-pwa && npm run build
   

   Serve via Symfony’s assets component or a CDN.

Integration Tips

• API Platform Customization Override the auto-generated api_platform.yaml by extending the bundle’s config:

  # config/packages/api_platform.yaml
  imports:
      - { resource: "@DontDrinkAndRootAppIntegrationBundle/Resources/config/api_platform.yaml" }
  api_platform:
      formats:
          jsonld: { mime_types: ['application/ld+json'] }
          json:   { mime_types: ['application/json'] }
  

• Angular Customization The bundle provides a starter template. To customize:

  • Modify public/angular-pwa/src/app/app.component.html for global layouts.
  • Override public/angular-pwa/src/styles.scss for theming.
  • Use ng generate inside the Angular project for new components.

• Authentication The bundle supports API Platform’s api_token auth by default. For JWT:

  # config/packages/dontdrink_and_root_app_integration.yaml
  api_platform:
      auth:
          provider: jwt
  

  Then generate Angular auth services:

  php bin/console dontdrink-and-root:generate:angular:auth
  

• Environment-Specific Config Use Symfony’s parameter bags to switch between dev/prod PWA assets:

  # config/packages/dontdrink_and_root_app_integration.yaml
  angular_pwa:
      base_path: '%env(ANGULAR_PWA_BASE_PATH)%'
  

  Set ANGULAR_PWA_BASE_PATH in .env.

Gotchas and Tips

Pitfalls

1. Auto-Generated Config Overwrites

   • The dontdrink-and-root:install command overwrites api_platform.yaml. Back up your config first or extend it as shown above.
   • Fix: Use imports to merge configs instead of replacing.

2. Angular Dependency Conflicts

   • The bundle includes a fixed version of Angular CLI/tools. Upgrading Angular manually may break builds.
   • Fix: Use npm install inside public/angular-pwa/ only after checking compatibility.

3. CORS Issues

   • The bundle doesn’t auto-configure CORS for local development. Add this to config/packages/nelmio_cors.yaml:

     paths:
         '^/api/':
             allow_origin: ['*']
             allow_methods: ['GET', 'POST', 'PUT', 'DELETE']
             allow_headers: ['*']
             max_age: 3600
     

4. Hot-Reloading Angular

   • The bundle doesn’t set up Angular’s dev server. Use:

     cd public/angular-pwa && npm run start
     

   • Proxy API requests in public/angular-pwa/proxy.conf.json:

     {
       "/api": {
         "target": "http://localhost:8000",
         "secure": false
       }
     }
     

Debugging

1. API Platform Issues

   • Check the auto-generated api_platform.yaml for typos or missing resources.
   • Use bin/console debug:api to inspect resources.

2. Angular Build Errors

   • Run npm run build -- --verbose for detailed errors.
   • Clear Symfony’s cache after Angular changes:

     php bin/console cache:clear
     

3. Console Command Failures

   • Ensure api bundle is installed (composer require api).
   • Run commands with --verbose for debug output:

     php bin/console dontdrink-and-root:install --verbose
     

Extension Points

1. Custom Angular Modules Override the default Angular module by creating a custom one and updating public/angular-pwa/src/app/app.module.ts:

   import { CustomModule } from './custom.module';
   @NgModule({
     imports: [
       // Replace default imports with CustomModule
       CustomModule,
     ],
   })
   export class AppModule {}
   

2. Dynamic API Resource Detection Extend the bundle’s resource detector by implementing DontDrinkAndRoot\AppIntegrationBundle\Detector\ResourceDetectorInterface and tagging your service:

   services:
       App\Custom\ResourceDetector:
           tags: [dontdrink_and_root.resource_detector]
   

3. Post-Install Hooks Add logic after installation by creating a subscriber:

   use Symfony\Component\Console\Event\ConsoleEvents;
   use Symfony\Component\Console\Event\ConsoleTerminateEvent;
   
   class PostInstallSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               ConsoleEvents::TERMINATE => 'onPostInstall',
           ];
       }
   
       public function onPostInstall(ConsoleTerminateEvent $event) {
           if ($event->getCommand()->getName() === 'dontdrink-and-root:install') {
               // Custom logic here
           }
       }
   }
   

4. Asset Versioning Disable Angular’s default hashing for development:

   cd public/angular-pwa && npm run build -- --configuration=development
   

   Or configure in angular.json:

   "configurations": {
       "development": {
           "fileReplacements": [...],
           "outputHashing": "none"
       }
   }