Architecture

How to Organize a PHP Project for Maintainability

Use a clear directory structure to separate public entry points, application code, configuration, storage, and third-party dependencies.

Separate public files from application code

A simple custom PHP application might use a structure like:

project/
├── app/
│   ├── Controllers/
│   ├── Models/
│   ├── Services/
│   └── Views/
├── config/
├── database/
├── public/
│   ├── index.php
│   └── assets/
├── storage/
│   ├── cache/
│   └── logs/
├── vendor/
├── composer.json
└── composer.lock

Only the public/ directory should be configured as the web document root where the hosting setup allows it.

Keep responsibilities clear

  • Controllers handle HTTP requests and coordinate application work.
  • Models or repositories handle data access.
  • Services contain reusable application logic.
  • Views render output.
  • Configuration provides environment-specific settings.

Avoid placing every query, validation rule, and HTML template in one large entry-point file.

Use a single bootstrap

A bootstrap file can load Composer's autoloader, configuration, error handling, and shared services. Keep initialization predictable and avoid including the same file through multiple paths.

Adapt to project size

A small site does not need dozens of layers. Start with a structure that makes responsibilities clear, then introduce additional abstractions when complexity justifies them.