Graphic Items Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require austral/graphic-items-bundle
   

   Register the bundle in config/app.php under providers:

   Austral\GraphicItemsBundle\AustralGraphicItemsBundle::class,
   

2. Publish Configuration Publish the default config:

   php artisan vendor:publish --provider="Austral\GraphicItemsBundle\AustralGraphicItemsBundle" --tag="config"
   

   This creates config/austral_graphic_items.php.

3. First Use Case: Displaying Icons Use the GraphicItem facade to render icons (e.g., from Simple Icons):

   use Austral\GraphicItemsBundle\Facades\GraphicItem;
   
   // Render an icon (e.g., GitHub)
   echo GraphicItem::icon('github')->size('24px')->render();
   

4. Database Setup (if using entities) Run migrations:

   php artisan migrate
   

   The bundle provides GraphicItem and GraphicItemFile entities for storing custom graphics.

Implementation Patterns

Core Workflows

1. Rendering Icons

   • Facade-based: Use GraphicItem::icon('name')->render() for static icons.
   • Dynamic Sizing: Chain methods like size(), color(), or class():

     GraphicItem::icon('laravel')->size('32px')->color('#ff2d20')->render();
     

   • Fallback Handling: Configure fallbacks in config/austral_graphic_items.php:

     'fallback_icon' => 'question',
     'fallback_size' => '16px',
     

2. Custom Graphic Items

   • Entity-Based Storage: Extend GraphicItem or GraphicItemFile to store custom SVGs/PNGs:

     $customIcon = new \Austral\GraphicItemsBundle\Entity\GraphicItem();
     $customIcon->setName('custom-logo');
     $customIcon->setContent('<svg>...</svg>');
     $entityManager->persist($customIcon);
     

   • File-Based Storage: Use GraphicItemFile for external files (e.g., uploaded SVGs):

     $fileIcon = new \Austral\GraphicItemsBundle\Entity\GraphicItemFile();
     $fileIcon->setName('uploaded-icon');
     $fileIcon->setFile($uploadedFile); // Symfony UploadedFile
     

3. Integration with Austral Ecosystem

   • Design Bundle: Pair with austral/design-bundle for theming:

     use Austral\DesignBundle\Facades\Design;
     
     echo GraphicItem::icon('twitter')->class(Design::getIconClass())->render();
     

   • HTTP Bundle: Use for API responses (e.g., return icon URLs):

     return response()->json(['icon' => GraphicItem::icon('github')->url()]);
     

4. Blade Directives Register the bundle’s Blade directives in AppServiceProvider:

   use Austral\GraphicItemsBundle\Blade\GraphicItemsBladeDirective;
   
   public function boot()
   {
       GraphicItemsBladeDirective::register();
   }
   

   Usage in Blade:

   @graphicIcon('github', ['size' => '24px'])
   

5. Caching Icons Enable caching in config:

   'cache' => [
       'enabled' => true,
       'ttl' => 3600, // 1 hour
   ],
   

   Clear cache when icons are updated:

   php artisan cache:clear
   

Gotchas and Tips

Common Pitfalls

1. Missing Dependencies

   • Ensure all required Austral bundles are installed (tools-bundle, entity-bundle, etc.).
   • Error: Class 'Austral\ToolsBundle\...' not found → Run composer require austral/tools-bundle.

2. Icon Not Found

   • Cause: Icon name doesn’t match Simple Icons or custom entries.
   • Fix: Check config/austral_graphic_items.php for allowed icons or add custom ones via entities.
   • Debug with:

     dd(GraphicItem::getAvailableIcons()); // List all registered icons
     

3. File Upload Issues

   • Cause: GraphicItemFile fails to save uploaded files.
   • Fix: Configure file storage in austral/entity-file-bundle (e.g., public/uploads/icons).
   • Validate file types in GraphicItemFile constraints:

     $fileIcon->setAllowedMimeTypes(['image/svg+xml', 'image/png']);
     

4. Blade Directive Conflicts

   • Cause: @graphicIcon conflicts with other directives.
   • Fix: Rename the directive in GraphicItemsBladeDirective or use the facade directly in Blade:

     {!! \Austral\GraphicItemsBundle\Facades\GraphicItem::icon('github')->render() !!}
     

5. Caching Quirks

   • Cause: Icons not updating after changes.
   • Fix: Clear both Laravel and bundle-specific caches:

     php artisan cache:clear
     php artisan austral:graphic-items:cache:clear
     

Debugging Tips

• Log Available Icons:

  \Log::info('Available Icons:', GraphicItem::getAvailableIcons());
  

• Inspect Entity Queries: Enable Doctrine debug in .env:

  APP_DEBUG=true
  DOCTRINE_ORM_OPTIMIZED_WRITER=false
  

• Check Config Overrides: Use config('austral_graphic_items') to verify loaded settings.

Extension Points

1. Custom Icon Sources Extend the IconSourceInterface to add new icon providers (e.g., Font Awesome):

   namespace App\GraphicItems;
   
   use Austral\GraphicItemsBundle\Icon\IconSourceInterface;
   
   class FontAwesomeSource implements IconSourceInterface
   {
       public function getIcon(string $name): string
       {
           // Fetch from Font Awesome API or local files
       }
   }
   

   Register in config:

   'icon_sources' => [
       \Austral\GraphicItemsBundle\Icon\SimpleIconsSource::class,
       App\GraphicItems\FontAwesomeSource::class,
   ],
   

2. Dynamic Icon Generation Use the GraphicItemBuilder to create icons programmatically:

   $builder = new \Austral\GraphicItemsBundle\Icon\GraphicItemBuilder();
   $builder->setName('dynamic-icon')->setContent('<svg>...</svg>');
   $icon = $builder->build();
   

3. Event Listeners Listen for graphic_item.created or graphic_item.updated events to trigger actions (e.g., cache invalidation):

   use Austral\GraphicItemsBundle\Event\GraphicItemEvent;
   
   public function onGraphicItemUpdated(GraphicItemEvent $event)
   {
       Cache::forget('graphic_items');
   }
   

4. Testing Mock the GraphicItem facade in tests:

   $this->mock(\Austral\GraphicItemsBundle\Facades\GraphicItem::class)
        ->shouldReceive('icon')
        ->andReturnSelf()
        ->shouldReceive('render')
        ->andReturn('<svg>Mock Icon</svg>');