Html Extra Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project:

   composer require twig/html-extra
   

   Register the extension in your Twig environment (e.g., in app/Providers/AppServiceProvider):

   use Twig\Extra\Html\HtmlExtension;
   
   public function boot()
   {
       $twig = $this->app['twig'];
       $twig->addExtension(new HtmlExtension());
   }
   

2. First Use Case Use the data_uri filter to embed small files (e.g., icons) directly in HTML:

   <img src="{{ 'path/to/image.png'|data_uri }}">
   

   Outputs:

   <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...">
   

Implementation Patterns

Common Workflows

1. Dynamic Class Handling Use html_classes to conditionally apply classes:

   <div class="{{ 'btn'|html_classes({'primary': isPrimary, 'disabled': isDisabled}) }}">
       Click Me
   </div>
   

   Outputs:

   <div class="btn primary">Click Me</div>
   

2. Class Variant Abstraction Leverage html_cva for consistent variant patterns (e.g., buttons):

   {% set button = 'btn'|html_cva({
       'primary': 'bg-blue-500 text-white',
       'secondary': 'bg-gray-200 text-gray-800',
       'size': {
           'sm': 'px-2 py-1 text-sm',
           'md': 'px-4 py-2'
       }
   }) %}
   
   <button class="{{ button('primary', 'md') }}">
       Submit
   </button>
   

   Outputs:

   <button class="btn bg-blue-500 text-white px-4 py-2">Submit</button>
   

3. Inline SVG/Data URIs Embed SVGs or small assets without extra HTTP requests:

   <div style="background-image: url('{{ 'icon.svg'|data_uri }}')"></div>
   

Integration Tips

• Laravel Blade: Use Twig templates alongside Blade by configuring twig facade or embedding Twig in Blade:

  @twig('partials/_button.twig', {'text': 'Save'})
  

• Form Helpers: Combine with Laravel Collective or Livewire for dynamic classes:

  <input type="text" class="{{ 'form-input'|html_classes({'error': hasError}) }}">
  

• Tailwind CSS: Pair html_cva with Tailwind’s utility classes for rapid theming.

Gotchas and Tips

Pitfalls

1. Data URI Size Limits

   • Browsers enforce max sizes (~1MB for most). Avoid embedding large files.
   • Debug with {{ 'file.png'|data_uri|length }} to check size.

2. Twig Extension Registration

   • Ensure the extension is added before rendering templates. Override boot() in AppServiceProvider if needed.

3. CVA Object Serialization

   • html_cva returns a Cva object. Always call it as a function (e.g., {{ button('variant') }}), not as a standalone object.

Debugging

• Class Output: Use {{ 'btn'|html_classes({...})|dump }} to inspect generated classes.
• Data URI Validation: Test with {{ 'file.png'|data_uri|raw }} to verify base64 encoding.

Extension Points

1. Custom Filters/Functions Extend the package by creating a custom Twig extension:

   use Twig\TwigFunction;
   
   $twig->addFunction(new TwigFunction('custom_html', function($input) {
       return (new HtmlExtension())->getFunction('html_classes')($input);
   }));
   

2. Laravel Mix/Webpack Pre-process data_uri in assets for critical CSS/JS:

   // webpack.mix.js
   mix.postCss('resources/css/app.css', 'public/css', [
       require('postcss-data-uri')({ extensions: ['svg'] })
   ]);
   

3. Performance Cache data_uri results for static assets:

   {% cache 'data_uri_icon' %}
       {{ 'icon.svg'|data_uri }}
   {% endcache %}