Reference Caps Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/reference-caps
   

   Verify PHP 8.4+ compatibility in your composer.json or php --version.

2. First Use Case: Fetching a Cap Size

   use BaksDev\ReferenceCaps\Facades\CapSize;
   
   $size = CapSize::get('58-60'); // Returns a CapSize object or null
   echo $size?->getDescription(); // e.g., "Medium"
   

3. Where to Look First

   • Facade: BaksDev\ReferenceCaps\Facades\CapSize (primary entry point).
   • Service Provider: BaksDev\ReferenceCaps\ReferenceCapsServiceProvider (check config/reference-caps.php for defaults).
   • Data Source: Inspect config/reference-caps.php for the default size mappings or override via config/caps.php.

Implementation Patterns

Core Workflows

1. Retrieving Cap Sizes

   // By exact match (string)
   $size = CapSize::find('58-60');
   
   // By numeric range (int)
   $size = CapSize::findByCircumference(58.5);
   
   // As a collection (e.g., for dropdowns)
   $allSizes = CapSize::all();
   

2. Integration with Eloquent Models

   use BaksDev\ReferenceCaps\Traits\HasCapSize;
   
   class Product extends Model
   {
       use HasCapSize;
   
       protected $casts = [
           'cap_size' => 'string', // or 'integer' if storing circumference
       ];
   }
   

   • Automatically validates against registered cap sizes.

3. Dynamic Data Loading Override the default data source in config/caps.php:

   'sizes' => [
       '58-60' => ['description' => 'Custom Medium', 'circumference' => 58.5],
       // ...
   ],
   

4. Localization Extend descriptions or add translations via service provider booting:

   public function boot()
   {
       CapSize::extendDescriptions([
           '58-60' => __('custom.medium'),
       ]);
   }
   

Gotchas and Tips

Pitfalls

1. Case Sensitivity

   • Size keys (e.g., '58-60') are case-sensitive. Use strtolower() if normalizing user input:

     $size = CapSize::find(strtolower(trim($request->input('size'))));
     

2. Circumference Precision

   • The findByCircumference() method uses a ±0.5 tolerance by default. Adjust in config:

     'tolerance' => 0.3, // Stricter matching
     

3. Data Overrides

   • Custom config/caps.php must mirror the default structure. Missing keys will throw InvalidArgumentException.

4. Facade vs. Direct Class

   • The facade caches the data source. For testing, reset the cache or use the underlying class:

     use BaksDev\ReferenceCaps\CapSize as CapSizeClass;
     $size = CapSizeClass::find('58-60'); // No facade caching
     

Debugging Tips

• Validate Data Source:

  dd(CapSize::getAvailableSizes()); // Inspect loaded sizes
  

• Check for Typos:

  if (!$size = CapSize::find('58-60')) {
      throw new \InvalidArgumentException("Size '58-60' not found. Available: " . implode(', ', array_keys(CapSize::getAvailableSizes())));
  }
  

Extension Points

1. Custom Matching Logic Bind a custom resolver to the service provider:

   public function boot()
   {
       CapSize::extendResolver(function ($query, $value) {
           // Custom logic (e.g., fuzzy matching)
           return CapSize::find(str_contains($value, 'medium') ? '58-60' : null);
       });
   }
   

2. Event Listeners Listen for size validation failures:

   event(new CapSizeNotFound($request->input('size')));
   

3. API Responses Format sizes for APIs:

   return response()->json([
       'cap_size' => CapSize::find($request->size)?->toArray(),
   ]);
   

   • Uses toArray() to return ['key' => '58-60', 'description' => 'Medium', 'circumference' => 58.5].