Reference Car Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require baks-dev/reference-car
   

   Ensure your project uses PHP 8.4+ and Laravel 10.x+ (or compatible).

2. Install Dependencies

   composer require --dev symfony/panther dbrekelmans/bdi
   

   Configure web drivers (e.g., Chrome, Firefox) via:

   vendor/bin/bdi detect drivers
   

   Alternative: Install drivers manually (see README).

3. Publish Config (Optional)

   php artisan vendor:publish --provider="BaksDev\ReferenceCar\ReferenceCarServiceProvider" --tag="config"
   

   Customize config/reference-car.php (e.g., API endpoints, caching).

4. First Use Case: Fetch Car Brands

   use BaksDev\ReferenceCar\Facades\ReferenceCar;
   
   $brands = ReferenceCar::brands()->get();
   // Returns a collection of brand models (e.g., ['Toyota', 'BMW', ...]).
   

Implementation Patterns

Core Workflows

1. Data Retrieval Use facade methods for common queries:

   // Brands
   ReferenceCar::brands()->where('country', 'Germany')->get();
   
   // Models (with pagination)
   ReferenceCar::models()->where('brand_id', 1)->paginate(10);
   
   // Parameters (e.g., engine type, fuel)
   ReferenceCar::parameters()->where('type', 'fuel')->get();
   

2. Caching Enable caching in config/reference-car.php:

   'cache' => [
       'enabled' => true,
       'ttl' => 3600, // 1 hour
   ],
   

   Note: Cache invalidation is manual (e.g., after manual updates).

3. Scraping Custom Data Extend the scraper for unsupported regions:

   // Example: Add a new scraper for a local market
   ReferenceCar::extendScraper('local', function () {
       return new LocalMarketScraper();
   });
   

4. Integration with Eloquent Attach car data to models:

   use BaksDev\ReferenceCar\Traits\HasCarData;
   
   class Vehicle extends Model
   {
       use HasCarData;
   }
   
   // Usage:
   $vehicle = new Vehicle();
   $vehicle->setBrand('Toyota');
   $vehicle->setModel('Camry');
   

API-Driven Patterns

• Rate Limiting: Handle 429 responses via middleware:

  ReferenceCar::withRetry(3, 1000); // Retry 3 times with 1s delay.
  

• Async Updates: Use queues for background scraping:

  ReferenceCar::updateAllBrands()->dispatch();
  

Gotchas and Tips

Pitfalls

1. Driver Dependencies

   • Issue: Missing drivers cause silent failures.
   • Fix: Verify drivers post-install:

     vendor/bin/bdi list
     

   • Fallback: Use Docker with pre-configured drivers.

2. Scraping Delays

   • Issue: Slow responses from target sites.
   • Fix: Adjust config/reference-car.php:

     'scraper' => [
         'timeout' => 30, // seconds
         'retry_attempts' => 2,
     ],
     

3. Data Mismatches

   • Issue: Inconsistent naming (e.g., "Sedan" vs. "Sedans").
   • Fix: Normalize data post-fetch:

     $brands = ReferenceCar::brands()->get()->map(fn ($brand) => strtolower($brand->name));
     

4. Cache Staleness

   • Issue: Outdated cached data.
   • Fix: Clear cache manually or add a last_updated_at field to models.

Debugging Tips

• Log Scraping Errors: Enable debug mode in config/reference-car.php:

  'debug' => env('APP_DEBUG', false),
  

  Check logs at storage/logs/laravel.log.

• Inspect Raw Responses: Use the debug() method:

  $response = ReferenceCar::brands()->debug()->get();
  // Dumps the raw HTML/JSON response.
  

Extension Points

1. Custom Scrapers Override the default scraper:

   ReferenceCar::resolver(function () {
       return new CustomScraper();
   });
   

2. Model Events Listen for data updates:

   ReferenceCar::brands()->updated(function ($brand) {
       // Trigger notifications, etc.
   });
   

3. Local Overrides Mock data for testing:

   ReferenceCar::setMockData([
       'brands' => ['Tesla', 'Rivian'],
   ]);