Avito Board Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require baks-dev/avito-board baks-dev/core:^7.4
   

   Verify php artisan package:discover detects the package.

2. Publish Assets:

   php artisan vendor:publish --provider="BaksDev\AvitoBoard\AvitoBoardServiceProvider" --tag="config"
   

   Update config/avito-board.php with your Avito API credentials (client ID, secret, and sandbox mode).

3. First Integration: Use the facade to fetch ads in a controller:

   use BaksDev\AvitoBoard\Facades\AvitoBoard;
   
   public function showAds(Request $request) {
       $ads = AvitoBoard::searchAds($request->query('q'), $request->query('category', 'all'));
       return view('ads.index', ['ads' => $ads]);
   }
   

4. Route Setup: Add routes in routes/web.php:

   use Illuminate\Support\Facades\Route;
   use BaksDev\AvitoBoard\Http\Controllers\AdController;
   
   Route::get('/ads', [AdController::class, 'index']);
   

5. Blade Template: Render ads in resources/views/ads/index.blade.php:

   @foreach($ads as $ad)
       <div class="ad-card">
           <h3>{{ $ad->title }}</h3>
           <p>{{ $ad->price }} ₽</p>
           <img src="{{ $ad->imageUrl }}" alt="{{ $ad->title }}">
       </div>
   @endforeach
   

6. Test Locally: Run the avito-board test group to verify core functionality:

   php artisan test --group=avito-board
   

Implementation Patterns

Core Workflows

1. Ad Listing Management:

   • Create/Update Ads:

     $ad = AvitoBoard::createAd([
         'title' => 'Laptop for Sale',
         'description' => 'Used MacBook Pro...',
         'price' => 120000,
         'category' => 'notebooks',
         'images' => ['url1.jpg', 'url2.jpg'],
     ]);
     

   • Fetch Ads:

     $ads = AvitoBoard::getAds('notebooks', 20, 1); // Category, limit, page
     

2. Search Functionality:

   • Query Ads:

     $results = AvitoBoard::searchAds('laptop', 'notebooks', ['price_max' => 150000]);
     

   • Filter Ads:

     $filteredAds = AvitoBoard::filterAds($ads, ['region' => 'moscow', 'price_min' => 100000]);
     

3. User Authentication:

   • OAuth Flow:

     $authUrl = AvitoBoard::getAuthUrl(['scope' => 'ads']);
     // Redirect user to $authUrl
     $user = AvitoBoard::handleAuthCallback($request);
     

4. Webhooks (Async Events):

   • Listen for ad status changes:

     AvitoBoard::onAdStatusChanged(function ($ad) {
         // Update local DB or notify users
     });
     

Integration Tips

• Laravel Service Provider: Extend the package’s AvitoBoardServiceProvider to bind custom services:

  public function register() {
      $this->app->singleton('avito.board.cache', function () {
          return Cache::store('redis')->rememberForever('avito_ads', function () {
              return AvitoBoard::getAds('all');
          });
      });
  }
  

• Eloquent Models: Sync Avito ads with local models:

  use BaksDev\AvitoBoard\Models\AvitoAd;
  use App\Models\Ad;
  
  $avitoAd = AvitoAd::find($id);
  Ad::updateOrCreate(
      ['avito_id' => $avitoAd->id],
      $avitoAd->toArray()
  );
  

• Blade Directives: Create custom Blade directives for Avito-specific logic:

  Blade::directive('avitoPrice', function ($expression) {
      return "<?php echo BaksDev\AvitoBoard\Helpers\Price::format({$expression}); ?>";
  });
  

  Usage:

  @avitoPrice($ad->price)
  

• Queue Jobs: Offload heavy operations (e.g., ad publishing):

  use BaksDev\AvitoBoard\Jobs\PublishAd;
  
  PublishAd::dispatch($adData)->onQueue('avito');
  

• Middleware: Restrict Avito routes:

  Route::middleware(['auth', 'avito.auth'])->group(function () {
      Route::post('/ads', [AdController::class, 'store']);
  });
  

• Events: Subscribe to Avito events:

  event(new \BaksDev\AvitoBoard\Events\AdPublished($ad));
  

Common Patterns

Gotchas and Tips

Pitfalls

1. Symfony-Laravel Conflicts:

   • Issue: Symfony’s EventDispatcher may clash with Laravel’s Events. Fix: Use Laravel’s Event facade and bind Symfony events via a service provider:

     $this->app->bind(
         \Symfony\Component\EventDispatcher\EventDispatcherInterface::class,
         function () {
             return new class extends \Illuminate\Events\Dispatcher {
                 // Override Symfony-specific methods
             };
         }
     );
     

2. Dependency on baks-dev/core:

   • Issue: The package requires baks-dev/core:^7.4, which may introduce Laravel incompatibilities. Fix: Fork the core package or replace dependencies (e.g., use Laravel’s illuminate/support instead of Symfony components).

3. Undocumented API:

   • Issue: Avito’s API endpoints or response formats may change without notice. Fix: Implement a feature flag for Avito-specific logic:

     if (config('avito-board.enabled')) {
         $ads = AvitoBoard::getAds();
     } else {
         $ads = Cache::get('fallback_ads');
     }
     

4. Rate Limiting:

   • Issue: Avito may throttle requests during high traffic. Fix: Use Laravel’s throttle middleware and implement exponential backoff:

     Route::middleware(['throttle:60,1'])->group(function () {
         Route::get('/ads', [AdController::class, 'index']);
     });
     

5. Caching Quirks:

   • Issue: Avito’s cache headers may not align with Laravel’s cache drivers. Fix: Use Cache::rememberForever with a custom cache key:

     Cache::rememberForever("avito_ads_{$category}_{$page}", function () use ($category, $page) {
         return AvitoBoard::getAds($category, 20, $page);
     });
     

6. Blade vs. Twig:

   • Issue: The package uses Twig templates, which won’t render in Laravel. Fix: Convert Twig to Blade or use a Twig-to-Blade compiler like tightenco/ziggy.

7. Authentication Flow:

   • Issue: Avito’s OAuth may redirect to external URLs, breaking Laravel’s session. Fix: Use Laravel’s Session and Redirect helpers to handle callbacks:

     return Redirect::to(AvitoBoard::handleAuthCallback($request))->with('auth', $user);
     

8. Database Migrations:

   • Issue: Doctrine migrations (if used) won’t work with Laravel’s Schema builder. Fix: Manually create Eloquent migrations for Avito-related tables.

Debugging Tips

1. Enable Avito Debug Mode:

   config(['avito-board.debug' => true]);
   

   This logs API requests/responses to storage/logs/avito-board.log.

2. Mock Avito API: Use Laravel’s HTTP client to mock responses:

   $mockResponse = ['data' => ['ads' => []]];
   AvitoBoard::setClient(Http::fake($mockResponse));
   

3. Test Avito Events: Listen for events in tests