Icons Laravel Package

Getting Started

1. Installation:

   composer require artisanpack-ui/icons
   php artisan vendor:publish --tag=artisanpack-package-config
   

2. First Use Case:

   • Place your SVG icons in resources/icons/[set-name]/ (e.g., resources/icons/fontawesome-pro/home.svg).
   • Configure the set in config/artisanpack/icons.php:

     'sets' => [
         'fa' => [
             'path' => resource_path('icons/fontawesome-pro'),
             'prefix' => 'fa',
         ],
     ],
     

   • Use in Blade:

     <x-icon-fa-home class="w-6 h-6" />
     

3. Where to Look First:

   • config/artisanpack/icons.php for configuration.
   • resources/icons/ for organizing your SVG files.
   • Extension API docs for event-driven registration.

Implementation Patterns

1. Config-Based Registration

• Workflow: Define icon sets in config/artisanpack/icons.php for static, project-wide icons.
• Example:

  'sets' => [
      'hero' => [
          'path' => resource_path('icons/heroicons'),
          'prefix' => 'hero',
      ],
      'custom' => [
          'path' => resource_path('icons/custom'),
          'prefix' => 'custom',
          'disk' => 's3', // Optional: Use a custom filesystem disk
      ],
  ],
  

• Use Case: Ideal for project-specific or third-party icons that don’t require dynamic registration.

2. Event-Driven Registration (for Packages)

• Workflow: Register icon sets programmatically via the ap.icons.register-icon-sets filter in a Service Provider or Event Listener.
• Example:

  // In a Service Provider's `boot()` method
  addFilter('ap.icons.register-icon-sets', function (IconSetRegistration $registry) {
      $registry->addSet(__DIR__ . '/../../resources/icons', 'mypackage');
      return $registry;
  });
  

• Use Case: Perfect for packages that bundle icons (e.g., admin dashboards, plugins) and want to auto-register them without user configuration.

3. Dynamic Icon Loading

• Workflow: Load icons conditionally based on user roles, features, or environment.
• Example:

  addFilter('ap.icons.register-icon-sets', function ($sets) {
      if (auth()->check() && auth()->user()->is_admin) {
          $sets[] = new IconSetRegistration(
              path: __DIR__ . '/../../resources/icons/admin',
              prefix: 'admin'
          );
      }
      return $sets;
  });
  

• Use Case: Role-based or feature-gated icons (e.g., admin-only icons).

4. Integration with Livewire/Blade UI Kit

• Workflow: Use the registered icons in Livewire components or Blade templates.
• Example:

  <!-- In a Livewire component -->
  <x-icon-fa-home class="w-6 h-6" wire:click="goHome" />
  

• Tip: Pair with blade-ui-kit/blade-icons for consistent icon rendering across your app.

5. Organizing Icons by Feature

• Workflow: Group icons by feature (e.g., resources/icons/auth/, resources/icons/dashboard/) and register them with descriptive prefixes.
• Example:

  'sets' => [
      'auth' => [
          'path' => resource_path('icons/auth'),
          'prefix' => 'auth',
      ],
      'dashboard' => [
          'path' => resource_path('icons/dashboard'),
          'prefix' => 'dashboard',
      ],
  ],
  

• Use Case: Modular icon management for large applications.

6. Custom Filesystem Disks

• Workflow: Store icons on remote storage (e.g., S3) and reference them via a disk.
• Example:

  'sets' => [
      'cloud' => [
          'path' => 'icons/cloud', // Relative to storage path
          'prefix' => 'cloud',
          'disk' => 's3',
      ],
  ],
  

• Use Case: Hosting icons externally (e.g., CDN or cloud storage).

Gotchas and Tips

Pitfalls

1. Prefix Conflicts:

   • Issue: Two icon sets with the same prefix (e.g., admin) will overwrite each other.
   • Fix: Use unique, descriptive prefixes (e.g., myapp-admin, plugin-x-admin).
   • Debug: Check config/artisanpack/icons.php and event-driven registrations for duplicates.

2. Missing SVG Files:

   • Issue: Icons won’t render if the SVG file is missing or the path is incorrect.
   • Fix: Verify paths in config/artisanpack/icons.php and ensure files exist at the specified location.
   • Debug: Use ArtisanPackUI\Icons\Facades\Icons::getSets() to inspect registered sets.

3. Caching Issues:

   • Issue: Changes to icon configurations or files may not reflect immediately due to Blade caching.
   • Fix: Clear Blade cache:

     php artisan view:clear
     

   • Tip: Disable caching in development:

     'cache' => env('APP_ENV') !== 'local',
     

     in config/artisanpack/icons.php.

4. Filesystem Permissions:

   • Issue: Icons stored on custom disks (e.g., S3) may fail to load if permissions are misconfigured.
   • Fix: Ensure the disk is properly configured in config/filesystems.php and the package has access.

5. Case Sensitivity:

   • Issue: Icon filenames are case-sensitive in Blade components (e.g., home.svg vs. Home.svg).
   • Fix: Standardize filenames to kebab-case (e.g., user-profile.svg).

Debugging Tips

1. Inspect Registered Sets:

   use ArtisanPackUI\Icons\Facades\Icons;
   dd(Icons::getSets());
   

   • Returns an array of all registered icon sets with their paths and prefixes.

2. Check Icon Existence:

   if (!Icons::hasIcon('fa', 'home')) {
       \Log::error('Icon "fa-home" not found!');
   }
   

3. Enable Debug Logging: Add to config/artisanpack/icons.php:

   'debug' => env('APP_ENV') === 'local',
   

   • Logs registration events and errors to storage/logs/laravel.log.

Extension Points

1. Custom Icon Resolvers:

   • Extend the package to support non-SVG icons (e.g., Font Awesome via CDN) by implementing a custom resolver:

     use ArtisanPackUI\Icons\Contracts\IconResolver;
     class FontAwesomeResolver implements IconResolver { ... }
     

   • Register it via the ap.icons.register-resolvers filter.

2. Dynamic Icon Generation:

   • Use the ap.icons.generate-icon event to dynamically create icons from data (e.g., emoji or generated SVGs).

3. Icon Theming:

   • Override icon colors/styles by extending the Blade component:

     <x-icon-fa-home class="text-blue-500" />
     

   • Or create a wrapper component:

     <x-my-icon.primary name="fa-home" />
     

Performance Tips

1. Lazy Loading:

   • Icons are loaded on-demand, so avoid registering large sets unnecessarily.
   • For admin panels, register icons only when the admin middleware is active.

2. Minimize Disk I/O:

   • Use local filesystem for icons (disk: null) unless remote storage is required.
   • Cache resolved icon paths if dynamically generating sets.

3. Bundle Icons:

   • Combine small icon sets into larger ones to reduce HTTP requests (if using remote storage).

Configuration Quirks

1. Default Values:

   • If disk is not specified, the package defaults to the local filesystem.
   • If prefix is omitted, it defaults to the set name (e.g., path: 'icons/hero' → prefix: 'hero').

2. Path Resolution:

   • Paths are resolved relative to the Laravel root (app_path(), resource_path(), etc.).
   • Use absolute paths for clarity in event-driven registration:

     addSet(realpath(__DIR__ . '/../../resources/icons'), 'mypackage');
     

3. Environment-Specific Config:

   • Override the config per environment (e.g., config/artisanpack/icons-local.php) and merge it:

     $config = require __DIR__ . '/icons.php';
     if (file_exists($customConfig = __DIR__ . '/icons-' . env('APP_ENV') . '.php')) {
         $config = array_merge_recursive($config, require $customConfig);