Search by

maslosoft / api-facades

pmaselkowski

OpenAPI chainable facades generator

Package info

github.com/Maslosoft/api-facades

pkg:composer/maslosoft/api-facades

Statistics

Installs: 23

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

2.0.0 2026-11-18 11:52 UTC

README

API Facades generator, allowing to call OpenAPI compatible API's with fluid interfaces.

🤖✨👱🏻 Made by human an Ai

Project developed with help of an Ai. This project is still in development, and only features currently required are being implemented and tested.

Description

The idea is to use natural path-like syntax, instead of method names clumps. The API call is basically last method which is the verb of request.

For example, POST to user account module API:

$api->ua->user->login->post($request);

Which sends post to: htttps://example.com/api/v1/ua/user/login

Example with GET:

$api->settlements->balance->show->get($request);

Or even shorter syntax:

$api->settlements->balance->show($request);

Which gets response from: htttps://example.com/api/v1/settlements/balance/show

Install

PHP 8.5 or newer is required for both the generator and generated clients.

composer require maslosoft/api-facades --dev

The runtime dependencies use Guzzle 8, Symfony 8, and Monolog 3. If generated clients run in production, install this package without --dev so their runtime classes remain available after composer install --no-dev.

When upgrading an existing installation, update dependencies with composer update --with-all-dependencies under PHP 8.5 or newer. Applications using a custom Guzzle client should review the Guzzle 8 migration guide.

Custom module or operation namers that accept configured processors must also implement Maslosoft\ApiFacades\Interfaces\ProcessorAware and expose public array $processors = [];. The built-in namers already implement this contract. Custom namers without processors can keep their existing interfaces.

Hydration

The ObjectProperties hydrator populates public properties using reflection. It supports #[Cast], #[CastArray], #[Scalar], and #[ScalarArray] attributes.

Computed get-only properties and properties with restricted setters are skipped. Readonly properties are initialized once and existing values are preserved. Writable property hooks are invoked when assigning hydrated values.

Input field mapping and camelization

Use #[InputField('field_name')] to map an input field to a property. When an input field is explicitly defined, camelization is ignored for that property.

Camelizing input keys (for example, user_name -> userName) can be configured through HydrationConfig:

  • HydrationConfig::CamelizeAuto (default) - camelize when snake_case keys are present.
  • HydrationConfig::CamelizeEnabled - always allow snake_case mapping.
  • HydrationConfig::CamelizeDisabled - disable snake_case mapping.
use Maslosoft\ApiFacades\Hydrators\Attributes\InputField;
use Maslosoft\ApiFacades\Hydrators\HydrationConfig;
use Maslosoft\ApiFacades\Hydrators\ObjectProperties;

class User
{
	#[InputField('user_name')]
	public string $userName = '';

	public string $emailAddress = '';
}

$hydrator = new ObjectProperties(new HydrationConfig(HydrationConfig::CamelizeAuto));
$user = $hydrator->hydrate(new User(), [
	'user_name' => 'Jane',
	'email_address' => 'jane@example.com',
]);

Unit tests

Install dependencies and run the checks with PHP 8.5 or newer:

composer install
composer check

composer check validates Composer metadata and platform requirements, runs PHPStan at level 5, and runs the Codeception suite with deprecations treated as errors. composer analyse and composer test run those checks separately.

The Makefile defaults to php8.5, so make check also works when the system's php command points to an older version. Override it with make PHP=php check if your default PHP is already 8.5 or newer.

To create unit test, make may be used with self-explanatory command, for example:

make unit Generate/Trim

Will generate new unit test class in:

tests/Unit/GenerateTrimTest.php

Keep in mind to use forward slash for namespace of tests, as \ may be interpreted as escape character and generated class namespece will be wrong.

Templates

Templates are stored as md files. This allows syntax highlighting while not showing errors when using placeholders.