E
Eootle Insights
Login Sign Up
How to Build a Custom PHP Web Framework in 2026: A Step-by-Step Guide for Beginners

Category: Tutorials & Guides || Posted Aug 12, 2026

How to Build a Custom PHP Web Framework in 2026: A Step-by-Step Guide for Beginners

Writing raw PHP for production applications in 2026 is generally considered a bad practice. Modern frameworks like Laravel and Symfony provide routing, Object-Relational Mapping (ORM), authentication, and security out of the box, adhering to modern PHP best practices by default. So, why should you build your own?

The greatest advantage of crafting your own framework is the absolute flexibility it provides. You choose exactly what you need and decide how to make everything work together. More importantly, building a framework from scratch is the ultimate way to demystify the "magic" behind modern PHP architecture.

In this guide, we will build a lightweight, modern PHP 8.4+ framework utilizing standard PHP-FIG (Framework Interop Group) recommendations.

Step 1: Project Setup & PSR-4 Autoloading

In the early days of PHP, developers wrote their own manual require statements. Today, real PHP projects use Composer to handle autoloading automatically. To maintain a clean and standard structure, the PHP-FIG introduced PSR-4, a standard that defines how classes and namespaces map to file paths.

Create a new directory for your project and initialize Composer via your terminal:

Bash


mkdir my-custom-framework && cd my-custom-framework
composer init

Next, open your composer.json file and configure PSR-4 autoloading so that Composer knows any class starting with the App\ namespace should be loaded from the src/ directory:

JSON


{
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}

Run composer dump-autoload to generate the autoloader based on these rules. Create a public folder for your web root and a src folder for your application code.

Step 2: The HTTP Foundation (PSR-7)

Modern PHP applications no longer rely directly on global variables like $_GET or $_POST. Instead, they use PSR-7 (HTTP Message Interface), which standardizes how request and response objects work across frameworks. This makes your code framework-agnostic.

To implement PSR-7, we can use a package like Diactoros, which comes with a factory to create requests from globals and provides implementations for different types of responses. We also need an "emitter" to output the response directly to the browser.

Install the modern Laminas Diactoros packages:

Bash


composer require laminas/laminas-diactoros laminas/laminas-httphandlerrunner

Create public/index.php (this acts as your application's front controller):

PHP


<?php
declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use Laminas\Diactoros\ServerRequestFactory;
use Laminas\HttpHandlerRunner\Emitter\SapiEmitter;

// Capture the incoming HTTP request from the server environment
$request = ServerRequestFactory::fromGlobals();

// We will generate a response in the next steps...

Step 3: Routing

Now, we want to run our code depending on a requested URL. To accomplish this, we need a router. FastRoute is an excellent, extremely fast routing solution widely adopted in the PHP community.

Install it via Composer:

Bash


composer require nikic/fast-route

Let's define a route that maps a URL to a controller class. Inside public/index.php, add the FastRoute dispatcher:

PHP


use FastRoute\RouteCollector;
use function FastRoute\simpleDispatcher;

// Define your routes
$dispatcher = simpleDispatcher(function(RouteCollector $r) {
$r->addRoute('GET', '/hello/{name}', 'App\Controllers\HelloController');
});

// Match the current request against the defined routes
$routeInfo = $dispatcher->dispatch($request->getMethod(), $request->getUri()->getPath());

switch ($routeInfo[0]) {
case FastRoute\Dispatcher::NOT_FOUND:
echo "404 Not Found";
break;
case FastRoute\Dispatcher::METHOD_NOT_ALLOWED:
echo "405 Method Not Allowed";
break;
case FastRoute\Dispatcher::FOUND:
$handler = $routeInfo[1]; // The controller class name
$vars = $routeInfo[2]; // The route variables (e.g., {name})
// We will call the controller here next!
break;
}

Step 4: Inversion of Control & Dependency Injection (PSR-11)

To keep your code modular, scalable, and testable, it is best practice to utilize Inversion of Control. A Dependency Injection Container (DIC) will automatically resolve and instantiate your controllers and any dependencies they might require (like database connections or mailers).

We will use PHP-DI, a powerful and user-friendly PSR-11 compliant container:

Bash


composer require php-di/php-di

Initialize the container in public/index.php and update the router's FOUND case to use it:

PHP


use DI\ContainerBuilder;

// Initialize the DI Container
$containerBuilder = new ContainerBuilder();
$container = $containerBuilder->build();

// ... (Router dispatcher code goes here)

case FastRoute\Dispatcher::FOUND:
$handler = $routeInfo[1];
$vars = $routeInfo[2];
// Let the container instantiate the controller automatically
$controller = $container->get($handler);
// Execute the controller and get a PSR-7 Response back
$response = $controller($request, $vars);
// Output the response to the browser using the emitter
$emitter = new SapiEmitter();
$emitter->emit($response);
break;

Step 5: Creating the Controller

Finally, let's create the HelloController to see our customized framework in action. Because we configured PSR-4 autoloading for the App\ namespace to look in the src/ directory, Composer knows exactly where to find this file.

Create the file at src/Controllers/HelloController.php:

PHP


<?php
declare(strict_types=1);

namespace App\Controllers;

use Laminas\Diactoros\Response\HtmlResponse;
use Psr\Http\Message\ServerRequestInterface;

class HelloController
{
/**
* Using the __invoke magic method makes the class instance callable as a function.
*/
public function __invoke(ServerRequestInterface $request, array $vars): HtmlResponse
{
// Sanitize the input to prioritize security
$name = htmlspecialchars($vars['name'], ENT_QUOTES, 'UTF-8');
// Return a PSR-7 compliant HTML response
return new HtmlResponse("<h1>Hello, {$name}! Welcome to your custom 2026 PHP Framework.</h1>");
}
}

Summary

Congratulations! You have successfully built the foundations of a custom, highly flexible PHP framework. By bypassing "framework magic" and building from the ground up, you learned how to:

  1. Ditch manual require statements and organize your project using PSR-4 autoloading.
  2. Manage HTTP requests and responses cleanly with PSR-7 HTTP Message Interfaces.
  3. Map endpoints to specific application logic using a highly performant Router.
  4. Manage class dependencies and autowire controllers using a PSR-11 Container.

While enterprise applications should generally lean on established tools like Laravel or Symfony, understanding how these core PSR standards stitch together elevates you from a developer who just uses a framework, to an engineer who truly understands how one operates.