maslosoft / api-facades
OpenAPI chainable facades generator
Requires
- php: >=8.5
- ext-json: *
- guzzlehttp/guzzle: ^8
- guzzlehttp/psr7: ^3
- maslosoft/embedi: ^2 | ^3
- monolog/monolog: ^3
- psr/http-message: ^2
- symfony/console: ^8 | ^9
- symfony/yaml: ^8 | ^9
Requires (Dev)
- codeception/codeception: ^5.3.7
- codeception/module-asserts: ^3.3
- maslosoft/codeception-reflection-asserts: ^1.0
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^13.4
Suggests
- jane-php/open-api-3: Generate OpenAPI client from OpenAPI spec
Provides
None
Conflicts
None
Replaces
None
- dev-master
- 2.0.0
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- dev-proper-generator
- dev-codex/implement-maslosoft-apifacades-builder
- dev-codex/fix-openapireader-to-extract-tags
- dev-codex/implement-openapireader-with-php-8.3
- dev-codex/implement-pathresolver-and-composerdiscover-classes
- dev-codex/refactor-api-facades-for-clear-syntax
This package is auto-updated.
Last update: 2026-11-18 12:10:32 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.