Reference Shoes Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require baks-dev/reference-shoes
   

   Ensure your composer.json has "require": {"php": "^8.4"}.

2. First Use Case: Fetch a shoe size conversion (e.g., US to EU):

   use BaksDev\ReferenceShoes\Facades\ShoeSize;
   
   $euSize = ShoeSize::convert('US', 'EU', 9); // Returns 42
   

3. Where to Look First:

   • Facade: BaksDev\ReferenceShoes\Facades\ShoeSize (primary entry point).
   • Config: config/reference-shoes.php (if custom mappings are needed).
   • Docs: Check src/ReferenceShoesServiceProvider.php for service binding details.

Implementation Patterns

Core Workflows

1. Standard Conversions:

   // Convert between any two supported systems
   $ukSize = ShoeSize::convert('EU', 'UK', 42); // Returns 6
   

2. Batch Processing:

   $sizes = [9, 10, 11]; // US sizes
   $euSizes = ShoeSize::batchConvert('US', 'EU', $sizes); // Returns [42, 43, 44]
   

3. Validation:

   if (ShoeSize::isValidSize('EU', 42)) {
       // Proceed with conversion
   }
   

4. Integration with Eloquent:

   // Example: Store shoe sizes in a model
   class Product extends Model {
       public function getEuSizeAttribute() {
           return ShoeSize::convert('US', 'EU', $this->us_size);
       }
   }
   

5. Custom Mappings: Override default mappings via config:

   // config/reference-shoes.php
   'custom_mappings' => [
       'BR' => [9 => 42, 10 => 43], // Brazilian sizes
   ];
   

Advanced Patterns

• Service Container Binding: Bind custom logic via the service provider:

  $this->app->bind('custom.shoe.converter', function () {
      return new CustomShoeConverter();
  });
  

• API Layer: Expose conversions via Laravel routes:

  Route::get('/shoe-convert/{from}/{to}/{size}', function ($from, $to, $size) {
      return response()->json([
          'size' => ShoeSize::convert($from, $to, $size)
      ]);
  });
  

Gotchas and Tips

Pitfalls

1. Unsupported Systems:

   • The package defaults to ['US', 'EU', 'UK', 'FR', 'DE']. Custom systems require config overrides.
   • Fix: Extend the config/reference-shoes.php array under supported_systems.

2. Floating-Point Precision:

   • Some conversions (e.g., fractional sizes) may return floats. Handle with round() if needed:

     $size = round(ShoeSize::convert('US', 'EU', 9.5), 1); // 42.5
     

3. Case Sensitivity:

   • System codes ('US', 'EU') are case-sensitive. Use constants or lowercase all inputs:

     $system = strtoupper($request->input('system'));
     

4. Performance:

   • Batch conversions are optimized, but avoid recursive calls in loops. Cache results if processing large datasets:

     $cacheKey = "shoe_{$from}_{$to}_{$size}";
     return Cache::remember($cacheKey, now()->addHours(1), fn() =>
         ShoeSize::convert($from, $to, $size)
     );
     

Debugging

• Check Mappings: Dump the full mapping table for debugging:

  dd(ShoeSize::getAllMappings());
  

• Logging: Enable debug mode in config to log conversion attempts:

  'debug' => env('APP_DEBUG', false),
  

Extension Points

1. Add New Systems: Extend the ShoeSize facade or create a decorator:

   class ExtendedShoeSize extends \BaksDev\ReferenceShoes\Facades\ShoeSize {
       public static function convertJp($usSize) {
           return self::convert('US', 'JP', $usSize);
       }
   }
   

2. Custom Validation: Override the isValidSize method in a service provider:

   $this->app->singleton('shoe.size.validator', function () {
       return new CustomSizeValidator();
   });
   

3. Testing: Mock the facade in tests:

   $this->app->instance('shoe.size', Mockery::mock(ShoeSize::class));
   

Config Quirks

• Default Values: The package uses null for unsupported conversions. Override in config:

  'default_fallback' => 'N/A',
  

• Localization: Size names (e.g., 'US' => 'United States') are hardcoded. Extend via:

  'system_names' => [
      'JP' => 'Japan',
  ],
  

```markdown
### Pro Tips
1. **Laravel Mix**:
   Bundle size charts as assets:
   ```js
   // resources/js/shoe-charts.js
   import { ShoeSize } from 'baks-dev/reference-shoes';

   export function getChartData() {
       return Array.from({length: 12}, (_, i) => ({
           us: i + 1,
           eu: ShoeSize.convert('US', 'EU', i + 1),
       }));
   }

2. API Resources: Format responses with API Resources:

   class ShoeSizeResource extends JsonResource {
       public function toArray($request) {
           return [
               'value' => $this->size,
               'eu_equivalent' => ShoeSize::convert('US', 'EU', $this->size),
           ];
       }
   }
   

3. Command Bus: Dispatch conversions as commands:

   $this->dispatch(new ConvertShoeSize($from, $to, $size));
   

4. Queue Jobs: Offload heavy conversions:

   ConvertShoeSizeJob::dispatch($from, $to, $size)->onQueue('shoes');
   

5. Notifications: Notify users of size changes:

   $user->notify(new ShoeSizeUpdated($oldSize, $newSize));