gajus/drill

Mandrill API interface with no bells and whistles.

0.0.3 2014-08-26 15:50 UTC

Requires

• php: >=5.3

Requires (Dev)

• satooshi/php-coveralls: dev-master

BSD-3-Clause

• Gajus Kuizinas

• email
• mandrill

README

Mandrill API interface with no bells and whistles.

Drill Client implementation makes no assumptions about the underlying API schema or required parameters. However, it will throw an exception when you do not provide the required parameters based on the response. Therefore, it is not an abstraction that will prevent your code from braking if/when Mandrill API changes. It is used to interact with the API endpoint and handle errors. That said, Mandrill RESTful API implements versioning, which ought to prevent breaking code that is using Drill implementation when API changes occur.

The only provided method is api

/**
 * @param string $key Mandrill API key.
 */
$drill = new \Gajus\Drill\Client('NlLdhX5FVKS55VBK1xPW_g');

/**
 * @see https://mandrillapp.com/api/docs/messages.JSON.html
 * @param string $path
 * @param array $parameters
 */
$response = $drill->api('messages/send', [
    'message' => [
        'text' => 'Test',
        'subject' => 'test',
        'from_email' => '[e-mail]',
        'to' => [
            ['email' => '[e-mail]']
        ],
    ]
]);

Mandrill response is converted to an associative array:

array(1) {
  [0]=>
  array(4) {
    ["email"]=>
    string(15) "[e-mail]"
    ["status"]=>
    string(4) "sent"
    ["_id"]=>
    string(32) "f65f65c266f74e2884344ccfff3bb337"
    ["reject_reason"]=>
    NULL
  }
}

Handling errors

Cases that can be caught before making a request to the API or rules that are enforced by Drill implementation, as opposed to the API spec, will throw Gajus\Drill\Exception\InvalidArgumentException.

All errors that occur during the runtime will result in Gajus\Drill\Exception\ErrorException.

Beware that errors returned from Mandrill API have inconsistent naming convention (CamelCase vs underscore, e.g. "UserError", "Invalid_Key"). Drill will cast all errors to CamelCase convention (e.g. "Invalid_Key" becomes "InvalidKeyException").

$drill = new \Gajus\Drill\Client('fxBTBjWKxJ05K9MjkFak1A');

try {
  $response = $drill->api('messages/send', [
      'message' => [
          'text' => 'Test',
          'subject' => 'test',
          'from_email' => 'invalidemail',
          'to' => [
              ['email' => '[e-mail]']
          ],
      ]
  ]);
} catch (\Gajus\Drill\Exception\RuntimeException\ValidationErrorException $e) {
    // @see https://mandrillapp.com/api/docs/messages.html
} catch (\Gajus\Drill\Exception\RuntimeException\UserErrorException $e) {
    // @see https://mandrillapp.com/api/docs/messages.html
} catch (\Gajus\Drill\Exception\RuntimeException\UnknownSubaccountException $e) {
    // @see https://mandrillapp.com/api/docs/messages.html
} catch (\Gajus\Drill\Exception\RuntimeException\PaymentRequiredException $e) {
    // @see https://mandrillapp.com/api/docs/messages.html
} catch (\Gajus\Drill\Exception\RuntimeException\GeneralErrorException $e) {
    // @see https://mandrillapp.com/api/docs/messages.html
} catch (\Gajus\Drill\Exception\RuntimeException\ValidationErrorException $e) {
    // @see https://mandrillapp.com/api/docs/messages.html
} catch (\Gajus\Drill\Exception\RuntimeException $e) {
    // All possible API errors.
} catch (\Gajus\Drill\Exception\InvalidArgumentException $e) {
    // Invalid SDK use errors.
} catch (\Gajus\Drill\Exception\DrillException $e) {
    // Everything.
}