Víctor FalcónBecause of my work at developerjoy.co, I have created over 10 Laravel projects from scratch in the last year, and worked on more than 25 and I have seem one common thing in all of them.
The Laravel default directory structure only works when your project it's really small.
As the project grows, the default directory structure becomes a problem because it does not scale properly.
After a few use cases, models, policies, and so on, you will end with something similar to this:
app/
├── Actions
│ ├── Actionable.php
│ ├── Graph
│ │ └── ...
│ ├── MonthlyResume
│ │ └── GenerateMonthlyResumeAssets.php
│ ├── User
│ │ └── UpdateUser.php
│ └── VoidActionable.php
├── Console
│ ├── Commands
│ │ ├── CalculateUserCryptoPortfolioBalanceCommand.php
│ │ ├── CategorizeTransactionsIaCommand.php
│ │ ├── GenerateMonthlyReportAssetsCommand.php
│ │ ├── IdeHelperAllCommand.php
│ │ ├── PruneNotificationsCommand.php
│ │ ├── SendMonthlyReportNotificationCommand.php
│ │ ├── SendNewUpdateChangeLogNotificationCommand.php
│ │ └── TrainCategorizationIaCommand.php
│ └── Kernel.php
├── Contracts
│ └── Pipe.php
├── Events
│ ├── SharingConfigurationSaved.php
│ ├── SupportMessageCreated.php
│ └── VisitIncreased.php
├── Exceptions
│ ├── GetBankAccountTransactionError.php
│ ├── Handler.php
│ └── RenderableApiError.php
├── Http
│ ├── Controllers
│ │ ├── Banks
│ │ ├── Controller.php
│ │ ├── CryptoCurrency
│ │ ├── Notification
│ │ ├── SupportMessage
│ │ └── User
│ │ ├── DeleteUserController.php
│ │ ├── GetUserController.php
│ │ └── PutUserController.php
│ ├── Kernel.php
│ ├── Middleware
│ │ ├── Authenticate.php
│ │ ├── DefaultLocale.php
│ │ ├── TrustProxies.php
│ │ ├── ValidateSignature.php
│ │ └── VerifyCsrfToken.php
│ ├── Requests
│ │ ├── PostSupportMessageRequest.php
│ │ └── PutUserRequest.php
│ └── Resources
├── Jobs
│ ├── CalculateUserCryptoPortfolioBalanceJob.php
│ ├── GenerateMonthlyResumeAssetsJob.php
│ ├── GetBankAccountDetails.php
│ └── GetCoinGeckoValuesJob.php
├── Listeners
│ ├── SendAdminNotificationOnSupportMessageCreated.php
│ ├── SendEmailToUserOnVisitIncremented.php
│ └── SendMailOnSupportMessageCreated.phpphp
├── Mail
│ ├── SupportMessage
│ └── Visits
├── Models
│ ├── Bank.php
│ ├── SharingConfiguration.php
│ ├── SupportMessage.php
│ ├── User.php
│ └── UserCryptoPortfolioBalance.php
├── Notifications
│ ├── Notifiable.php
│ ├── ThrottledNotification.php
│ ├── UncategorizedTransactionNotification.php
│ └── UpdateChangeLogNotification.php
├── Policies
│ └── CryptoCurrencyOrderPolicy.php
├── Providers
│ ├── AppServiceProvider.php
│ ├── EventServiceProvider.php
│ ├── HorizonServiceProvider.php
│ └── RouteServiceProvider.php
├── Services
│ └── CategorizationAi.php
└── Support
├── OrderType.php
├── SafeNumberFromStringParser.php
├── ShortNumberFormatter.php
├── StockAssets
└── helpers.php
I removed a lot of files and directories from tree, but you can imagine that it's impossible to see all the code related to users.
As you can see, it's really difficult to know what's happening there. You are working in a users controller, for example, and you don't have all the relevant classes close to it.
You can't see, at a glance, all the relevant classes and models for your current use case.
A better directory structure in our Laravel project
The main key, to properly scale your app, is to being able to see al the related code to the current use case you're working on at a glance.
For example, if you're working on the user registration use case, you should have the user model, user policies, registration request, the registered event, and more, close to you.
src/
├── Leads
├── Teams
└── Users
├── Actions
│ ├── CreateUser
│ │ ├── CreateUser.php
│ │ └── CreateUserAction.php
│ ├── LoginUserAction.php
│ ├── LogoutUserAction.php
│ └── RefreshAuthenticationTokenAction.php
├── Authenticatable.php
├── Authentication.php
├── Events
│ └── UserRegistered.php
├── Http
│ ├── Controllers
│ │ └── Api
│ │ ├── PostAuthenticationLoginApiController.php
│ │ ├── PostAuthenticationLogoutApiController.php
│ │ ├── PostAuthenticationRefreshApiController.php
│ │ └── PostAuthenticationRegisterApiController.php
│ ├── Requests
│ │ ├── PostAuthenticationLoginRequest.php
│ │ └── PostUserRequest.php
│ └── routes
│ └── api.php
├── Infrastructure
│ └── UserEventServiceProvider.php
├── InvalidCredentials.php
├── Listeners
│ └── SendWelcomeEmailOnUserRegistered.php
├── Mail
│ └── WelcomeMail.php
└── User.php
But know, you're wondering, how can I achieve this architecture easily on Laravel.
How to implement a domain directory architecture on Laravel
The start point is composer.json file. We are going to create a new folder ./src to store all our new code.
Adding the directory to the psr-4 key in the composer.json we are going to autoimport all our files easily.
"autoload": {
"psr-4": {
"App\\": "app/",
"DeveloperJoy\\": "src/",
// ...
},
// ...
}
Just with this, you can put all your models, controllers, requests, policies, and more, in a custom domain folder under src/User, for example.
There are only a few things missing: routes, and providers, so let's go one by one.
Move routes to a custom folder
For routes we have multiple options, for me, the most simpler and easier is to import them in the web.php or in the api.php file.
I usually write a helper file inside routes folder that looks like this:
<?php
function domain_web_routes(string $domain): void
{
require __DIR__."/../src/{$domain}/Http/routes/web.php";
}
function domain_api_routes(string $domain): void
{
require __DIR__."/../src/{$domain}/Http/routes/api.php";
}
and imported in my composer.json file just adding it to the files array.
"autoload": {
// ...
"files": [
"routes/helpers.php"
]
},
A them, in my default web.php or api.php I just import each new domain folder when it has any route.
This is, for example, my web.php file:
<?php
use Illuminate\Support\Facades\Route;
Route::inertia('/', 'Welcome');
domain_web_routes('Leads');
Inside src/Leads/Http/routes y have a web.php file with all my routes related to leads.
Is really that simple.
Move service providers, to a custom domain folder
With providers is actually pretty easy.
We have a file under bootstrap/app.php that has an array of all our providers.
You just have to add new providers to it, and it will be processed automatically on load time.
return Application::configure(basePath: dirname(__DIR__))
->withProviders([
DeveloperJoy\Users\Infrastructure\UserEventServiceProvider::class,
])
->create();
