## Getting Started

### Minimal Setup
1. **Install Dependencies**
   ```bash
   composer require baks-dev/materials-category baks-dev/materials-catalog baks-dev/core:^7.4

Note: baks-dev/core is a hard dependency; ensure Laravel compatibility.

Publish Configurations

php artisan vendor:publish --provider="BaksDev\MaterialsCatalog\MaterialsCatalogServiceProvider"

Verify config/materials-catalog.php exists and update database settings.

Run Migrations
```
php artisan migrate
```
- If migrations conflict with existing Laravel schema, manually inspect and merge.

First Use Case: List Materials

use BaksDev\MaterialsCatalog\Material;

$materials = Material::query()
    ->with('category', 'attributes')
    ->where('is_active', true)
    ->paginate(20);

Note: Assumes Eloquent integration. If the package uses Doctrine, wrap it in a Laravel service:
```
$materials = app(\BaksDev\MaterialsCatalog\Service::class)->findAll();
```

Basic Search

$results = Material::search('steel')
    ->where('supplier_id', auth()->user()->supplier->id)
    ->get();

If the package lacks Laravel’s query builder methods, use its native API:

$results = app(\BaksDev\MaterialsCatalog\SearchService::class)->search('steel');

Implementation Patterns

Core Workflows

1. Material CRUD with Laravel Eloquent

Pattern: Extend the package’s models with Laravel traits or use a repository pattern.

// app/Repositories/MaterialRepository.php
namespace App\Repositories;

use BaksDev\MaterialsCatalog\Material as BaseMaterial;
use Illuminate\Database\Eloquent\Model;

class MaterialRepository
{
    public function create(array $data): Model
    {
        return BaseMaterial::create($data);
    }
}

Integration Tip: Use Laravel’s bind() to resolve the repository:

$this->app->bind(
    \App\Repositories\MaterialRepository::class,
    \BaksDev\MaterialsCatalog\MaterialRepository::class
);

2. Attribute-Based Filtering

Pattern: Leverage the package’s attribute system for dynamic filtering.

// Example: Filter materials by density range
$materials = Material::query()
    ->whereHas('attributes', function ($query) {
        $query->where('name', 'density')
              ->where('value', '>=', 7.8); // g/cm³ for steel
    })
    ->get();

Fallback: If the package uses a custom attribute system:

$filter = app(\BaksDev\MaterialsCatalog\FilterBuilder::class)
    ->add('density', '>=', 7.8)
    ->build();

$materials = app(\BaksDev\MaterialsCatalog\Service::class)->filter($filter);

3. Supplier Integration

Pattern: Link materials to suppliers via Laravel relationships.

// app/Models/Material.php
public function supplier()
{
    return $this->belongsTo(Supplier::class);
}

Workaround: If the package lacks supplier support, extend its models:

class ExtendedMaterial extends \BaksDev\MaterialsCatalog\Material
{
    public function supplier()
    {
        return $this->belongsTo(Supplier::class, 'supplier_id');
    }
}

4. API Exposure

Pattern: Use Laravel’s API resources to expose the catalog.

// app/Http/Resources/MaterialResource.php
public function toArray($request)
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'category' => CategoryResource::make($this->category),
        'attributes' => AttributeResource::collection($this->attributes),
        'supplier' => SupplierResource::make($this->supplier),
    ];
}

Integration: Route the package’s data through Laravel’s API:
```
Route::apiResource('materials', MaterialController::class);
```

5. Event-Driven Extensions

Pattern: Listen to package events and trigger Laravel logic.

// app/Providers/EventServiceProvider.php
protected $listen = [
    \BaksDev\MaterialsCatalog\Events\MaterialCreated::class => [
        \App\Listeners\LogMaterialCreation::class,
    ],
];

Symfony Event Bridge: If the package uses Symfony events:

// app/Providers/AppServiceProvider.php
public function boot()
{
    \BaksDev\MaterialsCatalog\Events::dispatch(
        \BaksDev\MaterialsCatalog\Events\MaterialCreated::class,
        function ($event) {
            event(new \App\Events\MaterialCreated($event->material));
        }
    );
}

Integration Tips

1. Database Schema Alignment

Tip: Use Laravel’s Schema::defaultStringLength() to match the package’s expectations (e.g., 191 for MySQL).

Migration Strategy: Wrap the package’s migrations in Laravel’s schema builder:

Schema::create('materials', function (Blueprint $table) {
    $table->id();
    $table->string('name', 255);
    // ... other fields from the package's migration
});

2. Service Provider Setup

Tip: Register the package’s services in AppServiceProvider:

public function register()
{
    $this->app->singleton(\BaksDev\MaterialsCatalog\Service::class, function ($app) {
        return new \BaksDev\MaterialsCatalog\Service(
            $app->make(\BaksDev\MaterialsCatalog\MaterialRepository::class)
        );
    });
}

3. Testing Strategy

Tip: Use Laravel’s testing helpers to mock the package:

$this->mock(\BaksDev\MaterialsCatalog\Service::class, function ($mock) {
    $mock->shouldReceive('findAll')->andReturn(collect([$material]));
});

Symfony Test Bridge: If tests are Symfony-specific, run them in a separate Docker container with Symfony CLI.

4. Localization

Tip: Override the package’s language files in resources/lang:

// config/materials-catalog.php
'locale' => app()->getLocale(),

Fallback: Use Laravel’s __() function in views:

{{ __('materials-catalog::messages.create_success') }}

5. Performance Optimization

Tip: Cache frequent queries using Laravel’s cache:

$materials = Cache::remember('materials_active', now()->addHours(1), function () {
    return Material::where('is_active', true)->get();
});

Database Indexes: Add indexes to Laravel’s migrations if the package lacks them:

Schema::table('materials', function (Blueprint $table) {
    $table->index('name');
    $table->index('category_id');
});

Gotchas and Tips

Pitfalls

1. Symfony vs. Laravel DI Conflicts

Gotcha: The package expects Symfony’s service container. Directly calling Symfony services (e.g., new \BaksDev\MaterialsCatalog\Service()) will fail.

Fix: Bind services via Laravel’s container:

$this->app->bind(
    \BaksDev\MaterialsCatalog\Service::class,
    \BaksDev\MaterialsCatalog\Service::class
);

Debug Tip: Check for ContainerNotFoundException in Laravel logs.

2. Doctrine ORM vs. Eloquent

Gotcha: The package uses Doctrine, which may conflict with Laravel’s Eloquent.

Fix: Create a facade to abstract the ORM:

// app/Facades/Material.php
public static function query()
{
    return app(\BaksDev\MaterialsCatalog\MaterialRepository::class)->query();
}

Workaround: Fork the package and replace Doctrine with Eloquent.

3. Undocumented API Surface

Gotcha: The package may lack Laravel-specific documentation (e.g., no make:material Artisan command).

Fix: Reverse-engineer the package:

grep -r "public function" vendor/baks-dev/materials-catalog/src/

Tip: Check tests/ for usage examples.

4. Russian Documentation

Gotcha: The README and comments are in Russian

Materials Catalog Laravel Package