Fontawesome Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   • Add the bundle to composer.json:

     "require": {
         "bmatzner/fontawesome-bundle": "~4.7"
     }
     

   • Run composer update bmatzner/fontawesome-bundle.
   • Enable the bundle in AppKernel.php:

     new Bmatzner\FontAwesomeBundle\BmatznerFontAwesomeBundle(),
     

   • Install assets:

     php app/console assets:install web --symlink
     

2. First Use Case:

   • Include the CSS in your base template (e.g., base.html.twig):

     <link rel="stylesheet" href="{{ asset('bundles/bmatznerfontawesome/css/font-awesome.min.css') }}">
     

   • Use an icon in a Twig template:

     <i class="fa fa-user"></i>
     

3. Where to Look First:

   • Bundle Docs: Check the FontAwesome documentation for icon classes.
   • Twig Integration: Use Twig’s asset() function to reference the bundle’s assets.
   • Debugging: Verify assets are installed in web/bundles/bmatznerfontawesome/.

Implementation Patterns

Common Workflows

1. Dynamic Icon Loading:

   • Use Twig extensions or custom filters to dynamically generate icon classes (e.g., for localization or dynamic icons):

     {% set iconClass = 'fa-' ~ (isAdmin ? 'user-secret' : 'user') %}
     <i class="{{ iconClass }}"></i>
     

2. Asset Management:

   • Symlinking: Prefer --symlink in assets:install to avoid duplication.
   • Custom Paths: Override asset paths in config.yml if needed (though the bundle doesn’t expose this natively).

3. Integration with Twig:

   • Macros: Create reusable Twig macros for common icon patterns:

     {% macro icon(name, size='lg') %}
         <i class="fa fa-{{ name }} fa-{{ size }}"></i>
     {% endmacro %}
     

     Usage:

     {{ _self.icon('user', '2x') }}
     

4. JavaScript Integration:

   • Include FontAwesome JS (if needed) via asset():

     <script src="{{ asset('bundles/bmatznerfontawesome/js/font-awesome.min.js') }}"></script>
     

5. Versioning:

   • Pin the bundle version in composer.json to avoid breaking changes (e.g., ~4.7.0).

Best Practices

• Consistency: Use the same icon naming convention across templates (e.g., fa-{icon-name}).
• Performance: Load only necessary icons via FontAwesome’s CSS subsetting (requires manual CSS file generation).
• Fallbacks: Provide fallback text or images for users with disabled CSS/JS.

Gotchas and Tips

Pitfalls

1. Asset Paths:

   • Issue: Hardcoding paths like /bundles/bmatznerfontawesome/ may break if the bundle is renamed or moved.
   • Fix: Always use {{ asset() }} in Twig to generate correct paths dynamically.

2. Outdated Version:

   • Issue: The bundle is archived and uses FontAwesome v4.7.0 (released in 2016). Newer versions (v5/v6) require a different bundle (e.g., fortawesome/font-awesome-bundle).
   • Workaround: Fork the bundle or manually integrate FontAwesome assets.

3. Asset Installation:

   • Issue: Forgetting to run assets:install after composer update will break icon rendering.
   • Fix: Add a post-update script in composer.json:

     "scripts": {
         "post-update-cmd": "php bin/console assets:install web --symlink"
     }
     

4. Twig Autoloading:

   • Issue: If using custom Twig extensions, ensure the bundle is loaded before your extensions to avoid ClassNotFound errors.

Debugging Tips

1. Missing Icons:

   • Verify the CSS file is loaded (check browser DevTools → Network tab).
   • Ensure icon classes match FontAwesome’s official list.

2. Symlink Issues:

   • If using --symlink, ensure the web directory is writable:

     chmod -R 775 web/
     

3. Caching:

   • Clear Symfony cache after updates:

     php app/console cache:clear
     

Extension Points

1. Custom Icons:

   • Add custom icons by extending the CSS file or using FontAwesome’s SVG with JS approach.

2. Twig Extensions:

   • Create a custom Twig filter to generate icon HTML:

     // src/YourBundle/Twig/IconExtension.php
     class IconExtension extends \Twig_Extension {
         public function getFilters() {
             return [
                 new \Twig_SimpleFilter('icon', [$this, 'renderIcon']),
             ];
         }
         public function renderIcon($name, $size = 'lg') {
             return '<i class="fa fa-' . $name . ' fa-' . $size . '"></i>';
         }
     }
     

     Usage in Twig:

     {{ 'user'|icon('2x') }}
     

3. Integration with Other Bundles:

   • Combine with knplabs/knp-paginator-bundle for paginator icons:

     <i class="fa fa-{{ knp_pagination.hasPrevious ? 'chevron-left' : 'ban' }}"></i>
     

4. Localization:

   • Use Twig’s trans filter to localize icon tooltips:

     <i class="fa fa-user" title="{{ 'user.profile'|trans }}"></i>