Getting Started

Minimal Steps

Install the Package
```
composer require baks-dev/reference-cars
```
Verify PHP 8.4+ and Laravel 10+ compatibility.

Register the Service Add the service to your AppServiceProvider or a dedicated provider:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->bind(
        \BaksDev\Reference\Cars\ReferenceChoiceCars::class,
        \BaksDev\Reference\Cars\ReferenceChoiceCars::class
    );
}

First Usage Example Fetch car brands in a controller or Blade template:

use BaksDev\Reference\Cars\ReferenceChoiceCars;

public function showCarBrands(ReferenceChoiceCars $carReference)
{
    $brands = $carReference->getBrands();
    return view('cars.brands', compact('brands'));
}

Render in Blade:

<select name="brand">
    @foreach($brands as $brand)
        <option value="{{ $brand }}">{{ $brand }}</option>
    @endforeach
</select>

Verify Data Check the package’s default dataset by logging or dumping:
```
dd($carReference->getAllCars());
```

Implementation Patterns

Core Workflows

1. Dropdown Integration

Use the package’s choice-based system for forms:

// Controller
public function createCarForm(ReferenceChoiceCars $carReference)
{
    return view('cars.form', [
        'brands' => $carReference->getBrands(),
        'models' => $carReference->getModelsByBrand('Toyota'),
    ]);
}

Blade:

<select name="brand" class="form-control">
    @foreach($brands as $brand)
        <option value="{{ $brand }}">{{ $brand }}</option>
    @endforeach
</select>

<select name="model" class="form-control">
    @foreach($models as $model)
        <option value="{{ $model }}">{{ $model }}</option>
    @endforeach
</select>

2. Validation Rules

Extend Laravel’s validation with car-specific rules:

use Illuminate\Support\Facades\Validator;
use BaksDev\Reference\Cars\ReferenceChoiceCars;

public function store(Request $request, ReferenceChoiceCars $carReference)
{
    $validator = Validator::make($request->all(), [
        'brand' => ['required', 'string', function ($attribute, $value, $fail) use ($carReference) {
            if (!$carReference->isBrandValid($value)) {
                $fail('The brand is invalid.');
            }
        }],
        'model' => ['required', 'string', function ($attribute, $value, $fail) use ($carReference) {
            if (!$carReference->isModelValid($value)) {
                $fail('The model is invalid.');
            }
        }],
    ]);
}

3. API Responses

Return car data in API endpoints:

public function getCars(ReferenceChoiceCars $carReference)
{
    return response()->json([
        'brands' => $carReference->getBrands(),
        'models' => $carReference->getAllModels(),
    ]);
}

4. Caching Layer

Cache car data to reduce memory usage and improve performance:

public function getCachedCars(ReferenceChoiceCars $carReference)
{
    return Cache::remember('car_reference_data', now()->addHours(1), function () use ($carReference) {
        return $carReference->getAllCars();
    });
}

Integration Tips

Laravel Service Container

Bind the package’s services explicitly in a provider:

// app/Providers/BaksCarsServiceProvider.php
public function register()
{
    $this->app->singleton(
        \BaksDev\Reference\Cars\ReferenceChoiceCars::class,
        fn($app) => new \BaksDev\Reference\Cars\ReferenceChoiceCars()
    );
}

Facade for Simplicity

Create a facade to simplify access:

// app/Facades/CarReference.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

class CarReference extends Facade
{
    protected static function getFacadeAccessor()
    {
        return \BaksDev\Reference\Cars\ReferenceChoiceCars::class;
    }
}

Usage:

use App\Facades\CarReference;

$brands = CarReference::brands();

Database Persistence

If you need to persist car data, create a migration and seeder:

// database/migrations/xxxx_create_car_references_table.php
Schema::create('car_references', function (Blueprint $table) {
    $table->id();
    $table->string('brand');
    $table->string('model')->nullable();
    $table->json('parameters')->nullable();
    $table->timestamps();
});

// database/seeders/CarReferenceSeeder.php
public function run()
{
    $carReference = new \BaksDev\Reference\Cars\ReferenceChoiceCars();
    $cars = $carReference->getAllCars();

    foreach ($cars as $car) {
        CarReference::create([
            'brand' => $car['brand'],
            'model' => $car['model'] ?? null,
            'parameters' => $car['parameters'] ?? null,
        ]);
    }
}

Localization

Override default car names or descriptions for localization:

// config/car-reference.php
return [
    'localizations' => [
        'Toyota' => [
            'en' => 'Toyota',
            'ru' => 'Тойота',
        ],
        'Model' => [
            'en' => 'Model',
            'ru' => 'Модель',
        ],
    ],
];

Gotchas and Tips

Pitfalls

1. Memory Usage

The package likely loads data into memory by default. For large datasets, this can cause high memory consumption.
Fix: Implement caching or persist data to a database.

2. Data Mutability

The package’s data may be immutable or difficult to modify. If you need to add custom car brands/models, you’ll need to extend or override its logic.

Fix: Create a wrapper class to merge custom data with the package’s dataset:

class ExtendedCarReference
{
    protected $baseReference;
    protected $customData;

    public function __construct(ReferenceChoiceCars $baseReference, array $customData)
    {
        $this->baseReference = $baseReference;
        $this->customData = $customData;
    }

    public function getAllCars()
    {
        $baseCars = $this->baseReference->getAllCars();
        return array_merge($baseCars, $this->customData);
    }
}

3. Symfony DI Dependency

The package expects Symfony’s DI container, which may conflict with Laravel’s container if not properly bound.
Fix: Ensure all services are explicitly bound in Laravel’s container (as shown in the "Implementation Patterns" section).

4. No Eloquent Models

The package does not provide Eloquent models, so you’ll need to create your own if you want to use Laravel’s ORM.

Fix: Create a model and repository to bridge the package’s data with Eloquent:

// app/Models/CarReference.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class CarReference extends Model
{
    protected $fillable = ['brand', 'model', 'parameters'];
}

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

use App\Models\CarReference;
use BaksDev\Reference\Cars\ReferenceChoiceCars;

class CarReferenceRepository
{
    public function syncWithPackage(ReferenceChoiceCars $carReference)
    {
        $cars = $carReference->getAllCars();
        foreach ($cars as $car) {
            CarReference::updateOrCreate(
                ['brand' => $car['brand'], 'model' => $car['model']],
                ['parameters' => $car['parameters']]
            );
        }
    }
}

5. Limited Documentation

The package’s documentation is minimal, so you’ll need to rely on the source code and trial-and-error for advanced use cases.
Fix: Study the package’s source code (e.g., ReferenceChoiceCars.php) to understand its methods and data structure.

6. No Real-Time Updates

The package does not provide mechanisms for real-time updates or syncing with external APIs (e.g., manufacturer databases).

Fix: Implement a scheduled job to periodically update the dataset:

// app/Console/Commands/UpdateCarReferences.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use BaksDev\Reference\Cars\Reference

Reference Cars Laravel Package