Blade Mdi Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require postare/blade-mdi
   

   No additional configuration is required for basic usage.

2. First Use Case: Use the package in a Blade view by referencing an icon directly:

   <x-mdi-account />  <!-- Renders the account icon -->
   

   Or via the helper syntax (if available):

   @mdi('account')
   

3. Where to Look First:

   • Material Design Icons Website for icon names.
   • Blade UI Kit Demo for visual previews.
   • The package’s README for syntax details and updates.

Implementation Patterns

Usage Patterns

1. Blade Component Syntax (Recommended): Use the <x-mdi-* /> syntax for type safety and autocompletion:

   <x-mdi-home />
   <x-mdi-settings />
   

2. Dynamic Icons via Variables: Pass dynamic icon names using Blade variables:

   @php
     $iconName = 'account';
   @endphp
   <x-mdi-{{ $iconName }} />
   

3. Tailwind CSS Integration: Leverage the fill-current property for dynamic theming:

   <x-mdi-alert class="text-red-500" />
   

4. Icon Groups in Layouts: Centralize icon usage in a layout file (e.g., resources/views/layouts/app.blade.php):

   <div class="icon-group">
     <x-mdi-home class="icon" />
     <x-mdi-settings class="icon" />
   </div>
   

5. Livewire Component Icons: Use icons in Livewire components for interactive elements:

   <x-mdi-delete wire:click="deleteItem" class="cursor-pointer" />
   

Workflows

1. Icon Discovery Workflow:

   • Search for icons on Material Design Icons.
   • Validate availability in the package via Blade UI Kit.
   • Use the icon in Blade templates.

2. Theming Workflow:

   • Apply Tailwind classes to icons for dynamic theming:

     <x-mdi-star class="text-yellow-400 hover:text-yellow-500" />
     

   • Use CSS variables for global theming:

     .icon-primary { color: var(--primary-color); }
     

3. Asset Optimization Workflow:

   • Publish SVGs locally for customization:

     php artisan vendor:publish --provider="Postare\BladeMdi\BladeMdiServiceProvider" --tag="blade-mdi"
     

   • Optimize SVGs using tools like svgo or laravel-mix-svgo.

4. Testing Workflow:

   • Test icon rendering in Blade views:

     public function test_icon_renders()
     {
         $this->blade()->render('<x-mdi-home />')
             ->assertSee('<svg');
     }
     

   • Validate accessibility (e.g., ARIA labels, contrast).

Integration Tips

1. Laravel Mix/Vite Integration:

   • Ensure SVGs are processed by your build tool. Add to vite.config.js:

     export default defineConfig({
       assets: {
         include: ['resources/svg/**/*'],
       },
     });
     

2. Livewire Integration:

   • Use icons in Livewire components for interactive feedback:

     <button wire:click="save">
       <x-mdi-content-save class="mr-2" />
       Save
     </button>
     

3. Dark Mode Support:

   • Use Tailwind’s dark mode classes:

     <x-mdi-moon class="dark:text-gray-300" />
     

4. Custom Icon Aliases:

   • Override icon names in a config file (if supported) for project-specific aliases:

     'aliases' => [
       'home' => 'mdi-home',
     ],
     

5. Fallback for Missing Icons:

   • Provide a fallback icon or message if an icon is missing:

     @isset($iconName)
       <x-mdi-{{ $iconName }} />
     @else
       <x-mdi-alert class="text-gray-400" />
     @endisset
     

Gotchas and Tips

Pitfalls

1. Icon Name Mismatches:

   • Ensure icon names match exactly (e.g., mdi-account vs. account). Use the Blade UI Kit to verify names.

2. SVG Asset Loading:

   • If SVGs fail to load, check your asset pipeline (e.g., Vite/Laravel Mix) for misconfigured paths. Publish SVGs locally if needed:

     php artisan vendor:publish --tag="blade-mdi"
     

3. Tailwind Conflicts:

   • The fill-current property may conflict with Tailwind’s fill-* utilities. Use !important or custom CSS if needed:

     <x-mdi-star style="--tw-fill-opacity: 1;" class="text-yellow-500" />
     

4. Laravel 12 Compatibility:

   • Test thoroughly with Laravel 12’s new Blade features (e.g., @props). Report issues to the GitHub repo.

5. Caching Issues:

   • Clear Blade and asset caches after updates:

     php artisan view:clear
     php artisan cache:clear
     npm run dev
     

Debugging

1. Missing Icons:

   • Check the browser’s network tab to ensure SVGs are loaded. Verify the icon name exists in the package’s list.

2. Blade Syntax Errors:

   • Ensure the Blade component syntax is correct. Use php artisan blade:compile to debug:

     php artisan blade:compile --debug
     

3. SVG Rendering Issues:

   • Inspect the SVG in the browser’s dev tools. Ensure no CSS is overriding fill or stroke properties.

4. Performance Bottlenecks:

   • Use webpack-bundle-analyzer to check if SVGs are bloating your bundle:

     npm run build -- --analyze
     

Tips

1. Autocomplete Support:

   • Use IDE plugins (e.g., Laravel Blade snippets in VSCode) for autocompletion of icon names.

2. Icon Search Shortcut:

   • Bookmark the Blade UI Kit search page for quick icon lookups.

3. Dynamic Sizing:

   • Use Tailwind’s w-* and h-* classes for consistent icon sizing:

     <x-mdi-star class="w-6 h-6" />
     

4. Accessibility:

   • Add ARIA labels for screen readers:

     <x-mdi-alert aria-label="Warning" />
     

5. Customization:

   • Override SVG attributes in your Blade template:

     <x-mdi-home class="custom-icon" style="--icon-size: 24px" />
     

6. Contributing New Icons:

   • If you need an icon not in the package, fork the repo and run download.sh to add it:

     git clone https://github.com/postare/blade-mdi.git
     cd blade-mdi
     ./download.sh
     

7. Testing New Icons:

   • Test new icons in a staging environment before deploying to production. Use Laravel’s blade testing helpers:

     $this->blade()->render('<x-mdi-new-icon />')->assertSeeText('new-icon');
     

8. Laravel Mix Optimization:

   • Configure Laravel Mix to process SVGs:

     mix.setPublicPath('public')
       .svg('resources/svg/icons', 'public/svg', (path) => {
         return path.replace(/^resources\/svg/, '');
       });