LaravelPackages.net
Acme Inc.
Toggle sidebar
jeffersongoncalves/laravel-zero-api-client

Reusable base REST HTTP client for Laravel Zero CLIs: get/post/put/delete, pagination, Basic/Bearer auth and consistent API error handling.

419
1
v1.0.2
About jeffersongoncalves/laravel-zero-api-client

jeffersongoncalves/laravel-zero-api-client is a Laravel package for reusable base rest http client for laravel zero clis: get/post/put/delete, pagination, basic/bearer auth and consistent api error handling.. It currently has 1 GitHub stars and 419 downloads on Packagist (latest version v1.0.2). Install it with composer require jeffersongoncalves/laravel-zero-api-client. Discover more Laravel packages by jeffersongoncalves or browse all Laravel packages to compare alternatives.

Last updated

laravel-zero-api-client

laravel-zero-api-client

Buy Me A Coffee

A small, self-contained base for building REST API client wrappers in Laravel Zero CLI tools. It was extracted from the near-identical HTTP layers of the Bitbucket and Jira CLIs and captures the shared 85%: get/post/put/delete, pagination, Basic/Bearer authentication and consistent JSON error handling on top of Guzzle.

Why

Every API CLI ends up writing the same boilerplate: a Guzzle client, JSON decoding, a "throw a typed exception on 4xx" branch, and a pagination loop. This package owns that boilerplate so each concrete client only describes what is genuinely API-specific:

  • which exception type to throw, and
  • how to walk that API's particular pagination scheme.

It has no dependency on any credentials package - authentication is passed in through the constructor.

Installation

composer require jeffersongoncalves/laravel-zero-api-client

Requires PHP ^8.2 and guzzlehttp/guzzle ^7.10.

Usage

1. Define your exception

Extend ApiException. The base extractMessage() already understands the common error shapes (error.message, message, errorMessages); override it only when your API is different.

use JeffersonGoncalves\LaravelZero\ApiClient\ApiException;

final class GitHubApiException extends ApiException
{
    // Optional: GitHub returns { "message": "..." }, already handled by the base.
}

2. Define your client

Extend AbstractApiClient and implement newApiException() to bind error handling to your exception type.

use JeffersonGoncalves\LaravelZero\ApiClient\AbstractApiClient;
use JeffersonGoncalves\LaravelZero\ApiClient\ApiException;
use JeffersonGoncalves\LaravelZero\ApiClient\Auth;

final class GitHubClient extends AbstractApiClient
{
    public function __construct(string $token)
    {
        parent::__construct('https://api.github.com', Auth::bearer($token));
    }

    protected function newApiException(int $statusCode, array $body): ApiException
    {
        return GitHubApiException::fromResponse($statusCode, $body);
    }

    public function repo(string $owner, string $repo): array
    {
        return $this->get("repos/{$owner}/{$repo}");
    }
}

3. Authentication

Auth::basic('[email protected]', 'api-token'); // Authorization: Basic base64(user:token)
Auth::bearer('access-token');                 // Authorization: Bearer access-token

Pass null for anonymous access, or override authHeaders() for a custom scheme.

4. Pagination

Pagination differs across APIs, so paginate() takes two callables: one to extract the items from a page, one to describe the next request (or return null to stop).

Cursor pagination (Bitbucket-style next URL):

$all = $client->paginate(
    "repositories/{$workspace}/{$repo}/pullrequests",
    ['state' => 'OPEN'],
    fn (array $page) => $page['values'] ?? [],
    fn (array $page) => isset($page['next'])
        ? ['path' => $page['next'], 'query' => []]
        : null,
);

Offset pagination (Jira-style startAt/maxResults):

$all = $client->paginate(
    'search',
    ['startAt' => 0, 'maxResults' => 50],
    fn (array $page) => $page['issues'] ?? [],
    function (array $page, array $query) {
        $next = $query['startAt'] + $query['maxResults'];

        return $next >= ($page['total'] ?? 0)
            ? null
            : ['query' => ['startAt' => $next, 'maxResults' => $query['maxResults']]];
    },
);

Public API

| Class | Purpose | |-------|---------| | AbstractApiClient | Base client: get, post, put, delete, paginate. Implement newApiException(). | | ApiException | Abstract base exception with fromResponse() / extractMessage() and $statusCode / $response. | | Auth | Immutable credential: Auth::basic(), Auth::bearer(). | | AuthType | Basic / Bearer enum. |

Testing

composer test

License

MIT

Comments
Affiliate link

Get paid by clients abroad

Wise gives you local bank details in several currencies and converts at the mid-market rate. Useful when your invoices are not in your own currency.

Try Wise

Star History Chart

Get the next ones by email

New Laravel packages worth a look, once a month. No spam, one-click unsubscribe.