Mx Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require artack/mx-api-bundle
   

   Run composer update if needed.

2. Enable the Bundle Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3/2):

   Artack\MxApiBundle\ArtackMxApiBundle::class => ['all' => true],
   

3. First API Call Inject the service and use the fluent interface:

   use Artack\MxApiBundle\Service\ArtackMxApi;
   
   class MyController extends Controller
   {
       public function index(ArtackMxApi $mxapi)
       {
           $response = $mxapi->setPath('Contact')->get();
           return response()->json($response);
       }
   }
   

4. Configuration Publish the default config (if available) and update config/packages/artack_mx_api.yaml:

   php bin/console config:dump-reference artack_mx_api
   

Implementation Patterns

Core Workflows

1. CRUD Operations Use the fluent interface for common API actions:

   // Create
   $mxapi->setPath('Contact')->setData(['email' => 'test@example.com'])->post();
   
   // Read
   $mxapi->setPath('Contact')->get();
   
   // Update
   $mxapi->setPath('Contact/{id}')->setData(['status' => 'active'])->put();
   
   // Delete
   $mxapi->setPath('Contact/{id}')->delete();
   

2. Handling Responses Parse responses with Symfony’s Serializer:

   $response = $mxapi->setPath('Campaign')->get();
   $data = $this->get('serializer')->decode($response, 'json');
   

3. Authentication Pass credentials via config or dynamically:

   # config/packages/artack_mx_api.yaml
   artack_mx_api:
       api_key: 'your_api_key_here'
       api_secret: 'your_api_secret_here'
   

   Or override in code:

   $mxapi->setAuth('api_key', 'api_secret');
   

4. Error Handling Wrap API calls in try-catch:

   try {
       $mxapi->setPath('Newsletter')->post();
   } catch (\Artack\MxApi\Exception\ApiException $e) {
       $this->addFlash('error', $e->getMessage());
   }
   

Integration Tips

• Laravel-Specific: Use Laravel’s Http facade for compatibility:

  $client = new \Artack\MxApiBundle\Client\BuzzClient(
      new \GuzzleHttp\Client(),
      $this->app['config']['artack_mx_api']
  );
  

• Queue Jobs: Offload API calls to queues for long-running tasks:

  dispatch(new SyncContactsJob($mxapi));
  

• Caching: Cache frequent API responses:

  $cacheKey = 'mx_contacts_' . md5('Contact');
  $response = Cache::remember($cacheKey, 3600, function () use ($mxapi) {
      return $mxapi->setPath('Contact')->get();
  });
  

Gotchas and Tips

Common Pitfalls

1. Deprecated API Endpoints The README warns of "recent changes to the API." Verify endpoints exist via the mailXpert API docs (if available).

2. Buzz Client Dependency The bundle uses kriswallsmith/buzz (dev-master). Pin the version in composer.json to avoid breaking changes:

   "kriswallsmith/buzz": "dev-master@dev"
   

3. Symfony Serializer Version Requires symfony/serializer:>=2.0,<2.3-dev. Conflicts may arise with newer Symfony versions. Downgrade or fork the bundle if needed.

4. No Laravel Service Provider The bundle is Symfony-based. Manually register the service in Laravel’s AppServiceProvider:

   $this->app->bind('artack.mxapi', function ($app) {
       return new \Artack\MxApi\ArtackMxApi(
           new \Artack\MxApiBundle\Client\BuzzClient(
               new \GuzzleHttp\Client(),
               $app['config']['artack_mx_api']
           )
       );
   });
   

Debugging Tips

• Enable Debug Mode Set debug: true in config to log raw API responses:

  artack_mx_api:
      debug: true
  

• Check HTTP Headers Use setHeaders() to add custom headers (e.g., Accept: application/json):

  $mxapi->setHeaders(['Accept' => 'application/json']);
  

• Validate API Keys Test credentials with a simple endpoint first:

  $mxapi->setPath('System/Info')->get();
  

Extension Points

1. Custom Clients Extend \Artack\MxApiBundle\Client\AbstractClient to support Guzzle or other HTTP clients:

   class GuzzleClient extends AbstractClient
   {
       public function __construct(\GuzzleHttp\Client $client, array $config)
       {
           $this->client = $client;
           $this->config = $config;
       }
   }
   

2. Response Transformers Override response handling in a decorator:

   class DecoratedMxApi implements \Artack\MxApi\ArtackMxApiInterface
   {
       protected $mxapi;
   
       public function __construct(ArtackMxApi $mxapi)
       {
           $this->mxapi = $mxapi;
       }
   
       public function get()
       {
           $response = $this->mxapi->get();
           return $this->transformResponse($response);
       }
   
       protected function transformResponse($response)
       {
           // Custom logic (e.g., normalize data)
           return $response;
       }
   }
   

3. Event Listeners Listen for API events (if the bundle dispatches them). Example for Symfony:

   # config/services.yaml
   services:
       App\EventListener\MxApiListener:
           tags:
               - { name: kernel.event_listener, event: artack.mxapi.response, method: onResponse }