Rayacom Laravel Package

Getting Started

First Steps

1. Installation Clone the repository and install dependencies via Composer:

   composer require milestone/rayacom
   

   Publish the package configuration (if available) and run migrations:

   php artisan vendor:publish --provider="Milestone\RayaCom\RayaComServiceProvider"
   php artisan migrate
   

2. Initial Setup

   • Review the config/rayacom.php file for API keys, endpoints, and default settings.
   • Check the routes/rayacom.php file (if included) for predefined routes or register them manually in routes/web.php:

     Route::prefix('api/rayacom')->group(function () {
         Route::middleware('auth:sanctum')->group(base_path('vendor/milestone/rayacom/routes/api.php'));
     });
     

3. First Use Case: Product Fetching Use the package’s facade or service class to fetch products from Rayaheen’s API:

   use Milestone\RayaCom\Facades\RayaCom;
   
   $products = RayaCom::products()->fetch();
   return response()->json($products);
   

   • Verify the response structure and handle errors (e.g., rate limits, invalid API keys).

Implementation Patterns

Core Workflows

1. API Integration

   • Facade-Based Calls: Use RayaCom::endpoint()->method() for simplicity (e.g., RayaCom::orders()->create()).
   • Service Class: For complex logic, inject the RayaComService into controllers:

     public function __construct(private RayaComService $rayacom) {}
     

   • Custom Endpoints: Extend the package by creating a custom service class:

     class CustomRayaCom extends RayaComService {
         public function customEndpoint() {
             return $this->callApi('custom/endpoint');
         }
     }
     

2. Data Transformation

   • Use Laravel’s map or transform to adapt Rayaheen’s response to your models:

     $products = RayaCom::products()->fetch()->map(function ($item) {
         return new Product([
             'name' => $item->title,
             'price' => $item->price->amount,
         ]);
     });
     

   • Leverage Laravel’s Resource classes for API responses:

     public function toArray($request) {
         return [
             'id' => $this->id,
             'name' => $this->name,
             'rayacom_price' => $this->price->amount,
         ];
     }
     

3. Webhook Handling

   • If Rayaheen supports webhooks, create a controller to handle incoming requests:

     public function handleWebhook(Request $request) {
         $payload = $request->json()->all();
         // Validate payload (e.g., signature, event type)
         event(new RayaComWebhookReceived($payload));
     }
     

   • Dispatch events or update local models accordingly.

4. Authentication

   • Store API credentials in .env (e.g., RAYACOM_API_KEY) and use Laravel’s config('rayacom.api_key').
   • For OAuth flows, extend the package’s auth logic or use Laravel Passport.

Integration Tips

• Queue Delayed Tasks: Offload API calls to queues (e.g., dispatch(new SyncProductsJob())).
• Caching: Cache frequent API responses (e.g., product lists) with Cache::remember:

  $products = Cache::remember('rayacom_products', now()->addHours(1), function () {
      return RayaCom::products()->fetch();
  });
  

• Logging: Log API errors and responses for debugging:

  RayaCom::products()->fetch()->each(function ($product) {
      \Log::debug('Fetched product:', ['data' => $product]);
  });
  

Gotchas and Tips

Pitfalls

1. Deprecated/Undocumented Features

   • The package has no stars or dependents, suggesting limited community validation. Test thoroughly.
   • Check the 2022-11-28 release for breaking changes.

2. API Rate Limits

   • Rayaheen may throttle requests. Implement exponential backoff:

     try {
         $response = RayaCom::orders()->fetch();
     } catch (\GuzzleHttp\Exception\RequestException $e) {
         if ($e->getCode() === 429) {
             sleep(5); // Retry after 5 seconds
             retry();
         }
     }
     

3. Missing Error Handling

   • The package may lack granular error classes. Extend it:

     throw new \Milestone\RayaCom\Exceptions\InvalidProductException('Product not found');
     

4. Configuration Overrides

   • If config/rayacom.php is missing, manually define defaults in config/app.php or override via service provider:

     $this->app->singleton(RayaComService::class, function ($app) {
         return new RayaComService([
             'api_key' => env('RAYACOM_API_KEY', 'default_key'),
             'base_url' => env('RAYACOM_BASE_URL', 'https://api.rayaheen.com'),
         ]);
     });
     

Debugging Tips

• Enable Guzzle Middleware to inspect requests/responses:

  RayaCom::withMiddleware()->fetch(); // If supported
  

  Or use Laravel’s tap:

  RayaCom::products()->fetch()->tap(function ($response) {
      \Log::info('Raw response:', $response->getBody());
  });
  

• Test with Postman/cURL to verify Rayaheen’s API behavior before integrating.

Extension Points

1. Custom Endpoints Add new methods to the RayaComService class:

   public function getInventory($productId) {
       return $this->callApi("products/{$productId}/inventory");
   }
   

2. Model Observers Sync local models with Rayaheen’s data:

   class ProductObserver {
       public function saved(Product $product) {
           RayaCom::products()->update($product->id, $product->toRayaComArray());
       }
   }
   

3. Service Provider Binding Override the package’s service binding in AppServiceProvider:

   $this->app->bind(RayaComService::class, function ($app) {
       return new CustomRayaComService($app['config']['rayacom']);
   });
   

4. Webhook Validation Validate Rayaheen’s webhook signatures (if supported):

   $signature = hash_hmac('sha256', $request->getContent(), config('rayacom.webhook_secret'));
   if (!hash_equals($request->header('X-RayaCom-Signature'), $signature)) {
       abort(403);
   }