Fontawesome Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (add to composer.json):

   {
       "require": {
           "ekyna/fontawesome-bundle": "0.1.*@dev"
       },
       "scripts": {
           "post-install-cmd": [
               "Ekyna\\FontAwesomeBundle\\Composer\\ScriptHandler::install"
           ],
           "post-update-cmd": [
               "Ekyna\\FontAwesomeBundle\\Composer\\ScriptHandler::install"
           ]
       }
   }
   

   Run composer update.

2. Register the Bundle in app/AppKernel.php:

   new Ekyna\FontAwesomeBundle\EkynaFontAwesomeBundle(),
   

3. Install Fonts (if not auto-installed):

   php app/console ekyna:fontawesome:install
   

4. First Use Case: Include FontAwesome in a Twig template via Assetic:

   {% stylesheets output='css/backend.css' %}
       'bundles/ekynafontawesome/css/font-awesome.min.css'
   {% endstylesheets %}
   

Implementation Patterns

Asset Integration

• Assetic Workflow: Use {% stylesheets %} blocks to bundle FontAwesome with other CSS:

  {% stylesheets
      'bundles/ekynafontawesome/css/font-awesome.min.css'
      'css/custom.css'
      output='css/all.css' %}
      <link rel="stylesheet" href="{{ asset_url }}">
  {% endstylesheets %}
  

  Enable configure_assetic: true in config.yml for auto-configuration.

• Dynamic Icon Loading: Use Twig’s asset() function for icons:

  <i class="fa fa-user"></i>
  <img src="{{ asset('bundles/ekynafontawesome/fonts/fontawesome-webfont.eot') }}">
  

Configuration Overrides

• Custom Output Directory:

  ekyna_fontawesome:
      output_dir: %kernel.root_dir%/../web/custom-fonts
  

  Re-run ekyna:fontawesome:install to copy fonts to the new location.

• Disable Assetic Auto-Config: Set configure_assetic: false if managing Assetic manually.

Icon Usage Patterns

• Solid/Brand Icons:

  <i class="fas fa-check-circle"></i>  {Solid}
  <i class="fab fa-github"></i>        {Brand}
  

  Ensure the bundle’s CSS includes the correct styles (may require manual inclusion of fontawesome-solid.min.css/fontawesome-brands.min.css).

• SVG Icons: Use the SVG version if installed:

  <img src="{{ asset('bundles/ekynafontawesome/svgs/solid/user.svg') }}">
  

Gotchas and Tips

Pitfalls

1. Outdated FontAwesome Version: The bundle uses FontAwesome v4 (last release 2015). For v5/v6, manually override assets or fork the bundle. Workaround: Replace vendor/fortawesome/font-awesome with a newer version and update paths in config.yml.

2. Assetic Conflicts: If configure_assetic: true causes issues, disable it and manually add:

   assetic:
       assets:
           fontawesome_css:
               inputs:
                   - 'bundles/ekynafontawesome/css/font-awesome.min.css'
   

3. Font Paths in Production: Ensure output_dir is set to a web-accessible path (e.g., web/fonts). Default ~ may cause 404s.

Debugging

• Missing Icons: Verify the CSS file is loaded (check browser DevTools). For v5+, ensure fontawesome-all.min.css is included instead of font-awesome.min.css.

• Console Command Failures: Run ekyna:fontawesome:install with --verbose to debug font copying:

  php app/console ekyna:fontawesome:install --verbose
  

Extension Points

1. Custom Icon Sets: Override the assets_dir to point to a local FontAwesome fork:

   ekyna_fontawesome:
       assets_dir: %kernel.root_dir%/../src/Resources/public/fontawesome-custom
   

2. Post-Install Scripts: Extend the ScriptHandler to add custom logic (e.g., symlink fonts):

   // src/Ekyna/FontAwesomeBundle/Composer/ScriptHandler.php
   public static function install() {
       // Default logic...
       self::symlinkFonts();
   }
   

3. Twig Extensions: Create a custom Twig function for icon shortcuts:

   {{ fontawesome_icon('user', 'fas') }}  {Renders <i class="fas fa-user"></i>}