Megamarket Laravel Package

## Getting Started

### Minimal Steps to First Use
1. **Install the Package**
   ```bash
   composer require baks-dev/megamarket
   php artisan vendor:publish --provider="BaksDev\Megamarket\MegamarketServiceProvider"

• Publishes config files to config/megamarket.php.

2. Set Up Environment

   • Configure .env with Megamarket API credentials (e.g., MEGAMARKET_TOKEN, MEGAMARKET_API_URL).
   • Define queue transport for Messenger (e.g., Redis, RabbitMQ):

     MESSENGER_TRANSPORT_DSN=redis://localhost:6379/0
     

3. Run Asset Installation

   php artisan baks:assets:install
   

   • Initializes default configurations, migrations, and queue transports.

4. First API Call (Example: Fetch Products)

   use BaksDev\Megamarket\Facades\Megamarket;
   
   $products = Megamarket::products()->fetch();
   dd($products);
   

   • Uses Laravel’s facades for simplicity (if configured).

5. Test with Queues

   • Dispatch a job to sync catalog asynchronously:

     use BaksDev\Megamarket\Jobs\SyncCatalog;
     
     SyncCatalog::dispatch()->onQueue('megamarket');
     

   • Verify queue worker processes it:

     php artisan queue:work
     

Implementation Patterns

Core Workflows

1. API Integration

• Facade Pattern: Use Megamarket facade for common endpoints (e.g., products(), orders(), categories()).

  $orders = Megamarket::orders()->withStatus('pending')->fetch();
  

• Custom Endpoints: Extend via service providers:

  // app/Providers/MegamarketServiceProvider.php
  public function boot()
  {
      Megamarket::extend('custom', function () {
          return new CustomMegamarketClient();
      });
  }
  

2. Queue-Based Sync

• Job Dispatching: Offload heavy operations (e.g., catalog sync, order processing) to queues.

  // Dispatch a job to fetch and store products
  SyncProductsJob::dispatch()->onQueue('megamarket_products');
  

• Retry Logic: Leverage Messenger’s built-in retry strategy (configured in config/megamarket.php):

  $messenger->transport('megamarket')
      ->retryStrategy()
      ->maxRetries(3)
      ->delay(1000);
  

3. Event-Driven Extensions

• Listen for Megamarket Events: Hook into order/product updates via Laravel events.

  // app/Listeners/HandleMegamarketOrder.php
  public function handle(OrderCreatedEvent $event)
  {
      // Trigger custom logic (e.g., notify admin, update inventory)
  }
  

• Publish Events: Extend the package to emit events:

  event(new MegamarketOrderProcessed($order));
  

4. Configuration Management

• Dynamic Tokens: Rotate API tokens via config or environment variables:

  config(['megamarket.tokens.default' => env('MEGAMARKET_TOKEN')]);
  

• Environment-Specific Setups: Use Laravel’s config/caching or .env files to switch between dev/staging/prod.

Integration Tips

Laravel-Symfony Bridge

• Messenger Queues: Use laravel-messenger to bridge Symfony Messenger with Laravel’s queue system:

  // config/messenger.php
  'transports' => [
      'megamarket' => [
          'dsn' => env('REDIS_URL'),
          'options' => ['queue' => 'megamarket'],
          'retry_strategy' => [
              'max_retries' => 3,
              'delay' => 1000,
          ],
      ],
  ],
  

• Console Commands: Register Symfony commands as Laravel Artisan commands:

  // app/Console/Kernel.php
  protected $commands = [
      \BaksDev\Megamarket\Command\SyncCatalogCommand::class,
  ];
  

Database and ORM

• Doctrine vs. Eloquent: Avoid direct Doctrine usage. Instead:
  • Use repositories to abstract data access:

    $products = app(\BaksDev\Megamarket\Repository\ProductRepository::class)->findAll();
    

  • Or translate queries to Eloquent:

    // Example: Convert Doctrine query to Eloquent
    $builder = Megamarket::products()->getQueryBuilder();
    $eloquentQuery = Product::query()->whereRaw($builder->getDQL());
    

Testing

• Unit Tests: Mock the Megamarket client:

  $client = Mockery::mock(\BaksDev\Megamarket\Client::class);
  $client->shouldReceive('fetchProducts')->andReturn([]);
  
  $this->app->instance(\BaksDev\Megamarket\Client::class, $client);
  

• Feature Tests: Use Laravel’s HTTP tests for API endpoints:

  public function test_marketplace_integration()
  {
      $response = $this->get('/api/megamarket/products');
      $response->assertStatus(200);
  }
  

Gotchas and Tips

Pitfalls

1. Symfony-Laravel Dependency Conflicts

   • Issue: Symfony components (e.g., symfony/http-client) may conflict with Laravel’s versions.
   • Fix: Pin versions in composer.json:

     "require": {
         "symfony/http-client": "^6.0",
         "symfony/messenger": "^6.0"
     }
     

   • Workaround: Use Laravel’s HttpClient for API calls instead of Symfony’s.

2. Queue Transport Mismatches

   • Issue: Messenger’s queue transports may not align with Laravel’s queue drivers.
   • Fix: Configure laravel-messenger to use Laravel’s queue adapters:

     $messenger->transport('megamarket')
         ->dsn('doctrine://default') // Use Laravel's database queue
         ->options(['queue' => 'megamarket']);
     

3. Token Management Quirks

   • Issue: Megamarket tokens may expire or require rotation, but the package lacks built-in refresh logic.
   • Fix: Extend the token handler:

     // app/Providers/MegamarketServiceProvider.php
     Megamarket::extend('token_refresh', function () {
         return new RefreshableTokenHandler();
     });
     

4. Doctrine ORM in Laravel

   • Issue: Direct Doctrine usage breaks Laravel’s Eloquent conventions.
   • Fix: Use repositories or query builders to translate Doctrine logic:

     // Convert Doctrine query to Eloquent
     $doctrineQuery = $entityManager->createQuery('SELECT p FROM Product p');
     $eloquentQuery = Product::query()->whereRaw($doctrineQuery->getSQL());
     

5. Undocumented Features

   • Issue: The package lacks clear documentation for advanced features (e.g., webhooks, advanced filtering).
   • Fix: Explore the source (vendor/baks-dev/megamarket/src/) and write internal docs:

     php artisan ide-helper:generate --nowrite --dir=vendor/baks-dev/megamarket
     

Debugging Tips

1. Enable Messenger Debugging

   // config/messenger.php
   'debug' => env('APP_DEBUG', false),
   

   • Logs queue messages to storage/logs/messenger.log.

2. Symfony Dumpers

   • Use Symfony’s var_dump() or dd() for debugging:

     use Symfony\Component\VarDumper\VarDumper;
     
     VarDumper::dump($variable);
     

3. Queue Worker Logging

   • Tail queue worker logs:

     php artisan queue:work --once --verbose
     

4. API Response Inspection

   • Log raw API responses:

     Megamarket::setDebug(true);
     $response = Megamarket::products()->fetch();
     

Extension Points

1. Custom API Endpoints

   • Extend the client via service providers:

     Megamarket::extend('custom_endpoint', function () {
         return new CustomEndpointClient();
     });
     

2. Event Listeners

   • Listen to Megamarket events (e.g., OrderCreated, ProductUpdated):

     event(new MegamarketOrderCreated($order));
     

3. Queue Handlers

   • Override default job handlers:

     $messenger->getBus()->addHandler