Twig Awesome Bundle Laravel Package

Getting Started

Install via Composer:

composer require derrabus/twig-awesome-bundle

Register the bundle in your config/bundles.php:

Derrabus\TwigAwesomeBundle\DerrabusTwigAwesomeBundle::class => ['all' => true],

Ensure your project meets PHP 8.4 and Symfony 8.0+ requirements (v5.0.0 drops Symfony 7 and FontAwesome 6 support). First use case: Render FontAwesome 7 icons in Twig templates:

{{ icon('fa-solid fa-user', { class: 'text-blue-500' }) }}

Implementation Patterns

Core Workflow

1. Icon Registration: Define icons in config/twig_awesome.php (e.g., fa-solid, fa-regular prefixes).
2. Twig Integration: Use the icon() Twig function to render icons with custom classes/attributes:

   {{ icon('fa-brands fa-github', { size: '2x', aria_label: 'GitHub' }) }}
   

3. Dynamic Loading: Lazy-load icons via icon() to avoid bloating initial JS/CSS.

Advanced Patterns

• Custom Icon Sets: Extend the bundle by adding new icon sets in a service provider:

  $this->container->get('twig_awesome.icon_sets')->addSet('my-icons', [
      'home' => 'path/to/my-icon.svg',
  ]);
  

• Asset Optimization: Use Symfony’s asset mapper to bundle icons efficiently:

  # config/packages/twig_awesome.yaml
  assets:
      enabled: true
      version: 'v1'
  

Gotchas and Tips

Breaking Changes (v5.0.0)

• PHP 8.4 Required: Upgrade PHP or use v4.6.0 for older versions.
• Symfony 7 Dropped: Migrate to Symfony 8+ (e.g., update symfony/* packages).
• FontAwesome 6 Removed: Switch to FontAwesome 7 (update fontawesome/free-* packages).

Debugging

• Missing Icons: Verify config/twig_awesome.php includes the correct icon sets (e.g., fa-solid, fa-brands).
• Twig Errors: Clear cache (php bin/console cache:clear) if icon() function fails.
• Asset Loading: Check public/build/ for compiled icons if using assets.enabled: true.

Extension Points

• Override Defaults: Publish the config:

  php bin/console config:dump-reference DerrabusTwigAwesomeBundle | grep twig_awesome
  

• Custom Filters: Add Twig filters to modify icon output:

  $twig->addFilter(new \Twig\TwigFilter('icon_modifier', function ($icon) { ... }));
  

• Testing: Use TwigAwesomeBundleTest traits for PHPUnit (requires PHPUnit 12.5+):

  use Derrabus\TwigAwesomeBundle\Tests\Twig\IconFunctionTestCase;
  

Performance

• Icon Subsetting: Use FontAwesome’s web tool to generate minimal CSS/JS bundles.
• Cache Icons: Set assets.version to a hash of your icon set to leverage browser caching.