Make API client open for extending API call in the SDK (#836)

* Make API client open for extending API call in the SDK

* Fix code style

* Fix code style

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Change Log
 
 The change log describes what is "Added", "Removed", "Changed" or "Fixed" between each release.
+## 3.5.4
+
+### Added
+- Added ability to make own API request to needed endpoint
 
 ## 3.5.3
 

README.md

@@ -79,6 +79,32 @@ $result = $mgClient->domains()->updateWebScheme($domain, 'https');
 print_r($result);
 ```
 
+### Custom http request to the API
+
+```php
+<?php
+# Include the Autoloader (see "Libraries" for install instructions)
+require 'vendor/autoload.php';
+use Mailgun\Mailgun;
+
+# Instantiate the client.
+$mgClient = Mailgun::create('KEY', 'ENDPOINT');
+$domain = "DOMAIN";
+
+$path = 'some path';
+$params = [];
+
+# Issue the call to the client.
+$resultPost = $mgClient->httpClient()->httpPost($path, $params);
+
+$resultGet = $mgClient->httpClient()->httpGet($path, $params);
+
+$resultPut = $mgClient->httpClient()->httpPut($path, $params);
+
+$resultDelete = $mgClient->httpClient()->httpDelete($path, $params);
+
+```
+
 ### All usage examples
 
 You will find more detailed documentation at [/doc](doc/index.md) and on

src/Api/HttpClient.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Http\Client\Common\PluginClient;
+use Mailgun\HttpClient\RequestBuilder;
+use Psr\Http\Client\ClientExceptionInterface;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @see    https://documentation.mailgun.com/api-domains.html
+ *
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+class HttpClient extends HttpApi
+{
+    /**
+     * @return PluginClient|ClientInterface
+     */
+    public function getHttpClient()
+    {
+        return $this->httpClient;
+    }
+
+    /**
+     * @return RequestBuilder
+     */
+    public function getRequestBuilder(): RequestBuilder
+    {
+        return $this->requestBuilder;
+    }
+
+    /**
+     * @param  string                   $path
+     * @param  array                    $parameters
+     * @param  array                    $requestHeaders
+     * @return ResponseInterface
+     * @throws ClientExceptionInterface
+     */
+    public function httpDelete(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
+    {
+        return parent::httpDelete($path, $parameters, $requestHeaders);
+    }
+
+    /**
+     * @param  string                   $path
+     * @param  array                    $parameters
+     * @param  array                    $requestHeaders
+     * @return ResponseInterface
+     * @throws ClientExceptionInterface
+     */
+    public function httpGet(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
+    {
+        return parent::httpGet($path, $parameters, $requestHeaders);
+    }
+
+    /**
+     * @param  string            $path
+     * @param  array             $parameters
+     * @param  array             $requestHeaders
+     * @return ResponseInterface
+     */
+    public function httpPost(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
+    {
+        return parent::httpPost($path, $parameters, $requestHeaders);
+    }
+
+    /**
+     * @param  string                   $path
+     * @param  array                    $parameters
+     * @param  array                    $requestHeaders
+     * @return ResponseInterface
+     * @throws ClientExceptionInterface
+     */
+    public function httpPut(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
+    {
+        return parent::httpPut($path, $parameters, $requestHeaders);
+    }
+
+    /**
+     * @param  string                   $path
+     * @param  array|string             $body
+     * @param  array                    $requestHeaders
+     * @return ResponseInterface
+     * @throws ClientExceptionInterface
+     */
+    public function httpPostRaw(string $path, $body, array $requestHeaders = []): ResponseInterface
+    {
+        return parent::httpPostRaw($path, $body, $requestHeaders);
+    }
+}

src/Mailgun.php

@@ -12,6 +12,21 @@ declare(strict_types=1);
 namespace Mailgun;
 
 use Http\Client\Common\PluginClient;
+use Mailgun\Api\Attachment;
+use Mailgun\Api\Domain;
+use Mailgun\Api\EmailValidation;
+use Mailgun\Api\EmailValidationV4;
+use Mailgun\Api\Event;
+use Mailgun\Api\HttpClient;
+use Mailgun\Api\Ip;
+use Mailgun\Api\Mailboxes;
+use Mailgun\Api\MailingList;
+use Mailgun\Api\Message;
+use Mailgun\Api\Route;
+use Mailgun\Api\Stats;
+use Mailgun\Api\Suppression;
+use Mailgun\Api\Tag;
+use Mailgun\Api\Webhook;
 use Mailgun\HttpClient\HttpClientConfigurator;
 use Mailgun\HttpClient\Plugin\History;
 use Mailgun\HttpClient\RequestBuilder;
@@ -52,6 +67,11 @@ class Mailgun
      */
     private $responseHistory;
 
+    /**
+     * @param HttpClientConfigurator $configurator
+     * @param Hydrator|null          $hydrator
+     * @param RequestBuilder|null    $requestBuilder
+     */
     public function __construct(
         HttpClientConfigurator $configurator,
         Hydrator $hydrator = null,
@@ -65,6 +85,11 @@ class Mailgun
         $this->responseHistory = $configurator->getResponseHistory();
     }
 
+    /**
+     * @param  string $apiKey
+     * @param  string $endpoint
+     * @return self
+     */
     public static function create(string $apiKey, string $endpoint = 'https://api.mailgun.net'): self
     {
         $httpClientConfigurator = (new HttpClientConfigurator())
@@ -74,78 +99,131 @@ class Mailgun
         return new self($httpClientConfigurator);
     }
 
+    /**
+     * @return ResponseInterface|null
+     */
     public function getLastResponse(): ?ResponseInterface
     {
         return $this->responseHistory->getLastResponse();
     }
 
+    /**
+     * @return Attachment
+     */
     public function attachment(): Api\Attachment
     {
         return new Api\Attachment($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return Domain
+     */
     public function domains(): Api\Domain
     {
         return new Api\Domain($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return EmailValidation
+     */
     public function emailValidation(): Api\EmailValidation
     {
         return new Api\EmailValidation($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return EmailValidationV4
+     */
     public function emailValidationV4(): Api\EmailValidationV4
     {
         return new Api\EmailValidationV4($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return Event
+     */
     public function events(): Api\Event
     {
         return new Api\Event($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return Ip
+     */
     public function ips(): Api\Ip
     {
         return new Api\Ip($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return MailingList
+     */
     public function mailingList(): Api\MailingList
     {
         return new Api\MailingList($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return Message
+     */
     public function messages(): Api\Message
     {
         return new Api\Message($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return Route
+     */
     public function routes(): Api\Route
     {
         return new Api\Route($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return Suppression
+     */
     public function suppressions(): Api\Suppression
     {
         return new Api\Suppression($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return Stats
+     */
     public function stats(): Api\Stats
     {
         return new Api\Stats($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return Tag
+     */
     public function tags(): Api\Tag
     {
         return new Api\Tag($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
 
+    /**
+     * @return Webhook
+     */
     public function webhooks(): Api\Webhook
     {
         return new Api\Webhook($this->httpClient, $this->requestBuilder, $this->hydrator, $this->apiKey);
     }
 
+    /**
+     * @return Mailboxes
+     */
     public function mailboxes(): Api\Mailboxes
     {
         return new Api\Mailboxes($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
+
+    /**
+     * @return HttpClient
+     */
+    public function httpClient(): Api\HttpClient
+    {
+        return new Api\HttpClient($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
 }