Reference Pants Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require baks-dev/reference-pants

Verify in composer.json that the package is listed under require.

2. First Use Case Access pants sizes via the facade or service container:

   use BaksDev\ReferencePants\Facades\PantsSize;
   
   // Get all available sizes
   $sizes = PantsSize::all();
   
   // Get a specific size (e.g., 30/32)
   $size = PantsSize::find(30);
   

3. Where to Look First

   • Facade: BaksDev\ReferencePants\Facades\PantsSize (preferred for simplicity).
   • Service Container: Bind the PantsSize class directly if avoiding facades.
   • Documentation: Check the package’s README.md for size ranges (25/30 to 38/40) and methods.

Implementation Patterns

Core Workflows

1. Fetching Sizes

   • All Sizes: Use PantsSize::all() to retrieve an array of all supported sizes.

     $allSizes = PantsSize::all(); // Returns [25, 26, ..., 40]
     

   • Specific Size: Use PantsSize::find($waist) to get a size object.

     $size = PantsSize::find(32); // Returns object with waist/length properties
     

   • Range Query: Filter sizes dynamically (e.g., for UI dropdowns).

     $evenSizes = PantsSize::all()->filter(fn($size) => $size->waist % 2 === 0);
     

2. Integration with Laravel

   • Service Provider Binding (if extending functionality):

     // In AppServiceProvider@boot()
     $this->app->bind('custom.pants.size', function () {
         return new \BaksDev\ReferencePants\Services\CustomPantsSizeService();
     });
     

   • Eloquent Relationships: Attach sizes to a Product model.

     // Product.php
     public function pantsSize()
     {
         return $this->belongsTo(PantsSize::class, 'size_id');
     }
     

3. Localization

   • Override default labels (e.g., for Russian/English support):

     PantsSize::setLabel(30, '30/32 (Medium)');
     

   • Cache labels for performance:

     Cache::remember('pants_size_labels', now()->addHours(1), function () {
         return PantsSize::all()->pluck('label', 'waist');
     });
     

4. Validation

   • Use the package in Laravel validation rules:

     use BaksDev\ReferencePants\Rules\ValidPantsSize;
     
     $request->validate([
         'pants_size' => ['required', new ValidPantsSize],
     ]);
     

Gotchas and Tips

Pitfalls

1. Size Range Assumptions

   • The package supports 25/30 to 38/40 only. Attempting to fetch sizes outside this range (e.g., PantsSize::find(24)) returns null. Validate inputs:

     if (!$size = PantsSize::find($request->size)) {
         throw new \InvalidArgumentException("Invalid pants size.");
     }
     

2. Facade vs. Direct Instantiation

   • Avoid instantiating \BaksDev\ReferencePants\PantsSize directly. Use the facade or container binding to ensure consistency (e.g., for future label overrides).

3. PHP 8.4+ Requirement

   • The package requires PHP 8.4+. Check your php -v and update config/app.php if needed:

     'php' => '8.4',
     

4. Data Mutability

   • The PantsSize objects are immutable by default. To modify labels or metadata, use the setLabel() method or extend the class:

     class CustomPantsSize extends \BaksDev\ReferencePants\PantsSize {
         public function setCustomProperty($key, $value) { ... }
     }
     

Debugging

• Log Unavailable Sizes:

  if (!$size = PantsSize::find($input)) {
      \Log::warning("Pants size {$input} not found in reference data.");
  }
  

• Check for Typos: Ensure method names match exactly (e.g., find() vs get()).

Extension Points

1. Custom Size Logic

   • Extend the PantsSize class to add business logic:

     class ExtendedPantsSize extends \BaksDev\ReferencePants\PantsSize {
         public function isLarge(): bool {
             return $this->waist >= 36;
         }
     }
     

2. Database Storage

   • Store sizes in a database table for dynamic updates:

     // Migration
     Schema::create('pants_sizes', function (Blueprint $table) {
         $table->integer('waist')->unique();
         $table->string('label');
     });
     
     // Model
     class PantsSize extends \BaksDev\ReferencePants\PantsSize {
         protected static function boot() {
             parent::boot();
             static::addGlobalScope('db', function (Builder $builder) {
                 $builder->from('pants_sizes');
             });
         }
     }
     

3. Testing

   • Mock the facade in tests:

     $this->mock(BaksDev\ReferencePants\Facades\PantsSize::class)
         ->shouldReceive('find')
         ->andReturn(new \BaksDev\ReferencePants\PantsSize(32));
     

4. Performance

   • Cache the entire size collection if frequently accessed:

     Cache::remember('all_pants_sizes', now()->addDays(7), function () {
         return PantsSize::all();
     });
     

Config Quirks

• No Configuration File: The package is stateless by default. All behavior is driven by method calls (e.g., setLabel()). For complex setups, consider wrapping it in a config-driven service.
• Label Overrides: Changes to labels via setLabel() are not persisted. Reapply them on app boot if needed:

  // In AppServiceProvider@boot()
  PantsSize::setLabel(30, 'Custom Label');