PHPackages                             stoyantodorov/laravel-api-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. stoyantodorov/laravel-api-client

ActiveLibrary[API Development](/categories/api)

stoyantodorov/laravel-api-client
================================

API client for Laravel

2.0.0(1y ago)010MITPHPPHP ^8.2

Since May 8Pushed 1y ago1 watchersCompare

[ Source](https://github.com/stoyantodorovbg/laravel-api-client)[ Packagist](https://packagist.org/packages/stoyantodorov/laravel-api-client)[ Docs](https://github.com/stoyantodorov/laravel-api-client)[ RSS](/packages/stoyantodorov-laravel-api-client/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (13)Versions (4)Used By (0)

Laravel HTTP Facade wrapper and Token service
=============================================

[](#laravel-http-facade-wrapper-and-token-service)

This package provides a way to use Laravel HTTP facade with error handling, logging and events firing. There is also Token Service that makes requests to retrieve access token depending on stored configurations or received parameters.

[![Latest Version on Packagist](https://camo.githubusercontent.com/c04a3cdbd6f7c96e11a8191cb7f0b11cc9c00c99182a2b514be68b5a2543f9f6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73746f79616e746f646f726f762f6c61726176656c2d6170692d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/stoyantodorov/laravel-api-client)[![Total Downloads](https://camo.githubusercontent.com/39be8725ce1c246b3e671d79c9d30a04a0d0159a437baf84c6bcb07e107ef1a7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73746f79616e746f646f726f762f6c61726176656c2d6170692d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/stoyantodorov/laravel-api-client)

Installation
------------

[](#installation)

```
composer require stoyantodorov/laravel-api-client
```

Usage
-----

[](#usage)

### HttpClient Service

[](#httpclient-service)

Resolve an **HttpClient** instance in a way that fits what you need, for example:

```
use Stoyantodorov\ApiClient\Interfaces\HttpClientInterface;

$apiClient = resolve(HttpClientInterface::class);
```

Send a request:

```
$response = $apiClient->get('https://exmple-host', ['queryParam' => 'value']);
```

You can configure **PendingRequest** in advance:

```
use Illuminate\Support\Facades\Http;

$apiClient->get('https://exmple-host', ['queryParam' => 'value'], Http::withToken($token));
```

You can also use **baseConfig** method to add base configurations:

```
$apiClien->baseConfig(retries: 3, retryInterval: 3000, timout: 60, connectTimeout: 5, userAgent: 'Test');
```

This method can receive a configured PendingRequest:

```
use Illuminate\Support\Facades\Http;

$apiClient->baseConfig(retries: 3, pendingRequest: Http::withToken($token));
```

Use **send** method for specific HTTP method and format:

```
use Stoyantodorov\ApiClient\Enums\HttpMethod;
use Stoyantodorov\ApiClient\Enums\HttpRequestFormat;

$apiClient->send(HttpMethod::CONNECT, 'https://exmple-host', HttpRequestFormat::QUERY, []);
```

Optionally you can add configured **PendingRequest** to it too:

```
use Illuminate\Support\Facades\Http;
use Stoyantodorov\ApiClient\Enums\HttpMethod;
use Stoyantodorov\ApiClient\Enums\HttpRequestFormat;

$apiClient->send(HttpMethod::CONNECT, 'https://exmple-host', HttpRequestFormat::QUERY, [], Http::withToken($token));
```

When you need to send a request without error handling, logging and event firing may use **sendRequest**:

```
use Stoyantodorov\ApiClient\Enums\HttpClientRequestMethod;

$apiClient->->sendRequest(HttpClientRequestMethod::GET, 'https://exmple-host');
```

Logging and event firing is configurable trough **config** values:

```
    'events' => [
        'onSuccess' => true,
        'onRequestException' => true,
        'onConnectionException' => true,
    ],
    'logs' => [
        'onRequestException' => true,
        'onConnectionException' => true,
    ],
```

These configurations can be overridden through **HttpClient** setters:

```
$apiClient->fireEventOnSuccess(false);
```

### Token Service

[](#token-service)

#### Factories

[](#factories)

There are two factories which instantiate **TokenService**. The first one sets configurations from **config** file:

```
use Stoyantodorov\ApiClient\Factories\TokenFromConfigFactory;

TokenFromConfigFactory::create();
```

When you are using this factory should set the relevant configurations in **api-client.php**:

```
'tokenConfigurationsBase' => [
        'accessTokenRequest' => [
            'url' => '',
            'body' => [],
            'headers' => [],
            'responseNestedKeys' => ['access_token'],
            'method' => 'post',
            'dispatchEvent' => true,
        ],
        'refreshTokenRequest' => [
            'url' => '',
            'body' => [],
            'headers' => [],
            'responseNestedKeys' => ['access_token'],
            'method' => 'post',
            'dispatchEvent' => true,
        ],
        'tokenRequestsRetries' => 3,
    ],
```

The second factory sets configurations from data objects:

```
use Stoyantodorov\ApiClient\Factories\TokenFromDataFactory;
use Stoyantodorov\ApiClient\Data\TokenData;

$tokenData new TokenData(
            url: 'https://example-host/access-token',
            body: ['username' => 'testValue', 'password' => 'testValue'],
        );

TokenFromDataFactory::create($tokenData);
```

When you are using an endpoint to refresh a token, the factories should be instructed to send such configurations:

```
TokenFromConfigFactory::create(hasRefreshTokenRequest: true);

use Stoyantodorov\ApiClient\Data\RefreshTokenData;
```

```
$refreshTokenData = new RefreshTokenData(
            url: 'https://example-host/refresh-token',
            body: ['refreshToken' => 'testValue'],
        );
TokenFromDataFactory::create(tokenData: $tokenData, refreshTokenData: $refreshTokenData);
```

You may instruct **TokenFromConfigFactory** to loads configurations from other config key:

```
TokenFromConfigFactory::create(configKey: 'anotherApiConfigurations');
```

If you have an already received token, can send it to both factories as optional parameter:

```
TokenFromConfigFactory::>create(token: 'someValueOrNull');
TokenFromDataFactory::create(token: 'someValueOrNull');
```

#### Obtain a token

[](#obtain-a-token)

**get** method sends a token request:

```
$service->get();
```

If the service is instantiated with an already obtained token, the method returns it instead of sending a new request.

The same method can also send a request that refreshes the token:

```
$service->get(refresh: true);
```

The JSON path to the token in the response should be set in **config** file:

```
'responseNestedKeys' => ['data', 'access_token'],
```

or in **TokenData** and **RefreshTokenData**

```
new TokenData(
            url: 'https://example-host/access-token',
            body: ['username' => 'testValue', 'password' => 'testValue'],
            responseNestedKeys: ['data', 'access_token'],
        );
new RefreshTokenData(
            url: 'https://example-host/refresh-token',
            body: ['refreshToken' => 'testValue'],
            responseNestedKeys: ['data', 'access_token'],
        );
```

When you need to access the response can subscribe for the events which are fired by default:

```
use Stoyantodorov\ApiClient\Events\AccessTokenObtained;

public function handle(AccessTokenObtained $event): void
{
    $response = $vent->response;
}
```

```
use Stoyantodorov\ApiClient\Events\AccessTokenRefreshed;

public function handle(AccessTokenRefreshed $event): void
{
    $response = $vent->response;
}
```

If you aren't using these events may switch them off from the **config** file:

```
'dispatchEvent' => false,
```

or **TokenData** and **RefreshTokenData**:

```
new TokenData(
            url: 'https://example-host/access-token',
            body: ['username' => 'testValue', 'password' => 'testValue'],
            dispatchEvent: false,
        );
new RefreshTokenData(
            url: 'https://example-host/refresh-token',
            body: ['refreshToken' => 'testValue'],
            dispatchEvent: false,
        );
```

API Reference
-------------

[](#api-reference)

### HttpClientInterface

[](#httpclientinterface)

```
    /**
     * Base configuration for PendingRequest
     * When PendingRequest instance isn't received, new one is created
     *
     * @param array               $headers
     * @param int                 $retries
     * @param int                 $retryInterval
     * @param int                 $timeout
     * @param int                 $connectTimeout
     * @param string|null         $userAgent
     * @param PendingRequest|null $pendingRequest
     * @return self
     */
    public function baseConfig(
        array               $headers = [],
        int                 $retries = 1,
        int                 $retryInterval = 1000,
        int                 $timeout = 30,
        int                 $connectTimeout = 3,
        string|null         $userAgent = null,
        PendingRequest|null $pendingRequest = null,
    ): self;

    /**
     * Send a request with given HTTP method, url, options HTTP request format
     * When PendingRequest instance isn't received, new one is created
     *
     * @param HttpMethod          $httpMethod
     * @param string              $url
     * @param HttpRequestFormat   $format
     * @param array               $options
     * @param PendingRequest|null $pendingRequest
     * @return Response|null
     */
    public function send(
        HttpMethod          $httpMethod,
        string              $url,
        HttpRequestFormat   $format,
        array               $options = [],
        PendingRequest|null $pendingRequest = null
    ): Response|null;

    /**
     * Send HEAD request
     * When PendingRequest instance isn't received, new one is created
     *
     * @param string              $url
     * @param array               $parameters
     * @param PendingRequest|null $pendingRequest
     * @return Response|null
     */
    public function head(string $url, array $parameters = [], PendingRequest|null $pendingRequest = null): Response|null;

    /**
     * Send GET request
     * When PendingRequest instance isn't received, new one is created
     *
     * @param string              $url
     * @param array               $parameters
     * @param PendingRequest|null $pendingRequest
     * @return Response|null
     */
    public function get(string $url, array $parameters = [], PendingRequest|null $pendingRequest = null): Response|null;

    /**
     * Send POST request
     * When PendingRequest instance isn't received, new one is created
     *
     * @param string              $url
     * @param array               $body
     * @param PendingRequest|null $pendingRequest
     * @return Response|null
     */
    public function post(string $url, array $body = [], PendingRequest|null $pendingRequest = null): Response|null;

    /**
     * Send PUT request
     * When PendingRequest instance isn't received, new one is created
     *
     * @param string              $url
     * @param array               $body
     * @param PendingRequest|null $pendingRequest
     * @return Response|null
     */
    public function put(string $url, array $body = [], PendingRequest|null $pendingRequest = null): Response|null;

    /**
     * Send PATCH request
     * When PendingRequest instance isn't received, new one is created
     *
     * @param string              $url
     * @param array               $body
     * @param PendingRequest|null $pendingRequest
     * @return Response|null
     */
    public function patch(string $url, array $body = [], PendingRequest|null $pendingRequest = null): Response|null;

    /**
     * Send DELETE request
     * When PendingRequest instance isn't received, new one is created
     *
     * @param string              $url
     * @param array               $body
     * @param PendingRequest|null $pendingRequest
     * @return Response|null
     */
    public function delete(string $url, array $body = [], PendingRequest|null $pendingRequest = null): Response|null;

    /**
     * Send a request by given HttpClient request method, url, options
     * Catches RequestException and ConnectionException
     * Logs messages
     * Fires events depending on the configurations
     * $httpMethod parameter should be provided when $apiClientRequestMethod is HttpClientRequestMethod::SEND
     * When PendingRequest instance isn't received, new one is created
     *
     * @param HttpClientRequestMethod $apiClientRequestMethod
     * @param string                 $url
     * @param array                  $options
     * @param PendingRequest|null    $pendingRequest
     * @param HttpMethod|null        $httpMethod
     * @return Response|null
     */
    public function sendRequest(
        HttpClientRequestMethod $apiClientRequestMethod,
        string                 $url,
        array                  $options = [],
        PendingRequest|null    $pendingRequest = null,
        HttpMethod|null        $httpMethod = null,
    ): Response|null;

    /**
     * Send request without error handling and event triggering
     * Throw RequestException when throw is true
     *
     * @param HttpClientRequestMethod $apiClientMethod
     * @param string                 $url
     * @param array                  $options
     * @param HttpMethod|null        $httpMethod
     * @param bool                   $throw
     * @return Response
     */
    public function request(
        HttpClientRequestMethod $apiClientMethod,
        string                 $url,
        array                  $options = [],
        HttpMethod|null        $httpMethod = null,
        bool                   $throw = false,

    ): Response;

    /**
     * Set PendingRequest when not null value is received
     *
     * @param PendingRequest|null $pendingRequest
     * @return self
     */
    public function setPendingRequest(PendingRequest|null $pendingRequest): self;

    /**
     * Get pendingRequest
     *
     * @return PendingRequest|null
     */
    public function getPendingRequest(): PendingRequest|null;

    /**
     * Determine if HttpResponseSucceeded event is fired
     *
     * @param bool $value
     * @return self
     */
    public function fireEventOnSuccess(bool $value): self;

    /**
     * Determine if HttpRequestFailed event is fired
     *
     * @param bool $value
     * @return self
     */
    public function fireEventOnRequestException(bool $value): self;

    /**
     * Determine if HttpConnectionFailed event is fired
     *
     * @param bool $value
     * @return self
     */
    public function fireEventOnConnectionException(bool $value): self;

    /**
     * Determine if RequestException occurring is logged
     *
     * @param bool $value
     * @return self
     */
    public function logOnRequestException(bool $value): self;

    /**
     * Determine if ConnectionException occurring is logged
     *
     * @param bool $value
     * @return self
     */
    public function logOnConnectionException(bool $value): self;
```

### Enums

[](#enums)

```
enum HttpMethod: string
{
    case HEAD = 'HEAD';
    case GET = 'GET';
    case POST = 'POST';
    case PUT = 'PUT';
    case PATCH = 'PATCH';
    case DELETE = 'DELETE';
    case CONNECT = 'CONNECT';
    case OPTIONS = 'OPTIONS';
    case TRACE = 'TRACE';
}
```

```
enum HttpRequestFormat: string
{
    case QUERY = 'query';
    case BODY = 'body';
    case JSON = 'json';
    case FORM_PARAMS = 'form_params';
    case MULTIPART = 'multipart';
}
```

```
enum HttpClientRequestMethod: string
{
    case GET = 'get';
    case HEAD = 'head';
    case POST = 'post';
    case PATCH = 'patch';
    case PUT = 'put';
    case DELETE = 'delete';
    case SEND = 'send';
}
```

### TokenFromConfigFactoryInterface

[](#tokenfromconfigfactoryinterface)

```
    /**
     * Instantiate TokenInterface
     * When receives $token it is set in TokenInterface instance
     * $hasRefreshTokenRequest determines instantiating RefreshTokenData
     * $configKey refers to token configurations in the config file
     *
     * @param bool        $hasRefreshTokenRequest
     * @param string      $configKey
     * @param string|null $token = null
     * @return TokenInterface
     */
    public static function create(
                              bool $hasRefreshTokenRequest = true,
                              string $configKey = 'tokenConfigurationsBase',
                              #[SensitiveParameter] string|null $token = null,
    ): TokenInterface;
```

### TokenFromDataFactoryInterface

[](#tokenfromdatafactoryinterface)

```
    /**
     * Instantiate TokenInterface
     * When receives $token it is set in TokenInterface instance
     *
     * @param TokenData             $tokenData
     * @param RefreshTokenData|null $refreshTokenData = null
     * @param int                   $retries = 3
     * @param string|null           $token = null
     * @return TokenInterface
     */
    public static function create(
        #[SensitiveParameter] TokenData             $tokenData,
        #[SensitiveParameter] RefreshTokenData|null $refreshTokenData = null,
                              int                   $retries = 3,
        string|null                                  $token = null,
    ): TokenInterface;
```

### TokenInterface

[](#tokeninterface)

```
    /**
     * Get Access Token
     * When it's missing request it
     * When $refresh is true make a request to refresh the token
     *
     * @param bool $refresh = false
     * @return string
     */
    public function get(bool $refresh = false): string;
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Stoyan Todorov](https://github.com/StoyanTodorov)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance31

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~6 days

Total

2

Last Release

727d ago

Major Versions

1.0.0 → 2.0.02024-05-15

### Community

Maintainers

![](https://www.gravatar.com/avatar/66155a62cc2992d856c3346a3b36ff35230f06c4464c1212e821f6654b6ef357?d=identicon)[Stoyan\_Todorov](/maintainers/Stoyan_Todorov)

---

Tags

laravellaravel-api-clientstoyantodorov

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/stoyantodorov-laravel-api-client/health.svg)

```
[![Health](https://phpackages.com/badges/stoyantodorov-laravel-api-client/health.svg)](https://phpackages.com/packages/stoyantodorov-laravel-api-client)
```

###  Alternatives

[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.0k7.8M57](/packages/dedoc-scramble)[scalar/laravel

Render your OpenAPI-based API reference

6183.9k2](/packages/scalar-laravel)[ryangjchandler/bearer

Minimalistic token-based authentication for Laravel API endpoints.

8129.8k](/packages/ryangjchandler-bearer)[combindma/laravel-facebook-pixel

Meta pixel integration for Laravel

4956.9k](/packages/combindma-laravel-facebook-pixel)[stechstudio/laravel-hubspot

A Laravel SDK for the HubSpot CRM Api

2971.0k](/packages/stechstudio-laravel-hubspot)[njoguamos/laravel-plausible

A laravel package for interacting with plausible analytics api.

208.8k](/packages/njoguamos-laravel-plausible)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)