Download the PHP package scafera/integration without Composer

scafera/integration

External system communication for the Scafera framework. Provides an enforceable gateway pattern for calling third-party APIs — all behind Scafera-owned types.

Internally adopts symfony/http-client. Userland code never imports Symfony HttpClient types — boundary enforcement blocks it at build time. All alternative HTTP mechanisms (cURL, file_get_contents with HTTP URLs) are also blocked.

Provides: External system communication for Scafera — a gateway pattern where each class wraps one third-party system with business-level methods. HttpClient (5 methods: get/post/put/patch/delete) and Response (statusCode/json/body/headers/header) are Scafera-owned types; gateways wire up via #[Integration]. All HTTP escape hatches (Symfony HttpClient, cURL, file_get_contents/fopen with HTTP URLs) are blocked outside Integration/.

Depends on: A Scafera host project with an Integration/ layer (e.g. src/Integration/ under App\Integration). Per-integration config under integration: in config/config.yaml; secrets belong in config.local.yaml (git-ignored).

Extension points:

• Attribute — #[Integration('name')] resolves to the configured HttpClient; #[Integration('name', 'key')] resolves to a per-integration config value (ADR-065)
• User gateways — one class per external system in Integration/..., class name must end with Gateway (enforced by GatewayNamingValidator), business-level methods only
• Config — integration: section in config/config.yaml declares each integration's base_url, auth, and any custom keys (injectable via the two-arg attribute)
• Testing — HttpClient constructor accepts an optional HttpClientInterface (e.g. MockHttpClient) for test doubles; the bundle never passes it in production

Not responsible for: Raw HTTP outside Integration/ (Symfony HttpClient, cURL, file_get_contents/fopen with HTTP URLs — blocked by HttpClientLeakageValidator, HttpClientBoundaryValidator) · auto-throwing on HTTP errors (Response never throws; the gateway decides) · full URLs in gateway methods (relative paths only; base URL from config) · secret storage (belongs in config.local.yaml, not config.yaml) · unused integration: config keys (flagged by UnusedIntegrationConfigValidator).

This is a capability package. It adds optional external system integration to a Scafera project. It does not define folder structure or architectural rules — those belong to architecture packages.

What it provides

• HttpClient — wraps Symfony HttpClient with 5 methods (get, post, put, patch, delete)
• Response — wraps Symfony response with 5 methods (statusCode, json, body, headers, header)
• #[Integration('name')] — attribute for wiring gateways to configured HttpClient instances
• #[Integration('name', 'key')] — attribute for injecting integration-specific config values into gateways (ADR-065)
• HttpClientLeakageValidator — blocks all HTTP escape hatches in src/
• GatewayNamingValidator — enforces *Gateway naming in Integration/
• HttpClientBoundaryValidator — ensures HttpClient is only used in Integration/ layer
• IntegrationConfigBoundaryValidator — ensures #[Integration('name', 'key')] config values are only used in Integration/ layer
• UnusedIntegrationConfigValidator — flags config values defined in integration: but not referenced in any gateway

Design decisions

• Gateway, not HTTP client wrapper — a wrapped HTTP client would scatter $http->post() calls across the codebase. Gateways enforce one class per external system with business-level methods (ADR-064).
• #[Integration] attribute for wiring — extends Symfony's #[Autowire], same pattern as #[Config] in the kernel. Explicit at the injection site, greppable, validatable, refactor-safe (ADR-064). With a second argument, resolves integration-specific config values (ADR-065).
• Relative paths only — gateways use endpoint paths ('/charges'), not full URLs. Base URL is configured once in config.yaml.
• All HTTP escape hatches blocked — Symfony HttpClient, cURL, file_get_contents with HTTP URLs, fopen with HTTP URLs. If you need HTTP, you go through a gateway.

Installation

The bundle is auto-discovered via Scafera's symfony-bundle type detection. No manual registration needed.

Requirements

• PHP >= 8.4
• scafera/kernel

Configuration

If an integration has different base URLs per environment (e.g., sandbox vs production), override base_url in config.local.yaml as well.

Gateway

A gateway is one class per external system with business-level methods:

Gateway rules

• Class name must end with Gateway — enforced by validator
• One class per external system
• Business-level methods only — createPayment(), not post()
• No HTTP types in public method signatures — return arrays or domain objects
• No full URLs — endpoint paths only, base URL from config

Using a gateway in a service

Services inject gateways via constructor — same as any Scafera dependency:

Integration-specific configuration

Integrations can carry arbitrary config values beyond base_url and auth. These are registered as container parameters and injected via the same #[Integration] attribute with a second argument:

The gateway receives config values alongside the HttpClient:

#[Integration('name')] without a second argument resolves to the HttpClient service. #[Integration('name', 'key')] resolves to the config value. The HttpClient itself has no awareness of these values — they are resolved by the container before the gateway is constructed.

HttpClient API

The $data array is sent as JSON body. For other content types (form-encoded, multipart), use the $options array directly (e.g., $this->http->post('/upload', [], ['body' => $formData])).

Response API

HTTP errors do not throw automatically — error handling is the gateway's responsibility.

Testing

Testing services that use gateways

Mock the gateway, not the HTTP client:

Testing gateways themselves

The HttpClient constructor accepts an optional HttpClientInterface for testing — the bundle never passes it (engine stays hidden in production):

Boundary enforcement

Enforced via validators (scafera validate). The HttpClient and integration config values are only allowed inside the Integration/ layer — services and controllers inject gateways, not HTTP clients or integration config.

License

MIT