Reference Color Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require baks-dev/reference-color
   

   Verify PHP 8.4+ compliance in your php -v output.

2. Basic Configuration Create config/packages/reference.php with the provided Symfony DI snippet:

   <?php
   namespace Symfony\Component\DependencyInjection\Loader\Configurator;
   use BaksDev\Reference\Color\Choice\ReferenceChoiceColor;
   
   return static function (ContainerConfigurator $configurator) {
       $services = $configurator->services()
           ->defaults()
           ->autowire(true)
           ->autoconfigure(true);
       $services->set(ReferenceChoiceColor::class)->tag('baks.reference.choice');
   };
   

3. First Use Case: Color Dropdown Inject ReferenceChoiceColor into a Laravel controller or service:

   use BaksDev\Reference\Color\Choice\ReferenceChoiceColor;
   
   class AdminController extends Controller {
       public function __construct(private ReferenceChoiceColor $colorChoice) {}
   
       public function showColorPicker() {
           $colors = $this->colorChoice->getColors(); // Hypothetical method
           return view('admin.colors', compact('colors'));
       }
   }
   

   Render in Blade:

   <select>
       @foreach($colors as $color)
           <option value="{{ $color->hex }}">{{ $color->name }}</option>
       @endforeach
   </select>
   

Implementation Patterns

Usage Patterns

1. Centralized Color Management Define all colors in a single place (likely via the package’s configuration) and reuse across:

   • Blade templates (e.g., {{ $color->hex }}).
   • API responses (e.g., return response()->json(['color' => $color->hex])).
   • CLI tools (e.g., Artisan commands with color-coded output).

2. Dynamic UI Components Use the ReferenceChoiceColor service to populate:

   • Dropdowns: For admin panels (e.g., theme selectors).
   • Livewire/Alpine.js: Bind color changes to state:

     // Livewire component
     public $selectedColor;
     public function updatedSelectedColor() {
         // Trigger UI updates (e.g., dark/light mode toggle)
     }
     

   • Form Themes: Integrate with Laravel Collective or custom form builders.

3. Accessibility Checks Leverage hypothetical methods (e.g., getContrastRatio()) to validate:

   • WCAG compliance in controllers:

     if ($color->getContrastRatio($backgroundColor) < 4.5) {
         throw new \InvalidArgumentException("Color fails contrast ratio.");
     }
     

   • Automated tests:

     public function testColorContrast() {
         $this->assertGreaterThan(4.5, $color->getContrastRatio('#ffffff'));
     }
     

4. Theming Systems Implement multi-tenancy or user-preference-driven themes:

   // Pseudocode: Theme service using ReferenceChoiceColor
   class ThemeService {
       public function getThemeColors(User $user) {
           return $this->colorChoice->filterByTag($user->preferredTheme);
       }
   }
   

Workflows

1. Color Definition Workflow

   • Designers: Provide color names/HEX values to the backend team.
   • Developers: Configure the package (via ReferenceChoiceColor) to load these colors.
   • QA: Run automated contrast checks before deployment.

2. Release Workflow

   • Version colors alongside code (e.g., config/colors.php + package).
   • Use Git tags to track color palette changes:

     git tag -a v1.2.0 -m "Updated primary color to #4a6fa5"
     

3. Frontend-Backend Sync

   • Option 1: Expose colors via API:

     Route::get('/api/colors', function () {
         return response()->json($this->colorChoice->getColors());
     });
     

   • Option 2: Inline in Blade:

     <style>
         :root {
             --primary: {{ $colors['primary']->hex }};
         }
     </style>
     

Integration Tips

1. Laravel Service Provider Wrap the package in a Laravel provider to abstract Symfony DI:

   // app/Providers/ColorServiceProvider.php
   namespace App\Providers;
   use Illuminate\Support\ServiceProvider;
   use BaksDev\Reference\Color\Choice\ReferenceChoiceColor;
   
   class ColorServiceProvider extends ServiceProvider {
       public function register() {
           $this->app->singleton(ReferenceChoiceColor::class);
       }
   }
   

2. Caching Cache color references to avoid repeated loads:

   public function getColors() {
       return Cache::remember('color.palette', now()->addHours(1), function () {
           return $this->colorChoice->getColors();
       });
   }
   

3. Testing Mock the service in PHPUnit:

   $mockColors = collect([new Color('red', '#ff0000')]);
   $this->mock(ReferenceChoiceColor::class)->shouldReceive('getColors')->andReturn($mockColors);
   

4. Database Integration If colors are stored in a database, use Eloquent:

   class Color extends Model {
       protected $casts = ['hex' => 'string'];
   }
   

   Then bind the package to the model:

   $this->colorChoice->setColors(Color::all());
   

Gotchas and Tips

Pitfalls

1. Symfony DI in Laravel

   • Issue: The package expects Symfony’s ContainerConfigurator, which may conflict with Laravel’s container.
   • Fix: Use a Laravel service provider to register the service manually (see Integration Tips).

2. Undocumented API

   • Issue: Methods like getColors() or getContrastRatio() are not documented in the README.
   • Fix: Inspect the ReferenceChoiceColor class or use PHPStan to infer usage:

     vendor/bin/phpstan analyse --level 5
     

3. PHP 8.4+ Dependency

   • Issue: If your project uses PHP <8.4, the package will fail to install.
   • Fix: Upgrade PHP or use a polyfill (e.g., nikic/php-parser for attribute support).

4. No Frontend Integration

   • Issue: The package is PHP-only; frontend frameworks (e.g., Tailwind, Sass) won’t auto-sync.
   • Fix: Manually sync colors via:
     • API endpoints (recommended for SPAs).
     • Blade-injected CSS variables (for SSR).

5. Tagging System

   • Issue: The baks.reference.choice tag suggests the package is designed for specific use cases (e.g., dropdowns).
   • Fix: If you need broader functionality, extend the class:

     class ExtendedColorChoice extends ReferenceChoiceColor {
         public function getColorByName(string $name) {
             return $this->colors->firstWhere('name', $name);
         }
     }
     

6. No Color Space Conversions

   • Issue: The package may not support RGB/HSL conversions or other color spaces.
   • Fix: Use a secondary library (e.g., php-color) for advanced use cases.

Debugging

1. Service Not Found

   • Symptom: Class ReferenceChoiceColor not found.
   • Debug:

     php artisan container:list | grep ReferenceChoiceColor
     

   • Solution: Ensure the service is registered in AppServiceProvider or the Symfony config.

2. Empty Color List

   • Symptom: $colorChoice->getColors() returns an empty collection.
   • Debug: Check if colors are loaded via database/API or hardcoded in the package.
   • Solution: Implement a fallback:

     $colors = $this->colorChoice->getColors()->isEmpty()
         ? collect([new Color('default', '#000000')])
         : $this->colorChoice->getColors();
     

3. Symfony DI Errors

   • Symptom: Call to undefined method ContainerConfigurator::....
   • Debug: Verify Symfony’s dependency-injection package is installed:

     composer require symfony/dependency-injection
     

   • Solution: Use Laravel’s extend() to adapt the container:

     $this->app->extend(ReferenceChoiceColor::class, function () {
         return new ReferenceChoiceColor();
     });
     

Config Quirks

1. Package Configuration File
   • The config/packages/reference.php file is required for the service to work.
   • Tip: Store it in config/packages/ and ensure it’s loaded in config/app.php:

     'providers' => [
         // ...