No-Framework PHP Knowledge Base

Quick reference for building framework-free PHP applications using PSR standards, standalone Composer packages, and Clean Architecture. Covers everything needed to run a production-grade project without Symfony, Laravel, or any full-stack framework.

Core Principles

PSR Compliance

PSR	Purpose	Recommended Package
PSR-4	Autoloading	Composer autoloader
PSR-7	HTTP Messages	nyholm/psr7 or guzzlehttp/psr7
PSR-11	Container Interface	php-di/php-di or league/container
PSR-15	HTTP Handlers & Middleware	relay/relay or custom pipeline
PSR-17	HTTP Factories	nyholm/psr7 (includes factories)
PSR-3	Logging	monolog/monolog
PSR-6/PSR-16	Caching	symfony/cache (standalone)

Key Advantages

• Maximum domain freedom — Domain layer is pure PHP by default
• Composable packages — pick exactly the libraries you need
• Full control — bootstrap, middleware, error handling are explicit
• Lightweight — no hidden magic, no auto-wiring unless configured

Architecture Stack

public/index.php (Front Controller) → Middleware Pipeline (PSR-15)
  → Presentation (Actions) → Application (Use Cases) → Domain (Entities/VOs)
  → Infrastructure (Repos/Adapters) ← Composer + PSR-4 Autoloading

Quick Checklists

DDD-Compatible Pure PHP Project

• declare(strict_types=1) in every file
• PSR-4 autoloading via Composer
• Domain layer has zero external use statements (no Doctrine, no framework)
• Repository interfaces in Domain, implementations in Infrastructure
• DI container configured explicitly (PHP-DI or League)
• PSR-7 request/response, PSR-15 middleware pipeline
• Front controller in public/index.php
• Environment config via .env + vlucas/phpdotenv
• Error handling middleware with custom exception hierarchy
• Security via JWT middleware (lcobucci/jwt) + RBAC; Domain uses Specifications for authorization
• Queue job handlers delegate to Application UseCases; Domain dispatches events, not jobs
• Infrastructure components (Cache, HTTP Client, Mailer) accessed via domain port interfaces
• Domain EventDispatcherInterface port; Infrastructure provides PSR-14 or InMemory adapter

Clean Architecture Checks

• No use Illuminate\\ or use Symfony\\ in Domain or Application layers
• No HTTP concepts in Application layer
• All external services accessed through port interfaces
• Compiled DI container in production
• Database migrations managed by standalone tool

Common Violations Quick Reference

Violation	Where to Look	Severity
Missing declare(strict_types=1)	Any PHP file	Critical
require / include instead of autoloading	Entry points, legacy files	Critical
Global state ($_GET, $_POST, $_SESSION)	Presentation layer	Critical
Framework dependency in Domain	src/Domain/**/*.php	Critical
Custom ORM instead of using Doctrine/Cycle	src/Infrastructure/**/*.php	Warning
No PSR-7 — raw echo / header() calls	public/index.php, controllers	Warning
Service Locator in Application layer	src/Application/**/*.php	Warning
Missing DI container — manual new chains	Bootstrap files	Warning
No middleware pipeline — logic in index.php	public/index.php	Info
JWT/session logic in Domain	src/Domain/**/*.php	Critical
Queue library in Domain	use Enqueue\\ or use PhpAmqpLib\\ in Domain	Critical
Cache/HTTP Client in Domain	CacheInterface or HttpClientInterface in Domain	Critical
Missing queue resilience	Workers without retry/error handling	Warning

PHP 8.4 No-Framework Patterns

PSR-15 Middleware

declare(strict_types=1);

namespace Infrastructure\Http\Middleware;

use Psr\Http\Message\{ResponseInterface, ServerRequestInterface};
use Psr\Http\Server\{MiddlewareInterface, RequestHandlerInterface};

final readonly class CorsMiddleware implements MiddlewareInterface
{
    public function __construct(private string $allowedOrigin = '*') {}

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        return $handler->handle($request)
            ->withHeader('Access-Control-Allow-Origin', $this->allowedOrigin)
            ->withHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
    }
}

Application Service (Use Case)

declare(strict_types=1);

namespace Application\Order\UseCase;

final readonly class PlaceOrderUseCase
{
    public function __construct(
        private OrderRepositoryInterface $orders,
        private EventDispatcherInterface $events,
    ) {}

    public function execute(PlaceOrderCommand $command): OrderId
    {
        $order = Order::create($command->customerId, $command->lines);
        $this->orders->save($order);

        foreach ($order->releaseEvents() as $event) {
            $this->events->dispatch($event);
        }

        return $order->id();
    }
}

Front Controller

declare(strict_types=1);

require dirname(__DIR__) . '/vendor/autoload.php';
Dotenv\Dotenv::createImmutable(dirname(__DIR__))->load();
$container = require dirname(__DIR__) . '/config/container.php';
$container->get(App::class)->run();

References

For detailed information, load these reference files:

• references/architecture.md — Project structure, PSR-4 autoloading, bootstrap patterns
• references/ddd-integration.md — Pure Domain layer, Value Objects, Entities, Domain Events
• references/routing-http.md — PSR-7/PSR-15 HTTP, routing, middleware pipeline
• references/persistence.md — Doctrine/Cycle standalone, PDO repositories, migrations
• references/dependency-injection.md — PHP-DI, League Container, PSR-11, compiled containers
• references/testing.md — PHPUnit standalone, mocking, HTTP testing, database testing
• references/antipatterns.md — Common no-framework mistakes with detection patterns
• references/security.md — JWT authentication (lcobucci/jwt), RBAC middleware, password hashing, CSRF, security headers
• references/event-system.md — PSR-14, league/event, custom dispatcher, domain events, async event processing
• references/queue.md — enqueue/enqueue, php-amqplib, workers, job dispatcher, supervisor
• references/infrastructure-components.md — Cache PSR-6/16, HTTP Client PSR-18, Mailer, Rate Limiting