Reference Materials Furniture Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require baks-dev/reference-materials-furniture
   

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

2. Publish Config (if needed):

   php artisan vendor:publish --provider="BaksDev\Furniture\FurnitureServiceProvider" --tag="config"
   

   Check config/furniture.php for default material definitions (e.g., wood_types, upholstery_materials).

3. First Use Case: Fetch a material by ID in a Blade template or controller:

   use BaksDev\Furniture\Facades\Furniture;
   
   $oakMaterial = Furniture::getMaterial('oak');
   dd($oakMaterial->name, $oakMaterial->density); // Output: "Oak", 0.72
   

4. Key Files to Review:

   • config/furniture.php: Default material catalog and settings.
   • src/Facades/Furniture.php: Main facade for quick access.
   • src/Contracts/MaterialInterface.php: Expected material structure.

Implementation Patterns

Core Workflows

1. Material Retrieval:

   • Facade Method: Furniture::getMaterial($id) returns a Material object.
   • Collection Access: Furniture::allMaterials() returns a Collection of all materials.
   • Filtering: Use Furniture::filterMaterials(fn($material) => $material->type === 'wood').

2. Dynamic Material Extension:

   • Add custom materials via config:

     'custom_materials' => [
         'bamboo' => [
             'name' => 'Bamboo',
             'type' => 'wood',
             'density' => 0.65,
             'sustainable' => true,
         ],
     ],
     

   • Or programmatically:

     Furniture::addMaterial(new \BaksDev\Furniture\Models\Material([
         'id' => 'reclaimed_oak',
         'name' => 'Reclaimed Oak',
         'type' => 'wood',
         'density' => 0.8,
     ]));
     

3. Integration with Eloquent:

   • Attach materials to models via morphTo:

     class Chair extends Model {
         public function material() {
             return $this->morphTo();
         }
     }
     

   • Use the facade to validate material IDs:

     $valid = Furniture::isValidMaterial($request->material_id);
     

4. Localization:

   • Override material names/descriptions in lang/en/furniture.php:

     return [
         'materials' => [
             'oak' => [
                 'name' => 'American White Oak',
                 'description' => 'Durable and water-resistant...',
             ],
         ],
     ];
     

5. API Responses:

   • Serialize materials with Furniture::materialsAsJson():

     return response()->json(Furniture::materialsAsJson(['wood']));
     

Gotchas and Tips

Common Pitfalls

1. Material ID Case Sensitivity:

   • IDs in config/furniture.php must match exactly (e.g., 'oak' vs 'Oak'). Use strtolower() when accepting user input:

     $normalizedId = strtolower($request->material_id);
     

2. Config Caching:

   • After publishing config, clear the cache:

     php artisan config:clear
     

   • Or use the facade’s refresh() method:

     Furniture::refresh();
     

3. Missing Default Config:

   • If no config/furniture.php exists, the package falls back to hardcoded defaults. Publish the config to customize:

     php artisan vendor:publish --tag="config" --provider="BaksDev\Furniture\FurnitureServiceProvider"
     

4. Type Safety:

   • The MaterialInterface enforces id, name, type, and density fields. Omitting these will throw InvalidArgumentException.

5. Performance:

   • Avoid calling Furniture::allMaterials() in loops. Cache the result:

     $materials = Furniture::remember(3600, fn() => Furniture::allMaterials());
     

Debugging Tips

1. Validate Material Data:

   • Use the validateMaterial() helper:

     if (!Furniture::validateMaterial(['id' => 'oak', 'name' => 'Oak'])) {
         throw new \InvalidArgumentException("Invalid material data.");
     }
     

2. Check for Overrides:

   • Custom materials in config/furniture.php override defaults. Use Furniture::getRawMaterials() to inspect the merged catalog.

3. Facade Binding:

   • If the facade isn’t available, rebind it in a service provider:

     $this->app->bind('Furniture', function ($app) {
         return new \BaksDev\Furniture\Facades\Furniture($app['BaksDev\Furniture\MaterialRepository']);
     });
     

Extension Points

1. Custom Material Providers:

   • Implement BaksDev\Furniture\Contracts\MaterialProvider to fetch materials from an external API or database:

     class ApiMaterialProvider implements MaterialProvider {
         public function getMaterials(): array {
             return json_decode(file_get_contents('https://api.example.com/materials'), true);
         }
     }
     

   • Register it in config/furniture.php:

     'providers' => [
         \App\Providers\ApiMaterialProvider::class,
     ],
     

2. Material Events:

   • Listen for material-related events (e.g., MaterialAdded):

     event(new \BaksDev\Furniture\Events\MaterialAdded($material));
     

   • Or subscribe in EventServiceProvider:

     protected $listen = [
         \BaksDev\Furniture\Events\MaterialAdded::class => [
             \App\Listeners\LogMaterialAddition::class,
         ],
     ];
     

3. Testing:

   • Mock the facade in tests:

     $this->mock(Furniture::class)->shouldReceive('getMaterial')
         ->with('oak')->andReturn(new Material(['id' => 'oak', 'name' => 'Mock Oak']));
     

   • Use the FurnitureTestCase trait for shared assertions:

     use BaksDev\Furniture\Testing\FurnitureTestCase;
     
     class MaterialTest extends FurnitureTestCase {
         public function testOakMaterialExists() {
             $this->assertMaterialExists('oak');
         }
     }
     

4. Blade Directives:

   • Create a custom directive for concise Blade usage:

     Blade::directive('material', function ($expression) {
         return "<?php echo \\BaksDev\\Furniture\\Facades\\Furniture::getMaterial({$expression})->name; ?>";
     });
     

   • Usage:

     @material('oak') is a popular choice for furniture.