Field Tire Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require baks-dev/field-tire
   

2. Configure Twig: Add the package’s form themes to config/packages/field.php:

   return static function (TwigConfig $twig) {
       $twig->formThemes([
           '@field-tire-season/form.row.html.twig',
           '@field-tire-studs/form.row.html.twig',
           // ... other themes
       ]);
   };
   

3. First Use Case: Render a tire season field in a Laravel Blade view (via Twig integration):

   // In a controller
   return view('tires.create', [
       'seasonField' => app('tire_field.season') // Hypothetical facade
   ]);
   

   {# In resources/views/tires/create.blade.php #}
   {{ include('field-tire-season/form.row.html.twig') }}
   

Where to Look First

• Templates: Check vendor/baks-dev/field-tire/resources/views/ for default templates.
• Configuration: Review config/packages/field.php for theme registration.
• Override Guide: Follow the README’s template override instructions for customization.

First Practical Workflow

1. Create a tire selection form in Laravel.
2. Integrate the package’s fields (e.g., season, studs) into the form.
3. Override templates in resources/templates/field-tire/ for styling/behavior changes.
4. Validate submissions using Laravel’s Form Requests or custom logic.

Implementation Patterns

Usage Patterns

1. Field Integration in Forms

Use the package’s fields in Laravel forms via Twig:

{# resources/views/tires/form.blade.php #}
{{ form_start() }}
    {{ include('field-tire-season/form.row.html.twig', {
        'label': 'Сезонность шины',
        'value': old('season', $tire->season ?? null)
    }) }}
    {{ include('field-tire-studs/form.row.html.twig', {
        'label': 'Шипы',
        'value': old('has_studs', $tire->has_studs ?? null)
    }) }}
    {{ form_end() }}

2. Dynamic Field Rendering

Leverage Laravel’s service container to inject fields:

// app/Providers/AppServiceProvider.php
public function register()
{
    $this->app->bind('tire_field.season', function () {
        return new \BaksDev\FieldTire\SeasonField();
    });
}

// In a controller
$seasonField = app('tire_field.season');
return view('tires.edit', ['field' => $seasonField]);

3. Form Request Validation

Extend Laravel’s FormRequest to validate tire-specific rules:

use Illuminate\Foundation\Http\FormRequest;

class StoreTireRequest extends FormRequest
{
    public function rules()
    {
        return [
            'season' => 'required|in:winter,summer,all_season',
            'has_studs' => 'required_if:season,winter|boolean',
        ];
    }
}

4. Livewire/Alpine Integration

Use the package’s fields in Livewire components:

// app/Http/Livewire/TireSelector.php
public function render()
{
    return view('livewire.tire-selector', [
        'seasonOptions' => \BaksDev\FieldTire\SeasonField::options(),
    ]);
}

<!-- resources/views/livewire/tire-selector.blade.php -->
<select wire:model="season">
    @foreach($seasonOptions as $option)
        <option value="{{ $option['value'] }}">{{ $option['label'] }}</option>
    @endforeach
</select>

Workflows

Tire Configurator Tool

1. User Input: Collect tire specs (season, studs, dimensions) via package fields.
2. Validation: Use Laravel’s validation to enforce rules (e.g., studs only for winter).
3. Recommendation Engine: Pass validated data to a service to fetch compatible tires.
4. Display Results: Render results in Blade/Twig.

Inventory Filtering

1. Filter Form: Use package fields to let users filter tires by specs.
2. Query Builder: Convert filter inputs to Eloquent queries:

   $query = Tire::query();
   if ($request->has('season')) {
       $query->where('season', $request->season);
   }
   if ($request->has('has_studs')) {
       $query->where('has_studs', $request->has_studs);
   }
   

Localization

Override templates for Russian/other languages:

{# resources/templates/field-tire/season/content.html.twig #}
{% for option in options %}
    <option value="{{ option.value }}">{{ option.label|trans }}</option>
{% endfor %}

Integration Tips

1. Twig in Laravel:

   • Use laravel-twig-bridge for seamless Twig integration.
   • Cache Twig templates to avoid performance hits:

     Twig::enableAutoReload(false); // In production
     

2. Template Overrides:

   • Place overrides in resources/templates/field-tire/{field}/.
   • Example for season field:

     resources/
     └── templates/
         └── field-tire/
             └── season/
                 ├── content.html.twig
                 └── template.html.twig
     

3. Symfony Dependencies:

   • If conflicts arise, isolate the package in a separate service provider:

     // app/Providers/FieldTireServiceProvider.php
     public function register()
     {
         $this->app->register(\BaksDev\Core\FieldTireServiceProvider::class);
     }
     

4. Testing:

   • Test fields in isolation using Laravel’s HTTP tests:

     public function testSeasonField()
     {
         $response = $this->get('/tires?season=winter');
         $response->assertSee('Зимние шины');
     }
     

Gotchas and Tips

Pitfalls

1. Twig vs. Blade Conflicts:

   • Issue: Twig templates may not render correctly in Blade views.
   • Fix: Use laravel-twig-bridge and ensure Twig is properly initialized before Blade.

2. Template Caching:

   • Issue: Overridden templates may not update due to caching.
   • Fix: Clear Twig cache:

     php artisan twig:clear
     

3. Symfony Dependency Hell:

   • Issue: baks-dev/core may conflict with other Symfony packages.
   • Fix: Use composer why-not to diagnose conflicts and isolate dependencies.

4. Validation Gaps:

   • Issue: The package provides UI fields but no backend validation logic.
   • Fix: Implement custom validation in FormRequest or middleware.

5. Localization Quirks:

   • Issue: Hardcoded labels in templates may not translate.
   • Fix: Override content.html.twig to use Laravel’s __() or Twig’s trans filter.

Debugging

1. Template Not Loading:

   • Debug: Check if the template path is correct (e.g., resources/templates/field-tire/season/content.html.twig).
   • Fix: Verify the theme is registered in config/packages/field.php.

2. Field Not Rendering:

   • Debug: Ensure the field service is bound in Laravel’s container.
   • Fix: Manually instantiate the field class:

     $field = new \BaksDev\FieldTire\SeasonField();
     

3. CSRF Errors:

   • Debug: Twig templates may not include CSRF tokens.
   • Fix: Extend the template to include @csrf or use Laravel’s form_start() with Twig.

4. PHP 8.4+ Requirements:

   • Debug: If using Laravel <10, enable PHP 8.4 features or use polyfills.
   • Fix: Update config/packages/field.php to use compatible Symfony versions.

Tips

1. Extend Fields: Customize field behavior by extending the base classes:

   // app/Fields/CustomSeasonField.php
   use BaksDev\FieldTire\SeasonField;
   
   class CustomSeasonField extends SeasonField
   {
       public function options()
       {
           return array_merge(parent::options(), [
               ['value' => 'custom', 'label' => 'Custom Season']
           ]);
       }
   }
   

2. Reuse Logic: Extract tire-specific logic into a service:

   // app/Services/TireValidator.php
   public function validateSeasonAndStuds(array $data)
   {
       if ($data['season'] === 'winter' && !$data['has_studs']) {
           throw new \InvalidArgumentException('Winter tires must have studs.');
       }
   }
   

3. Performance:

   • Preload field options in a service provider: