README

This refactor delivers a brand-new, SOLID-oriented Engeni API client that mirrors Laravel Eloquent's read/query and write behavior while remaining purely HTTP-driven. The legacy implementation now lives under old/, letting the package evolve without backward-compatibility constraints.

Highlights

Complete CRUD support: Fluent, Eloquent-style operations for reading (first, firstOrFail, find, findOrFail, get, paginate, simplePaginate, pluck, value, count, exists, doesntExist, cursor, chunk) and writing (create, save, update, delete, destroy, upsert).
Mass assignment protection: Laravel-style $fillable and $guarded properties for secure attribute handling.
Change tracking: Full support for isDirty(), wasChanged(), getChanges(), getOriginal(), and getPrevious() methods.
Dependency inversion throughout: a swappable HttpClientInterface keeps the runtime and tests fully mockable.
Lightweight resource models that hydrate from Engeni's REST responses while offering familiar Eloquent ergonomics.
Laravel-first integration with automatic service-provider discovery; once installed, the client is resolved from the container without manual wiring.
Requires PHP 8.3+, letting us lean on modern language features such as typed class constants for safer configuration.
Comprehensive PHPUnit + Orchestra Testbench suite, plus Bitbucket Pipelines that run pint --test and phpunit on pull requests and master merges.
Observability helpers such as Engeni\ApiClient2\Http\TracingHttpClient let you capture the exact URL, method, and query parameters generated by the client without enabling verbose debug output.

Requirements

PHP 8.3 or newer
Guzzle 7+
Laravel support components (pulled in automatically)

Installation

composer require engeni/api-client

Quick Start

use Engeni\ApiClient2\Resources\LaGuiaOnline\Business;

// Configure credentials via .env (see config/engeni.php).

// Reading data
$popularBusinesses = Business::query()
    ->where('country_id', 54)
    ->orderBy('name')
    ->paginate(25);

// Creating records
$business = Business::create([
    'name' => 'Acme Corp',
    'country_id' => 54,
    'category_id' => 123,
]);

// Updating records
$business->name = 'Updated Corp Name';
$business->save();

// Deleting records
$business->delete();

Configuration

The package ships with config/engeni.php (publish via php artisan vendor:publish --tag=engeni-api-client-config).
By default it reads the following environment variables (with sensible fallbacks):
- ENGENI_API_CLIENT_BASE_URI (falls back to ENGENI_SERVICE_BASE_URI)
- ENGENI_API_CLIENT_TOKEN (falls back to ENGENI_SERVICE_API_TOKEN)
- ENGENI_API_CLIENT_TIMEOUT
- ENGENI_API_CLIENT_DEBUG
- ENGENI_API_CLIENT_HTTP_DEBUG
ENGENI_SERVICE_ID (used for the default User-Agent)
The service provider binds both Client::class and HttpClientInterface::class as singletons and shares the instance with every ResourceModel, so you can call any resource class without manual bootstrapping.
Need custom transport? Bind your own implementation of Engeni\ApiClient2\Contracts\Http\HttpClientInterface or tweak the published config.

Tracing Requests

Need to inspect the exact HTTP request being dispatched without enabling verbose dumps? Wrap any existing HTTP transport in the TracingHttpClient decorator. It records every call, exposing helper methods that you can assert against in tests or print in diagnostic scripts.

use Engeni\ApiClient2\Client;
use Engeni\ApiClient2\Http\GuzzleHttpClient;
use Engeni\ApiClient2\Http\TracingHttpClient;
use Engeni\ApiClient2\Resources\LaGuiaOnline\Country;
use GuzzleHttp\Client as GuzzleClient;

$http = new TracingHttpClient(
    new GuzzleHttpClient(new GuzzleClient([
        'base_uri' => config('services.engeni.base_uri'),
        'headers' => ['Authorization' => 'Bearer '.config('services.engeni.token')],
    ]))
);

$client = new Client(
    http: $http,
    baseUri: config('services.engeni.base_uri'),
);

Country::setClient($client);
Country::query()->with('states')->limit(3)->get();

dump($http->lastRequest());
// [
//     'method'  => 'GET',
//     'uri'     => 'https://api.engeni.com/lgo/countries',
//     'options' => [
//         'query' => [
//             'embed' => 'states',
//             'limit'   => 3,
//         ],
//     ],
// ]

$http->clear(); // reset the log once you have asserted what you need

Because TracingHttpClient implements the same contract as the production transport you can drop it into integration tests, CLI tools, or debugging sessions. The examples/countries.php playground ships with the tracer enabled so you can see every generated URL after each scenario.

Architecture at a Glance

Client – Holds the base URI, default headers, and exposes newQuery() for every resource definition.
HttpClientInterface – Abstraction over the transport layer (default GuzzleHttpClient, but anything PSR-18/HTTP-capable can be wrapped).
Query\Builder – Fluent query object that translates Eloquent-style calls into Engeni-friendly query strings.
ResourceModel – Minimal model layer that hydrates responses, offers attribute access, collections, and paginator interop.
Support utilities – Helpers for pagination, response parsing, and tests (see tests/Support).

Documentation

See context/guide.md for an extensive reference covering:

Contract diagram, dependency injection guidelines, and how to provide your own HTTP transport.
Every query builder method with signatures, behaviour notes, and examples.
Pagination semantics (mapping Engeni meta/links into Laravel paginators).
Testing recipes (mocking HttpClientInterface, using Orchestra, asserting request shapes).
Pipelines, coding standards, and the roadmap for introducing write operations.

Quality Gates

composer install
composer lint                   # runs Pint in --test mode
composer test                   # runs PHPUnit + Orchestra suite
composer test:coverage          # runs tests with HTML and text coverage reports
composer test:coverage:clover   # runs tests with Clover XML coverage report

After running composer test:coverage, open coverage/html/index.html in your browser to view the detailed coverage report.

bitbucket-pipelines.yml executes the same commands on pull requests and on merges to master, ensuring styling and tests stay green before code lands.

Contributing

Keep contributions read-only until write operations are designed.
Prefer new contracts over deep inheritance; the package leans on dependency injection to ease mocking.
Update docs and tests whenever you add behaviour.

engeni / api-client-2

Maintainers

Details