Strict. Secure. Fast.

Waffle is a next-generation PHP framework for building secure, high-performance APIs and microservices. It is built on a Zero Trust architecture and enforces Strict Typing and Immutability by design.

Unlike traditional frameworks, Waffle refuses "magic." We prioritize explicit dependency injection, rigorous interface contracts, and the bleeding-edge features of PHP 8.5+ (Property Hooks, Asymmetric Visibility, Readonly Classes).

Everything you need to build, secure, and deploy Waffle applications.

1. 🛡️ Security First: Security is the foundation, not an addon. Fail-closed ABAC (a controller action with no #[Voter] is denied unless explicitly marked #[PublicAccess]), fail-closed universal authentication (JWT, OAuth2/OIDC, WebAuthn passkeys, HMAC assertions, API keys, Basic), a stateless HMAC CSRF layer bound to the authenticated identity, rate limiting at the edge (a token bucket per subject or client IP, shared in Redis), internal SSRF protection (DNS-pinned, private-CIDR-blocked outbound calls), timing-safe secret comparison, trusted-host enforcement, baseline secure headers, native YAML parsing, and strict input validation — Waffle assumes the environment is hostile.

2. ⚡ Built for the Resident Worker: Designed to run on FrankenPHP (Caddy) in Worker Mode. The kernel boots once and stays resident, memory stays bounded, and outbound calls go through a non-blocking client with mandatory timeouts, bounded retries and a circuit breaker. Performance figures are published with their method and environment, and re-measured on the current runtime before they are quoted again.

3. 🧘 No Magic: No facades. No global state. No implicit logic. Waffle code is predictable, testable, and statically analyzable.

4. 🧹 Zero-Debt: Every component passes vendor/bin/mago fmt, lint, analyze, guard, and composer tests with 0 errors, 0 warnings, plus the worker-safety audit (wfl igor, 0 KO). No baseline files exist anywhere in the tree.

5. 🐘 PHP 8.5 Strict: Property Hooks for DTO validation, Asymmetric Visibility (public private(set)) on framework state, typed constants for ecosystem-wide identifiers, final readonly value objects, #[\Override] on every interface implementation.

The waffle-commons organization is a modular monorepo of 25 fiercely independent framework components. Every component depends only on waffle-commons/contracts (plus waffle-commons/utils, the shared foundation — which itself requires only contracts) and its declared PSR dependencies — mago guard enforces this perimeter on every build.

The umbrella ships a Docker-native host helper, wfl, so contributors never run PHP on the host:

Run wfl help for the full command list.

Current Phase: 🟦 Beta 7 (Production surface — background jobs, OpenAPI, DTO serialization, a kernel testing bridge, rate limiting, outbound resilience, Kubernetes operability)

Beta 7 closes the gap between a fast framework and a production API ecosystem: four new components (queue, openapi, serializer, testing), a token-bucket rate limiter shared in Redis, outbound timeouts, retries and a circuit breaker, /healthz and /readyz probes with per-check timeouts, a graceful drain (in the acceptance run, a rolling restart of two replicas under k6 at 100 requests per second lost none of 7 501 requests — a correctness check, not a capacity figure), and reversible migrations. Every roadmap item was accepted on evidence: tests, command output and archived runs. It builds on Beta 6, which stabilized and audited the ecosystem: 17/17 security findings fixed natively with zero suppressions, a complete Diátaxis documentation overhaul, the EcoShield Gateway POC, and the first K6 benchmark harness — hardened in Beta 7 so that a run never overwrites a series and memory is reported as a slope with its 95 % bound.

• ✅ Alpha 4: Pipeline & Hardening — native YAML config, PSR-15 pipeline, RFC 7807 error-handler.

• ✅ Alpha 5: Observability & Integration — PSR-3 log, PSR-14 event-dispatcher, attribute-based security.

• ✅ Alpha 6: Contracts freeze; DTO-validation groundwork.

• ✅ Beta 0: "Zero-Debt" — Mago Purge Protocol complete, new cache + console components.

• ✅ Beta 1: "EcoShield" — worker-native security hardening, new PSR-18 http-client, fail-closed ABAC, stateless CSRF, secure headers.

• ✅ Beta 2: HTTP correctness wave (405 / OPTIONS / HEAD / Allow) + developer experience + cognitive tooling.

• ✅ Beta 3: Data & Persistence (data, RFC-022) + Universal Auth Bridge (auth, RFC-021) + wfl igor worker-safety tooling.

• ✅ Beta 4: Security & stability hardening (SSRF, identity-bound CSRF, timing-safe comparisons) + DX tooling + the monorepo Academy.

• ✅ Beta 5: Enterprise Runtime — AOT container/router compiler, DB connection pooling, Fiber async finish-request deferral, contract-first telemetry & telemetry-otel bridge, WebAuthn/passkeys.

• ✅ Beta 6: Stabilization, Audit & Performance — multi-engine security audit remediation (17/17 fixed natively), Diátaxis docs overhaul, EcoShield Gateway POC, K6 benchmark harness.

• 🟦 Beta 7 (current, November 2026): Production surface — queue, openapi, serializer, testing, rate limiting and outbound resilience (NET), Kubernetes operability (OPS).

• 🎯 v1.0.0: Production Ready (Gold — late January 2027), via Beta 8 (API freeze & consolidation, December 2026) and 1.0.0-RC1 (December 2026), certified by a soak of at least four weeks on the EcoShield Gateway.

We maintain a zero-tolerance policy for code quality. Before contributing, please ensure your environment meets the following:

• PHP: 8.5+ (strictly enforced; Property Hooks, Asymmetric Visibility, typed constants).

• Toolchain: Mago (formatter, linter, analyzer, guard) + the wfl igor worker-safety audit (igor-php 0.9.7, pinned, 0 KO) — every check must pass with zero baselines.

• Testing: PHPUnit 12.5+ (≥ 95 % coverage required for all components, and a clean OK verdict — no skipped, incomplete or risky tests).

• Architectural perimeter: Your changes must respect the [guard.perimeter.rules] declared in the component's mago.toml. Cross-component coupling outside that perimeter is a build break.

Every framework component ships a Keep-a-Changelog CHANGELOG.md and a PR template listing the exact gates a contribution must clear. Every component runs the same CI workflow — Mago, PHPUnit against a Redis service, the igor audit, secret scanning and a CycloneDX SBOM — and the umbrella collapses them behind a single required umbrella-ci gate. Please read our Contribution Guidelines in the waffle repository.

Join the core team and contributors on Discord to shape the future of cloud-native PHP.

Maintained by the Waffle Framework Core Team. © 2026.