Symfony Favicons Webpack Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require black-forest/symfony-favicons-webpack-bundle
   

   Add to config/bundles.php:

   BlackForest\SymfonyFaviconsWebpackBundle\BlackForestSymfonyFaviconsWebpackBundle::class => ['all' => true],
   

2. Webpack Configuration Ensure your webpack.config.js includes the FaviconPlugin:

   const FaviconPlugin = require('favicon-webpack-plugin');
   
   module.exports = {
       plugins: [
           new FaviconPlugin('./public/assets/images/favicon.png')
       ]
   };
   

3. First Use Case Place your favicon.png (or .ico) in public/assets/images/, then run:

   yarn build
   

   Verify generated files in /public/build/favicon.ico and related assets.

Implementation Patterns

Symfony Integration

• Asset Management Use Symfony’s AssetComponent to reference generated favicons:

  <link rel="icon" href="{{ asset('build/favicon.ico') }}">
  

  For dynamic paths, inject AssetMapperInterface:

  $faviconPath = $assetMapper->getUrl('build/favicon.ico');
  

• Environment Awareness Configure different favicons per environment (e.g., dev vs. prod) via config/packages/black_forest_symfony_favicons_webpack.yaml:

  black_forest_symfony_favicons_webpack:
      source: '%kernel.project_dir%/public/assets/images/favicon_%env(APP_ENV)%.png'
  

Workflow

1. Development

   • Use APP_ENV=dev to auto-generate favicons with debug metadata (e.g., timestamps).
   • Leverage Webpack’s watch mode for live updates:

     yarn watch
     

2. Production

   • Minify favicons by setting optimize: true in webpack.config.js:

     new FaviconPlugin('./public/assets/images/favicon.png', {
         optimize: true,
         inject: true
     })
     

   • Cache busting: Append ?v={{ hash('sha256', 'favicon') }} to <link> tags.

3. CI/CD

   • Add favicon generation to your build pipeline (e.g., GitHub Actions):

     - run: yarn build
     - run: php bin/console assets:install public
     

Gotchas and Tips

Pitfalls

• Missing Source File If favicon.png is missing, Webpack fails silently. Fix: Validate the path in webpack.config.js and add error handling:

  if (!fs.existsSync('./public/assets/images/favicon.png')) {
      throw new Error('Favicon source file not found!');
  }
  

• Symfony Cache Invalidation After changing favicon paths, clear Symfony’s cache:

  php bin/console cache:clear
  

• Webpack 5+ Compatibility The bundle assumes Webpack 4’s publicPath. For Webpack 5, update webpack.config.js:

  output: {
      publicPath: '/build/',
      assetModuleFilename: 'assets/[name][ext]'
  }
  

Tips

• Custom Output Path Override the default /build/ output in webpack.config.js:

  new FaviconPlugin('./src/Resources/images/favicon.ico', {
      logo: './src/Resources/images/logo.png',
      outputPath: '../public/custom-favicons/'
  });
  

• Multiple Favicons Generate multiple formats (e.g., .ico, .png, .svg) using FaviconPlugin’s icons option:

  new FaviconPlugin('./public/assets/images/favicon.png', {
      icons: {
          apple: true,
          android: true,
          yandex: true
      }
  });
  

• Debugging

  • Webpack Errors: Check yarn build --verbose for plugin-specific logs.
  • Symfony Twig: Use {{ dump(asset('build/favicon.ico')) }} to debug paths in templates.
  • Bundle Config: Validate config/packages/black_forest_symfony_favicons_webpack.yaml with:

    php bin/console debug:config black_forest_symfony_favicons_webpack
    

• Extension Points

  • Post-Processing: Hook into Symfony’s kernel.terminate event to log favicon generation:

    use Symfony\Component\HttpKernel\KernelEvents;
    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
    
    class FaviconSubscriber implements EventSubscriberInterface {
        public static function getSubscribedEvents() {
            return [KernelEvents::TERMINATE => 'logFavicon'];
        }
    
        public function logFavicon() {
            if (file_exists($this->getParameter('kernel.project_dir').'/public/build/favicon.ico')) {
                // Log success or trigger notifications
            }
        }
    }