Pwa Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require disjfa/pwa-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Disjfa\PwaBundle\DisjfaPwaBundle::class => ['all' => true],
   ];
   

2. Configure .env Set the public path for PWA assets:

   PWA_PUBLIC_PATH=/pwa-assets
   

3. Copy Default Icon

   cp vendor/disjfa/pwa-bundle/Resources/public/pwa-icon.png public/pwa-assets/
   

4. Include Meta Tag in Twig Add to your base template (e.g., base.html.twig):

   {{ include('@DisjfaPwa/meta.html.twig') }}
   

5. Verify Output Visit your site in Chrome DevTools (Application > Manifest) to confirm the manifest.json and icons are generated.

First Use Case: Basic PWA Setup

For a quick PWA implementation:

• Use the default pwa-icon.png as a placeholder.
• Customize colors and metadata via config/packages/disjfa_pwa.yaml.
• Test the PWA with:

  php bin/console cache:clear
  

Implementation Patterns

Core Workflow

1. Configuration Define PWA settings in config/packages/disjfa_pwa.yaml:

   disjfa_pwa:
       favicon: /pwa-assets/pwa-icon.png
       background_color: '#ffffff'
       theme_color: '#3498db'
       name: 'My App'
       short_name: 'App'
       start_url: '/'
       display: 'standalone'
   

   • Dynamic Values: Use Twig variables (e.g., {{ app.name }}) for dynamic metadata.

2. Icon Generation

   • Place icons (e.g., icon-192x192.png) in public/pwa-assets/.
   • The bundle auto-generates manifest.json with references to these icons.
   • Pro Tip: Use liip_imagine filters (configured in config/packages/disjfa_pwa.yaml) to resize icons on-the-fly.

3. Routing Add PWA routes in config/routes/disjfa_pwa.yaml:

   disjfa_pwa:
       resource: '@DisjfaPwaBundle/Controller/'
       type: annotation
   

   • Ensures /manifest.json and icon endpoints are accessible.

4. Twig Integration

   • Include the meta tag in your layout:

     {% block head %}
         {{ parent() }}
         {{ include('@DisjfaPwa/meta.html.twig') }}
     {% endblock %}
     

   • Override templates (e.g., meta.html.twig) in templates/bundles/DisjfaPwa/ for customization.

Advanced Patterns

1. Dynamic Manifest Extend the DisjfaPwaBundle to fetch metadata from a service:

   // src/Service/PwaManifestService.php
   class PwaManifestService {
       public function getManifestData(): array {
           return [
               'name' => $this->appNameService->getName(),
               'theme_color' => $this->themeService->getColor(),
           ];
       }
   }
   

   Override the bundle’s ManifestController to use this service.

2. Multi-Language Support Use Symfony’s translation system to localize manifest.json:

   # config/packages/disjfa_pwa.yaml
   disjfa_pwa:
       name: '%app.name%'
       short_name: '%app.short_name%'
   

   Define translations in translations/messages.en.yaml:

   app:
       name: 'My App'
       short_name: 'App'
   

3. Service Worker Integration While the bundle doesn’t include a service worker, pair it with Workbox or Laravel Mix for offline support.

Gotchas and Tips

Common Pitfalls

1. Missing Public Path

   • Error: PWA_PUBLIC_PATH not set in .env causes 404s for icons/manifest.
   • Fix: Always define PWA_PUBLIC_PATH (e.g., /pwa-assets).

2. Icon Size Requirements

   • Issue: Chrome ignores icons not matching PWA spec sizes.
   • Fix: Provide icons for 192x192, 512x512, etc., or use liip_imagine to resize dynamically.

3. Caching Headers

   • Problem: Browsers cache manifest.json aggressively, causing stale PWA installs.
   • Solution: Add cache-busting to the manifest URL:

     <link rel="manifest" href="{{ path('disjfa_pwa_manifest', {'version': app.version}) }}">
     

4. Twig Template Overrides

   • Gotcha: Overriding meta.html.twig requires the file to exist in templates/bundles/DisjfaPwa/.
   • Tip: Use {{ include('@DisjfaPwa/meta.html.twig') }} with ignore_missing: true to avoid errors during development.

Debugging Tips

1. Validate manifest.json Use Google’s Manifest Validator or Chrome DevTools (Application > Manifest) to check for errors.

2. Check Routes Run php bin/console debug:router | grep disjfa_pwa to verify PWA routes are registered.

3. Log Configuration Dump the bundle’s config for debugging:

   use Disjfa\PwaBundle\DisjfaPwaBundle;
   dump($this->container->getParameter('disjfa_pwa'));
   

Extension Points

1. Custom Manifest Controller Extend the bundle’s ManifestController to add logic:

   // src/Controller/CustomManifestController.php
   class CustomManifestController extends \Disjfa\PwaBundle\Controller\ManifestController {
       public function manifestAction() {
           $data = parent::manifestAction();
           $data['custom_field'] = 'value';
           return $this->json($data);
       }
   }
   

   Override the route in config/routes/disjfa_pwa.yaml:

   disjfa_pwa_manifest:
       path: /manifest.json
       controller: App\Controller\CustomManifestController::manifestAction
   

2. Event Listeners Hook into the bundle’s lifecycle (e.g., modify manifest data before generation):

   // src/EventListener/PwaManifestListener.php
   class PwaManifestListener implements KernelEventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               KernelEvents::CONTROLLER => 'onKernelController',
           ];
       }
   
       public function onKernelController(ControllerEvent $event) {
           $controller = $event->getController();
           if ($controller instanceof \Disjfa\PwaBundle\Controller\ManifestController) {
               // Modify $controller's manifest data here
           }
       }
   }
   

3. Asset Management Use Symfony’s AssetComponent to version PWA assets:

   <link rel="manifest" href="{{ asset('manifest.json', {'version': '1.0.0'}) }}">
   

Performance Tips

1. Optimize Icons Use liip_imagine to generate optimized icons:

   liip_imagine:
       filter_sets:
           pwa_192x192:
               quality: 85
               filters:
                   - resize: { width: 192, height: 192, mode: outbound }
   

   Reference in disjfa_pwa.yaml:

   disjfa_pwa:
       icons:
           - /pwa-assets/icon.png
           - /pwa-assets/icon@2x.png
   

2. Preload Manifest Add to your HTML <head>:

   <link rel="preload" href="/manifest.json" as="manifest">
   

3. Lazy-Load Non-Critical Icons Defer loading non-critical icons (e.g., splash screens) until after the page loads:

   if ('serviceWorker' in navigator) {
       window.addEventListener('load', () => {
           navigator.serviceWorker.register('/sw.js').then(() => {
               // Load icons after SW registration
               const icon = new Image();
               icon.src = '/pwa-assets/splash.png';
           });
       });
   }