Architecture

Build a Maintainable Custom PHP Application

A practical architecture for small and medium PHP applications without requiring a full-stack framework.

Overview

A custom PHP application can remain maintainable as it grows when responsibilities are separated and conventions are consistent. A framework is optional; structure is not. The goal is to make request handling, business rules, persistence and presentation easy to locate and test.

Recommended project boundaries

Keep the public document root limited to the front controller and public assets. Store configuration, secrets, logs, uploads and generated private files outside the web root. Organize application code into focused areas such as Controllers, Services, Repositories, Views and Support. Avoid turning every small operation into a class, but do give business rules a clear home.

Request lifecycle

A typical request should pass through a predictable sequence: bootstrap configuration, create shared services, resolve the route, validate the request, invoke application logic, and render a response. A front controller keeps this lifecycle consistent:

<?php
declare(strict_types=1);

require dirname(__DIR__) . '/app/bootstrap.php';

$router = new Router();
$router->get('/', [HomeController::class, 'index']);
$router->dispatch($_SERVER['REQUEST_METHOD'], $_SERVER['REQUEST_URI']);

The example is intentionally small; adapt the Router and bootstrap to the application rather than copying an incomplete framework.

Keep responsibilities separate

Controllers should coordinate HTTP input and output, not contain every SQL query and business rule. Services implement use cases. Repositories encapsulate persistence where that abstraction is useful. Views format already-prepared data and escape output. This makes changes less likely to affect unrelated features.

Configuration and deployment

Read environment-specific values from a private configuration source. Do not commit database passwords or API keys. Use different settings for local development and production, and fail safely when required configuration is missing. Keep writable directories narrowly scoped and never make application source writable by the web process without a clear reason.

Practical checklist

  • Use declare(strict_types=1) consistently where appropriate.
  • Keep the document root separate from private application files.
  • Centralize error handling and logging.
  • Validate input at the boundary and authorize every protected action.
  • Keep SQL parameterized and output context-escaped.
  • Document setup, required PHP extensions and deployment steps.

When this approach fits

A custom architecture works well for focused websites, internal tools and content platforms whose requirements are understood. If the application develops complex domain workflows or many contributors, consider adopting stronger conventions or a framework after evaluating migration cost.

Official references

PHP Manual PHP-FIG PSR recommendations

A practical structure

A small application can start with a restrained structure and add boundaries as the domain grows:

public/
  index.php
app/
  Controllers/
  Services/
  Repositories/
  Views/
config/
storage/
  logs/
  cache/
vendor/

Keep public/ as the document root. The front controller should load the Composer autoloader, bootstrap configuration and dispatch the request. Controllers coordinate HTTP concerns; services implement use cases; repositories isolate persistence when that separation pays for itself. Do not create a class for every trivial expression. Introduce a boundary when it makes a responsibility easier to test, replace or understand.

Decide where code belongs

A useful test is to ask what would change if the database, URL, or business rule changed. SQL belongs in a persistence boundary, not scattered through templates. HTML belongs in views, not in database repositories. Authorization should be explicit at the action or service boundary rather than hidden in a navigation menu.

Keep the architecture observable

Add structured error logging, health checks for critical dependencies and a repeatable deployment checklist. Document the request lifecycle and the location of configuration. A new developer should be able to find the entry point, understand how a route is resolved and run the test suite without guessing.

Common mistakes

  • Building a large framework-like abstraction before the application has real complexity.
  • Letting controllers grow into a mixture of SQL, validation, email and HTML.
  • Putting uploads, logs or credentials under the public document root.
  • Making production-only behavior impossible to reproduce locally.

Review the structure when a feature repeatedly crosses the same boundaries. Refactor around demonstrated friction rather than theoretical purity.