IntegrationEngine — a Symfony bundle that centralises your external API integrations

#symfony #php #opensource #architecture

I built a Symfony bundle this week that centralises external API integrations under a hexagonal architecture: IntegrationEngine.

The problem it solves: every integration ends up as an isolated case. Different auth mechanisms, inconsistent structures, duplicated cache logic. Code fragments and every new API means starting from scratch.

How it works

One entry point for all your integrations:

$registry->get('stripe')->send(
    actionName: 'CreateCharge',
    context: DefaultActionContext::create(['id' => 42]),
    body: $body,
);

The call site is always the same — regardless of whether the integration uses static auth, dynamic OAuth with token caching, path parameters, or custom headers.

What the bundle handles for you

Dynamic auth with transparent caching — declare which action fetches the token and which field contains it. The engine resolves, caches and substitutes it before the actual request. No caching logic in your code.
Path context — /orders/{id} resolved at call time. Explicit exception if a parameter is missing.
Three-layer headers — YAML defaults → auth headers → caller headers. Each layer overrides the previous.
Typed responses — each action defines its own Response DTO.
Scaffolding — make:integration generates Action, Mapper, Response and YAML in one step, including the bundle config on first run.

The bundle proposes, it does not impose

The most interesting pattern it enables: integration base classes.

abstract class StripeAction extends AbstractAction
{
    public static function create(string $method, string $path, ?ActionBodyInterface $body = null): static
    {
        return parent::create(
            method: $method,
            path: '/v1'.$path,
            body: $body,
            authorization: new StaticAuthorizationConfig(
                type: 'bearer',
                params: ['token' => '%env(STRIPE_SECRET_KEY)%'],
            ),
        );
    }
}

final class CreateChargeAction extends StripeAction
{
    public static function getName(): string { return 'CreateCharge'; }
    public static function hasResponse(): bool { return true; }
    public static function mapper(): string { return CreateChargeMapper::class; }
}