Getting Started

Minimal Setup

Installation:
```
composer require alexandermatveev/fontawesome-bundle
```
Ensure your project uses Symfony 3.x (compatible with Symfony 4/5 via legacy mode if needed).

Enable the Bundle: Add to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

return [
    // ...
    Alexandermatveev\FontawesomeBundle\AlexandermatveevFontawesomeBundle::class => ['all' => true],
];

First Use Case:

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

<link href="{{ asset('bundles/alexandermatveevfontawesome/css/all.min.css') }}" rel="stylesheet">

Render an Icon: Use the <i> tag with Font Awesome classes:

<i class="fas fa-check-circle"></i>  {Solid style}
<i class="far fa-circle"></i>       {Regular style}
<i class="fal fa-ban"></i>         {Light style (if included)}

Verify Assets: Check the public/bundles/alexandermatveevfontawesome/ directory for the bundled CSS/JS files.

Implementation Patterns

Workflows

Dynamic Icon Selection: Use Twig logic to toggle icon styles (solid/regular/light) based on conditions:

{% set iconClass = status === 'success' ? 'fas fa-check' : 'fas fa-times' %}
<i class="{{ iconClass }}"></i>

Asset Optimization:
- Lazy-Loading: Load all.min.css only on pages needing icons (e.g., admin dashboards).
- Custom Builds: Replace the bundle’s all.min.css with a Font Awesome webkit for reduced payload.

Integration with UI Components:

Buttons: Combine with Bootstrap/Tailwind:

<button class="btn btn-primary">
  <i class="fas fa-download mr-2"></i> Download
</button>

Forms: Use icons for validation feedback:

<div class="input-group">
  <input type="email" class="form-control">
  <div class="input-group-append">
    <span class="input-group-text"><i class="fas fa-envelope"></i></span>
  </div>
</div>

SVG Replacement: For dynamic colors/sizes, use the SVG version (not bundled by default):
```
<script src="https://kit.fontawesome.com/a076d05319.js" crossorigin="anonymous"></script>
```
Then use <i> tags or the SVG API.

Advanced Patterns

Twig Extension for Icons: Create a custom Twig function to generate icons programmatically:

// src/Twig/FontAwesomeExtension.php
class FontAwesomeExtension extends \Twig\Extension\AbstractExtension
{
    public function getFunctions()
    {
        return [
            new \Twig\TwigFunction('fontawesome_icon', [$this, 'renderIcon']),
        ];
    }

    public function renderIcon(string $style, string $icon, array $options = [])
    {
        $class = $style === 'solid' ? 'fas' : ($style === 'regular' ? 'far' : 'fal');
        $attrs = '';
        foreach ($options as $key => $value) {
            $attrs .= sprintf(' %s="%s"', $key, $value);
        }
        return sprintf('<i class="%s fa-%s"%s></i>', $class, $icon, $attrs);
    }
}

Usage:

{{ fontawesome_icon('solid', 'user', {'style': 'color: red;', 'title': 'Profile'}) }}

Asset Versioning: Append a version query string to the CSS link to bypass cache:

<link href="{{ asset('bundles/alexandermatveevfontawesome/css/all.min.css?v='~'1.0') }}" rel="stylesheet">

Theming: Override the CSS by extending the bundle’s stylesheet in your assets:

// assets/css/app.scss
@import '~@fortawesome/fontawesome-free/css/all';
.fa-user {
  color: #2c3e50;
}

Gotchas and Tips

Pitfalls

Outdated Version:
- The bundle ships Font Awesome 5.3.1 (released 2018). For newer icons/styles, use the official webkit or update the bundle’s assets manually.
- Fix: Replace public/bundles/alexandermatveevfontawesome/css/all.min.css with the latest from Font Awesome’s CDN.

Missing Light (Thin) Icons: The bundle includes Free 5.3.1, which lacks the "light" (fal) style. Add it manually:

# Download the light style separately
wget https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css -O public/bundles/alexandermatveevfontawesome/css/all.min.css

Asset Path Changes: If you move the public/bundles/ directory, update the Twig template paths:
```
<link href="{{ asset('custom/path/to/fontawesome/css/all.min.css') }}" rel="stylesheet">
```
License Compliance: The bundle includes Font Awesome Free (MIT license). Avoid mixing with Pro icons without a license.
Symfony 4/5 Compatibility: The bundle targets Symfony 3.x. For newer versions:
- Use symfony/flex to manage assets.
- Replace the bundle with dama/doctrine-test-bundle (for testing) or manually include Font Awesome via CDN.

Debugging Tips

Broken Icons:
- Check the browser’s Network tab to ensure all.min.css loads (404 = wrong path).
- Verify the <i> tag has the correct class (e.g., fas fa-user vs. fa-user).

Cache Issues: Hard-refresh with Ctrl+F5 or append a cache-buster:

<link href="{{ asset('bundles/.../all.min.css?t='~now()) }}" rel="stylesheet">

Console Errors: If the bundle throws errors, check:
- PHP version (>=5.3.0 is ancient; upgrade to >=7.4).
- Symfony kernel compatibility (use symfony/flex for auto-config).

Extension Points

Custom Icon Sets: Override the default all.min.css by:
- Extending the bundle’s Resources/public/ directory.
- Using a build tool (Webpack Encore) to merge custom icons.

Dynamic Icon Loading: Lazy-load icons via JavaScript:

// Load Font Awesome dynamically
const script = document.createElement('script');
script.src = 'https://kit.fontawesome.com/a076d05319.js';
script.crossOrigin = 'anonymous';
document.head.appendChild(script);

Twig Global Functions: Extend the bundle to add global Twig functions for icons (see Implementation Patterns).

Webpack Integration: For modern Symfony apps, replace the bundle with:

// webpack.config.js
Encore
  .addEntry('fontawesome', './node_modules/@fortawesome/fontawesome-free/css/all.min.css')
  .copyFiles({
    from: './node_modules/@fortawesome/fontawesome-free/webfonts',
    to: 'fonts/[path][name].[ext]',
  });

Fontawesome Bundle Laravel Package