Download the PHP package waffle-commons/contracts without Composer

Waffle Contracts Component

Release: 0.1.0-beta6  |  CHANGELOG.md

The Waffle Framework's central contract package. Every other waffle-commons/* component depends only on this package and on its declared PSR interfaces. No component may depend on a sibling's concrete implementation — contracts is the line that keeps the ecosystem decoupled.

This package contains interfaces, attributes, enums, exception interfaces, typed constants, and the small set of concrete routing exceptions (RouteNotFoundException, MethodNotAllowedException) shared across components. No business logic ever ships from here.

🆕 Beta-2 highlights — HTTP method correctness

• NEW — Waffle\Commons\Contracts\Routing\Exception\MethodNotAllowedException (concrete final class) and its MethodNotAllowedExceptionInterface marker. Carries the allowed-methods list so downstream renderers can emit the RFC 7231 Allow header on 405 responses.
• NEW — Waffle\Commons\Contracts\Routing\Constant: HTTP-method string constants (METHOD_GET, METHOD_POST, METHOD_PUT, METHOD_PATCH, METHOD_DELETE, METHOD_HEAD, METHOD_OPTIONS).
• CHANGED — Waffle\Commons\Contracts\Routing\Attribute\Route (relocated from waffle-commons/routing in Beta-2): gained the array $methods = ['GET'] parameter for method filtering and route overloading. Constructor argument order normalised so $path precedes $methods. Empty methods array means "any method".
• NEW — Waffle\Commons\Contracts\Exception\WaffleExceptionInterface: explicit base interface for the framework's exception hierarchy.

Beta-1 inheritance

The Beta-1 line introduced the security and HTTP-correctness foundations this package still carries:

• BREAKING (Beta-1) — CsrfTokenManagerInterface::issue(), validate(), refresh() take a $sessionId argument. The HMAC binds tokens to the per-browser WAFFLE_SID cookie issued by AnonymousSessionMiddleware.
• NEW (Beta-1) — Waffle\Commons\Contracts\Security\Attribute\PublicAccess — explicit opt-out for the fail-closed ABAC default. Without #[Voter] and without #[PublicAccess], SecureContainer::analyze() denies with HTTP 403.
• NEW (Beta-1) — Waffle\Commons\Contracts\Routing\Exception\RouteNotFoundException — concrete final class implementing RouteNotFoundExceptionInterface. Thrown by CoreRoutingMiddleware so missing routes render as 404 instead of 500.
• NEW (Beta-1) — CSRF binding constants on Waffle\Commons\Contracts\Security\Csrf\Constant: SESSION_COOKIE_NAME (WAFFLE_SID), SESSION_ID_BYTES (32), SESSION_REQUEST_ATTRIBUTE (_anon_sid), SESSION_COOKIE_MAX_AGE (2_592_000), plus MIN_SECRET_BYTES (32) and SECRET_ENV_KEY (WAFFLE_CSRF_SECRET).

📦 Installation

🧱 What's inside

🐘 PHP 8.5 surface

The contracts package is the canonical reference for the framework's PHP 8.5 contract style:

• Typed constants everywhere — public const string EVENT_NAME = '...';, public const int SECURITY_LEVEL10 = 10;.
• Marker attributes with Attribute::TARGET_* declarations (#[Dto], #[Voter], #[Rule]).
• final readonly class for value-object attributes.
• All return types and parameter types are explicit; no mixed in the public surface except where PSR-11 mandates it (ContainerInterface::get(): mixed).

📐 Sample interfaces

KernelInterface — the heart of the framework:

ConfigInterface — typed config access:

#[Dto] — marker attribute for auto-hydrated DTOs:

A DTO consumer in your controller:

🤝 Decoupling rule

Every concrete waffle-commons component must depend on waffle-commons/contracts and on nothing else from the waffle-commons/* namespace, unless explicitly declared in its own composer.json require. This rule is enforced at build time by mago guard perimeters in every component.

🧭 Architectural boundary (mago guard)

contracts is the root of the ecosystem, so its own perimeter (enforced by vendor/bin/mago guard, bundled into composer mago, zero baselines — see mago.toml [guard.perimeter]) is the strictest of all: production code under Waffle\Commons\Contracts may depend only on:

• Waffle\Commons\Contracts\** — itself
• Psr\** — PSR interfaces
• @global + Psl\** — PHP core and the PHP Standard Library

It depends on *no other `waffle-commons/package** — that is what lets every other component depend on it without creating a cycle. Test code underWaffleTests\Commons\Contractsis unrestricted (@all`).

Structural rules are guarded too: interfaces must be named *Interface, Exception\** classes must end in *Exception, and any Enum\** namespace may hold only enum declarations (see the Decoupling rule above for the ecosystem-wide counterpart).

🧪 Testing

📚 Documentation

Full guides live in the central Diátaxis documentation tree:

• Reference — waffle-commons/contracts
• Documentation home

📄 License

MIT — see LICENSE.md.