Monorepo with PHP: Code Organization for Beginners

Introduction

PHP development often starts with a single index.php file, but as the project grows, the need to structure the code arises. Many developers face a dilemma: store everything in one repository (monorepo) or split it into many small repositories (multirepo). In this article, we will explore the concept of a monorepo for PHP projects, show how to organize code for beginners, and provide practical examples.

A monorepo is an approach where the code of several projects, libraries, or components is stored in a single version control system repository (Git). In the context of PHP, this means your main website, API, packages, and utilities are all in one folder. This simplifies dependency management, refactoring, and deployment.

In this article, you will learn:

• What a monorepo is and why you need it
• How to organize the folder structure for PHP
• How to configure Composer to work with a monorepo
• Examples of real-world code organization

Benefits of a Monorepo for PHP

Many beginner PHP developers think a monorepo is a "code dump." In reality, when properly organized, it is a powerful tool. Here are the main advantages:

• Ease of navigation: All project components are in one place. No need to switch between repositories.
• Single version of dependencies: You use one composer.json file to manage packages, eliminating version conflicts.
• Atomic commits: Changes to the API, frontend, and libraries can be made in a single commit, simplifying rollbacks.
• Simplified testing: Integration tests run faster since all components are available locally.
• Unified CI/CD: One build pipeline for the entire project.

However, a monorepo is not suitable for everyone. If your team is large (more than 20 people), or projects differ greatly in technology, a multirepo approach might be better. For beginners and medium-sized projects, it is an ideal choice.

Monorepo Structure: Basic Layout

Let's create a typical PHP monorepo structure. Suppose we have a web application with an API and several libraries. Here is the recommended folder hierarchy:

my-php-monorepo/├── apps/│   ├── web/               # Main website (Laravel, Symfony, or pure PHP)│   │   ├── public/│   │   ├── src/│   │   └── config/│   └── api/               # API server│       ├── public/│       ├── src/│       └── routes/├── packages/              # Internal libraries and packages│   ├── core/              # System core (base classes)│   │   ├── src/│   │   └── composer.json│   ├── database/          # Database work (migrations, models)│   │   ├── src/│   │   └── composer.json│   └── utils/             # Utilities (validation, logging)│       ├── src/│       └── composer.json├── tests/                 # Global tests├── docker/                # Docker configs├── composer.json          # Root Composer├── composer.lock├── .gitignore└── README.md

Explanation:

• apps/ — contains executable applications (websites, APIs, console scripts). Each application has its own entry point (public/index.php).
• packages/ — internal packages you develop. They are included via composer.json using path repositories.
• tests/ — root-level tests (e.g., integration tests that check interaction between packages).
• docker/ — files for Docker (Dockerfile, docker-compose.yml).

Configuring Co