Blade Boxicons Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mallardduck/blade-boxicons
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="MallardDuck\BladeBoxicons\BladeBoxiconsServiceProvider"
   

2. Basic Usage: Add the service provider to config/app.php under providers:

   MallardDuck\BladeBoxicons\BladeBoxiconsServiceProvider::class,
   

3. First Blade Usage:

   @boxicon('bxl-github', '2x')
   

   Renders a GitHub icon at 2x size.

4. Where to Look First:

   • Check the Boxicons documentation for icon names.
   • Review config/blade-boxicons.php for customization options (e.g., CDN paths, default sizes).
   • Inspect resources/views/vendor/blade-boxicons.blade.php (if published) for default templates.

Implementation Patterns

Common Workflows

1. Dynamic Icons with Variables:

   @boxicon($iconName, $size, ['class' => 'text-blue-500'])
   

   Pass variables for icons, sizes, or additional attributes.

2. Icon Sets: Use prefixes for different sets (e.g., bxl-, bx-, bxs-):

   @boxicon('bxs-user', 'lg')  <!-- Solid set -->
   @boxicon('bx-user', 'sm')   <!-- Regular set -->
   

3. Inline SVG Customization: Override default SVG attributes via the attributes parameter:

   @boxicon('bxl-laravel', 'md', [
       'fill' => 'currentColor',
       'aria-label' => 'Laravel'
   ])
   

4. Component Integration: Create reusable Blade components:

   @component('components.icon', ['name' => 'bxl-react', 'size' => '1.5x'])
   @endcomponent
   

5. Asset Optimization: Preload critical icons in your layout:

   @boxicon('bxl-github', '1x', ['preload' => true])
   

Integration Tips

• CSS Frameworks: Pair with Tailwind, Bootstrap, or custom CSS for styling:

  @boxicon('bxl-python', 'md', ['class' => 'text-green-600 hover:scale-110'])
  

• Dark Mode: Use CSS variables or classes for dynamic theming:

  @boxicon('bxl-moon', 'sm', ['class' => 'dark:text-yellow-300'])
  

• Accessibility: Add aria-hidden or labels for screen readers:

  @boxicon('bxl-search', 'sm', ['aria-label' => 'Search'])
  

Gotchas and Tips

Pitfalls

1. Icon Not Found:

   • Ensure the icon name matches Boxicons' naming convention.
   • Debug with:

     @boxicon('invalid-icon', 'sm')  <!-- Will output raw text if icon fails -->
     

   • Check storage/logs/laravel.log for missing icon warnings.

2. CDN Dependencies:

   • If using a custom CDN, verify the path in config/blade-boxicons.php:

     'cdn' => 'https://unpkg.com/boxicons@2.1.4',
     

   • Offline? Use the local asset option:

     'use_local_assets' => true,
     

3. Caching Issues:

   • Clear Blade cache after config changes:

     php artisan view:clear
     

   • For production, precompile assets:

     npm run prod
     

4. Size Limitations:

   • Supported sizes: 1x, 2x, 3x, 4x, 5x, 6x, 7x, 8x, 9x, 10x, sm, md, lg, xl.
   • Custom sizes require manual SVG scaling (not recommended for maintainability).

Debugging

• Inspect Output: Use @dd() to debug the rendered SVG:

  @boxicon('bxl-code', 'md', ['debug' => true])
  

• Check Config: Validate config/blade-boxicons.php for typos or misconfigurations.

Extension Points

1. Custom Icons: Extend the package by adding a custom-icons config array:

   'custom-icons' => [
       'my-icon' => '<svg>...</svg>',
   ],
   

   Usage:

   @boxicon('my-icon')
   

2. Blade Directives: Override the default directive in your service provider:

   Blade::directive('boxicon', function ($expression) {
       // Custom logic here
       return "<?php echo MallardDuck\BladeBoxicons\Facades\BladeBoxicons::render($expression); ?>";
   });
   

3. Asset Pipelines: Integrate with Laravel Mix/Vite for bundling:

   // vite.config.js
   import { defineConfig } from 'vite';
   import laravel from 'laravel-vite-plugin';
   import { createBoxiconsPlugin } from 'vite-plugin-boxicons';
   
   export default defineConfig({
       plugins: [
           laravel({
               input: ['resources/css/app.css', 'resources/js/app.js'],
           }),
           createBoxiconsPlugin(),
       ],
   });
   

4. Testing: Mock the facade in PHPUnit:

   $this->mock(BladeBoxicons::class)->shouldReceive('render')
       ->once()
       ->andReturn('<svg>Mock Icon</svg>');