Mx Api Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require artack/mx-api
   

   (Note: Due to the package being archived, verify compatibility with your Laravel version.)

2. Service Provider & Facade Add to config/app.php under providers:

   Artack\MxApi\MxApiServiceProvider::class,
   

   Publish config (if available):

   php artisan vendor:publish --provider="Artack\MxApi\MxApiServiceProvider"
   

3. First API Call

   use Artack\MxApi\Facades\MxApi;
   
   $response = MxApi::get('/endpoint', ['param' => 'value']);
   $data = $response->json();
   

4. Configuration Check .env or config/mx-api.php for:

   • Base API URL
   • API keys/auth tokens
   • Default headers (e.g., Accept: application/json)

First Use Case: Fetching User Data

// Fetch a user's profile
$userData = MxApi::get('/users/{id}', ['id' => 123]);

// Handle response
if ($userData->successful()) {
    $name = $userData->json()['name'];
} else {
    $error = $userData->json()['error'];
}

Implementation Patterns

1. Request Workflows

• GET Requests

  MxApi::get('/users', ['active' => true]);
  

• POST Requests (with payload)

  MxApi::post('/users', ['name' => 'John', 'email' => 'john@example.com']);
  

• Authentication Attach tokens via config or dynamically:

  MxApi::withHeaders(['Authorization' => 'Bearer ' . $token])
       ->get('/protected-route');
  

2. Response Handling

• JSON Parsing

  $data = MxApi::get('/data')->json();
  

• Status Checks

  if (MxApi::get('/status')->ok()) {
      // Success logic
  }
  

• Error Handling

  try {
      $response = MxApi::get('/fail');
  } catch (\Artack\MxApi\Exceptions\ApiException $e) {
      Log::error($e->getMessage());
  }
  

3. Integration with Laravel Features

• Queue Jobs for Async Calls

  dispatch(new FetchMxDataJob($params));
  

  (Assuming the package supports queuing or you wrap it in a job.)

• Middleware for API Guard

  // app/Http/Middleware/CheckMxApi.php
  public function handle($request, Closure $next) {
      if (MxApi::get('/health')->failed()) {
          abort(503, 'MX API unavailable');
      }
      return $next($request);
  }
  

• Caching Responses

  $data = Cache::remember('mx_user_123', now()->addHours(1), function () {
      return MxApi::get('/users/123')->json();
  });
  

4. Testing

• Mocking API Calls

  $mock = Mockery::mock('overload', Artack\MxApi\Facades\MxApi::class);
  $mock->shouldReceive('get')
       ->with('/test')
       ->andReturn(response()->json(['mocked' => true]));
  

Gotchas and Tips

Pitfalls

1. Archived Package Risks

   • No active maintenance; test thoroughly for Laravel version compatibility.
   • Check for deprecated methods or breaking changes in documentation (if any exists).

2. Error Handling Gaps

   • The package may lack detailed error messages. Extend with custom exceptions:

     try {
         $response = MxApi::post('/create', $data);
     } catch (\Exception $e) {
         throw new \Artack\MxApi\Exceptions\ValidationException(
             $response->json()['errors'] ?? $e->getMessage()
         );
     }
     

3. Rate Limiting

   • No built-in retry logic. Implement exponential backoff:

     use Symfony\Component\HttpClient\RetryStrategy;
     
     $client = MxApi::getClient()
         ->withOptions([
             'max_retries' => 3,
             'retry_delay' => 100,
         ]);
     

4. Config Overrides

   • Dynamic config changes (e.g., switching API environments) may not persist across requests. Use dependency injection:

     $api = new \Artack\MxApi\Client(['base_uri' => $dynamicUrl]);
     

Debugging Tips

• Enable Guzzle Debugging Add to config/mx-api.php:

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

  (If supported; otherwise, use a Guzzle middleware.)

• Log Raw Responses

  $response = MxApi::get('/data');
  Log::debug('MX API Response', [
      'status' => $response->status(),
      'body' => $response->getBody(),
      'headers' => $response->headers(),
  ]);
  

Extension Points

1. Custom Request Factories Extend the base client for project-specific needs:

   class ProjectMxApi extends \Artack\MxApi\Client {
       public function customEndpoint($params) {
           return $this->post('/custom', $params)->json();
       }
   }
   

2. Event Listeners Trigger events on API calls (if the package supports it):

   // Example: Log all API calls
   MxApi::getClient()->on('request', function ($request) {
       Log::info('MX API Request', [
           'method' => $request->getMethod(),
           'uri' => $request->getUri(),
       ]);
   });
   

3. Middleware for Requests Add preprocessing/POST-processing:

   MxApi::getClient()->getEmitter()->addSubscriber(
       new class implements \Symfony\Contracts\HttpClient\EventListener\EventListenerInterface {
           public function onEvent(object $event) { /* ... */ }
       }
   );
   

Performance Tips

• Connection Pooling Reuse the Guzzle client instance:

  $client = MxApi::getClient(); // Singleton
  $response = $client->request('GET', '/data');
  

• Parallel Requests Use Guzzle’s Promise for concurrent calls:

  $promises = [
      MxApi::getClient()->request('GET', '/users'),
      MxApi::getClient()->request('GET', '/posts'),
  ];
  $results = \GuzzleHttp\Promise\Utils::settle($promises)->wait();