Structuring large Laravel applications

In this lesson’s refactor of a Pathshala admissions endpoint, the fat version of the AdmissionController printed 44 lines in wc -l and the refactored version printed 30, with the same feature test passing against both. The 44-line original holds validation, normalisation, a seat check, an event dispatch and the response shaping in one method, which is more than one person can hold in their head once the Fees and Attendance teams start reaching for the same models.

Laravel 13’s slim skeleton stays kind as long as one or two people own the whole project. This lesson shows one answer when it is not enough: an app/Domain/<Area> folder of actions, data objects and events, a short table that chooses between a direct call, an event and a queued job for the calls that cross module lines, and a Pest architecture test that keeps modules out of one another.

Where domain code lives

The default app/ folder of a Laravel 13 project is small on purpose. Controllers go under app/Http/Controllers/, models under app/Models/, service providers under app/Providers/, and that is nearly all. A team of one or two can hold the whole picture by searching those folders. The directory structure documentation leaves it to you to extend app/: Laravel does not care how you nest it, as long as composer.json autoloads it under App\.

A domain-driven folderdomain-driven folder: A folder under app/Domain/<Area>/ that groups one business area's actions, data objects, events and listeners, so one search finds the whole module and no file in another module reaches into its code. is app/Domain/<Area>/, where <Area> is one of the words the office uses: Admissions, Fees, Attendance, Payroll. Each module owns the classes that belong to its own job and never reaches into another module’s models. The result is a modular monolithmodular monolith: One deployable application with one database and one request/response cycle, whose folders of code read as if they were separate modules. Each module owns its area and talks to the others only through events or explicit interfaces.: one deployable application, one database, one request/response cycle, but the folders of code read as if they were separate.

Nothing changes in composer.json: the default "App\\": "app/" PSR-4 rule covers App\Domain\Admissions\Actions\EnrolStudent at app/Domain/Admissions/Actions/EnrolStudent.php. No new provider is needed either, but one line of bootstrap/app.php is: event discovery scans only app/Listeners by default, so a module’s listeners are found once withEvents(discover: [__DIR__.'/../app/Domain/*/Listeners']) names every module’s folder (the * matches each module).

When does the split pay off? A heuristic, stated as opinion rather than a rule: when a folder outgrows what one person can hold in their head. Picture the admissions controller grown to 300 lines across two methods, with nobody able to say where the seat-limit code should go; an app/Domain/Admissions/ folder makes that question easy. Splitting a 100-line project is premature, and splitting a 10,000-line project late takes far longer than splitting it on time. The signal is the search: when a search for “fees” keeps dragging a reader into app/Http/Controllers/AdmissionController.php, the split has already waited too long.

Actions: one method a class

An action classaction class: A plain class with one public method, often handle, that holds one business rule and knows nothing of HTTP, so controllers, commands and jobs can all call it. More in “Controllers and route model binding” is a plain class with one public method, usually __invoke, that does one piece of the business. Pathshala’s EnrolStudent takes an admission request, checks the seat count and dispatches a domain event. Its constructor is empty, so the container builds it from its type-hints, which lets any caller take it as a dependency: the HTTP controller, a queued job that retries a failed webhook, an Artisan command that runs a nightly backfill, or a Livewire component on an admin page. The office rule lives in one file, called the same way from everywhere.

The lesson’s refactor example runs the same PHPUnit feature test, through php artisan test, against the fat and the slim controller, so the user-visible behaviour never changes:

from session import run

# A before-and-after refactor of Pathshala's admissions endpoint. The before controller holds validation,
# normalisation, the seat check and the event dispatch in one method; the after controller delegates to an
# EnrolStudent action under app/Domain/Admissions/. The same feature test runs against both versions and stays
# green. The two overlay folders drop their files flat into the project root (overlay keeps paths), so the
# session cps each file to its real Laravel path and runs the test twice. Last, event:list shows that the module's
# listener is registered only after bootstrap/app.php points event discovery at app/Domain/*/Listeners.
run(
    """
cp web.php routes/web.php
cp AdmissionTest.php tests/Feature/AdmissionTest.php
cp AdmissionController.before.php app/Http/Controllers/AdmissionController.php
wc -l app/Http/Controllers/AdmissionController.php
php artisan test --filter=AdmissionTest
mkdir -p app/Domain/Admissions/Actions app/Domain/Admissions/Data app/Domain/Admissions/Events app/Domain/Admissions/Listeners
cp AdmissionController.after.php app/Http/Controllers/AdmissionController.php
cp EnrolStudent.php app/Domain/Admissions/Actions/EnrolStudent.php
cp AdmissionRequest.php app/Domain/Admissions/Data/AdmissionRequest.php
cp StudentEnrolled.php app/Domain/Admissions/Events/StudentEnrolled.php
cp SendWelcomeMessage.php app/Domain/Admissions/Listeners/SendWelcomeMessage.php
wc -l app/Http/Controllers/AdmissionController.php app/Domain/Admissions/Actions/EnrolStudent.php app/Domain/Admissions/Data/AdmissionRequest.php
php artisan test --filter=AdmissionTest
php artisan event:list --event=StudentEnrolled
cp app.php bootstrap/app.php
php artisan event:list --event=StudentEnrolled
""",
    app=True,
    overlay=("before", "after"),
)

$ cp web.php routes/web.php
$ cp AdmissionTest.php tests/Feature/AdmissionTest.php
$ cp AdmissionController.before.php app/Http/Controllers/AdmissionController.php
$ wc -l app/Http/Controllers/AdmissionController.php
      44 app/Http/Controllers/AdmissionController.php
$ php artisan test --filter=AdmissionTest
   PASS  Tests\Feature\AdmissionTest
  ✓ post admissions returns 201 with the centre                          …s

  Tests:    1 passed (2 assertions)
  Duration: …s
$ mkdir -p app/Domain/Admissions/Actions app/Domain/Admissions/Data app/Domain/Admissions/Events app/Domain/Admissions/Listeners
$ cp AdmissionController.after.php app/Http/Controllers/AdmissionController.php
$ cp EnrolStudent.php app/Domain/Admissions/Actions/EnrolStudent.php
$ cp AdmissionRequest.php app/Domain/Admissions/Data/AdmissionRequest.php
$ cp StudentEnrolled.php app/Domain/Admissions/Events/StudentEnrolled.php
$ cp SendWelcomeMessage.php app/Domain/Admissions/Listeners/SendWelcomeMessage.php
$ wc -l app/Http/Controllers/AdmissionController.php app/Domain/Admissions/Actions/EnrolStudent.php app/Domain/Admissions/Data/AdmissionRequest.php
      30 app/Http/Controllers/AdmissionController.php
      29 app/Domain/Admissions/Actions/EnrolStudent.php
      28 app/Domain/Admissions/Data/AdmissionRequest.php
      87 total
$ php artisan test --filter=AdmissionTest
   PASS  Tests\Feature\AdmissionTest
  ✓ post admissions returns 201 with the centre                          …s

  Tests:    1 passed (2 assertions)
  Duration: …s
$ php artisan event:list --event=StudentEnrolled
   INFO  Your application doesn't have any events matching the given criteria.
$ cp app.php bootstrap/app.php
$ php artisan event:list --event=StudentEnrolled
  App\Domain\Admissions\Events\StudentEnrolled ...............................
  ⇂ App\Domain\Admissions\Listeners\SendWelcomeMessage@handle

The before controller (44 lines) carries validation, normalisation, the seat check, the event dispatch and the response shape in one store method. The after controller (30 lines) validates the HTTP shape and asks the EnrolStudent action to do the rest. The action owns the seat rule, the data object normalises the HTTP names into camel case, and the event file is the only shape another module may listen for.

The last three commands show the one line the move costs. With the skeleton’s bootstrap/app.php, php artisan event:list --event=StudentEnrolled finds no listener at all, because discovery looks only in app/Listeners; once the file names app/Domain/*/Listeners, the same command lists SendWelcomeMessage@handle for StudentEnrolled. A listener that nothing registered fails silently: the feature test above passed while SendWelcomeMessage was not registered, so only a test that checks the listener ran, or event:list, catches it.

<?php

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Str;

// The admissions controller as a growing team tends to leave it: validation, normalisation, the seat check, the
// event dispatch and the response shaping, all in one method. Everything a reviewer must hold in their head to
// change one line of this feature lives in this one file.
class AdmissionController extends Controller
{
    public function store(Request $request): JsonResponse
    {
        $data = $request->validate([
            'student_name'   => ['required', 'string', 'min:2', 'max:120'],
            'guardian_phone' => ['required', 'regex:/^[6-9]\d{9}$/'],
            'course'         => ['required', 'string', 'max:60'],
            'centre'         => ['required', 'string', 'max:60'],
        ]);

        $studentName = (string) Str::of($data['student_name'])->squish()->title();
        $course      = (string) Str::of($data['course'])->squish();
        $centre      = (string) Str::of($data['centre'])->squish();

        $seatKey = sprintf('seats:%s:%s', Str::slug($centre), Str::slug($course));
        if ((int) Cache::get($seatKey, 0) >= 30) {
            return response()->json(['error' => 'course is full'], 409);
        }

        Cache::increment($seatKey);
        Event::dispatch('student.enrolled', [[
            'student_name'   => $studentName,
            'guardian_phone' => $data['guardian_phone'],
            'course'         => $course,
            'centre'         => $centre,
        ]]);

        return response()->json(['centre' => $centre], 201);
    }
}

<?php

namespace App\Http\Controllers;

use App\Domain\Admissions\Actions\EnrolStudent;
use App\Domain\Admissions\Data\AdmissionRequest;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

// The admissions controller after the refactor: validates the HTTP shape, hands the parsed request to one action
// and shapes the response. Everything the office cares about (seat limits, who else needs telling, how the id is
// built) now lives in the Admissions module, where a search for "fees" or "attendance" never has to tread.
class AdmissionController extends Controller
{
    public function store(Request $request, EnrolStudent $enrol): JsonResponse
    {
        $data = $request->validate([
            'student_name'   => ['required', 'string', 'min:2', 'max:120'],
            'guardian_phone' => ['required', 'regex:/^[6-9]\d{9}$/'],
            'course'         => ['required', 'string', 'max:60'],
            'centre'         => ['required', 'string', 'max:60'],
        ]);

        $outcome = $enrol(AdmissionRequest::fromValidated($data));

        return $outcome['ok']
            ? response()->json(['centre' => $outcome['centre']], 201)
            : response()->json(['error' => 'course is full'], 409);
    }
}

<?php

namespace App\Domain\Admissions\Actions;

use App\Domain\Admissions\Data\AdmissionRequest;
use App\Domain\Admissions\Events\StudentEnrolled;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Str;

// One job per class: EnrolStudent takes a parsed admission and either takes a seat for it or reports back that
// the course is full. The controller, the queue worker that retries a failed webhook and the console seeder for
// a new centre all call the same __invoke method, so the office rule lives in exactly one place.
final class EnrolStudent
{
    private const SEATS = 30;

    public function __invoke(AdmissionRequest $request): array
    {
        $seatKey = sprintf('seats:%s:%s', Str::slug($request->centre), Str::slug($request->course));
        if ((int) Cache::get($seatKey, 0) >= self::SEATS) {
            return ['ok' => false, 'centre' => $request->centre];
        }

        Cache::increment($seatKey);
        StudentEnrolled::dispatch($request);

        return ['ok' => true, 'centre' => $request->centre];
    }
}

<?php

namespace App\Domain\Admissions\Data;

use Illuminate\Support\Str;

// A readonly data object that stands between the HTTP shape (snake_case names, trailing spaces, lower-case
// titles) and the domain's own vocabulary. Nothing inside the Admissions module reads the request array
// directly: everything takes an AdmissionRequest and names its fields in camel case.
final readonly class AdmissionRequest
{
    public function __construct(
        public string $studentName,
        public string $guardianPhone,
        public string $course,
        public string $centre,
    ) {}

    public static function fromValidated(array $data): self
    {
        return new self(
            studentName:   (string) Str::of($data['student_name'])->squish()->title(),
            guardianPhone: $data['guardian_phone'],
            course:        (string) Str::of($data['course'])->squish(),
            centre:        (string) Str::of($data['centre'])->squish(),
        );
    }
}

<?php

namespace App\Domain\Admissions\Events;

use App\Domain\Admissions\Data\AdmissionRequest;
use Illuminate\Foundation\Events\Dispatchable;

// A domain event: the only shape the rest of the app sees when a student is enrolled. The Fees and Attendance
// modules listen for this class without knowing anything else about the Admissions module.
final class StudentEnrolled
{
    use Dispatchable;

    public function __construct(public AdmissionRequest $request)
    {
    }
}

<?php

namespace App\Domain\Admissions\Listeners;

use App\Domain\Admissions\Events\StudentEnrolled;
use Illuminate\Support\Facades\Log;

// A listener kept beside the event it listens for. Event discovery registers it for the event its handle() method
// type-hints once bootstrap/app.php names the module folders (withEvents(discover: [.../app/Domain/*/Listeners]));
// by default Laravel scans only app/Listeners.
final class SendWelcomeMessage
{
    public function handle(StudentEnrolled $event): void
    {
        Log::info('welcome queued', [
            'student' => $event->request->studentName,
            'centre'  => $event->request->centre,
        ]);
    }
}

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Request;

// bootstrap/app.php of the Laravel 13 skeleton with one call added: withEvents() points event discovery at every
// module's Listeners folder. Without it Laravel scans only app/Listeners, so a listener kept in
// app/Domain/Admissions/Listeners is never registered and its event reaches nobody.
return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withEvents(discover: [
        __DIR__.'/../app/Domain/*/Listeners',
    ])
    ->withMiddleware(function (Middleware $middleware): void {
        //
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        $exceptions->shouldRenderJsonWhen(
            fn (Request $request) => $request->is('api/*') || $request->expectsJson(),
        );
    })->create();

A readonly data object is cheap insurance: nothing inside the module reads $data['student_name'] by key, and a rename of the HTTP field is one line in AdmissionRequest::fromValidated. The action signature __invoke(AdmissionRequest $request) reads like the sentence an office worker would say: “enrol this student”.

Modules talking: events, calls or jobs

Modules talk through one of three shapes: a direct call through an interface the other module publishes, a domain event with listeners in the modules that care, or a queued job that a worker runs later. Choosing among them is less a style question than a question about what the caller needs and what the receiver does. The lesson’s example trace is the one request that goes through the slim admissions controller:

The three shapes make different promises. A direct call is a method call in the same process: the caller gets the receiver’s return value or its exception. Between modules, the caller type-hints an interface the receiving module publishes, such as App\Domain\Admissions\Contracts\SeatCounter, whose method returns a number, not a model; one bind() call in a service provider tells the container which Admissions class to inject, so no other module imports its actions. An event is a dispatch to listeners that the caller never names; by default the listeners run synchronously, so the response still waits for them, but a listener that implements ShouldQueue moves to the queue. A job is a message handed to a worker process: the dispatch returns at once and the sender never sees the outcome.

The question “does the caller need the result in the same response?” picks the row. A controller that must return a 201 with the enrolled centre takes a direct call to EnrolStudent; a side effect such as sending the welcome message goes on an event listenerevent listener: A class that reacts to one event class. Laravel registers it for the event that its handle or __invoke method is type-hinted with. More in “Events, listeners and model observers”; a slow outside call, such as a payment gateway, goes on a queued job with retries and backoff. A sync event that reaches a slow SMS gateway holds up every admission request, so measure before promising a listener will stay sync.

The pattern that hurts, in practice, is a listener that reaches into another module’s model. A listener registered by the Fees module for StudentEnrolled must not type-hint App\Domain\Admissions\Models\Enrolment; it should read the plain values off the event and build its own Fees-side data. The next section lets a test refuse that reach.

Boundaries enforced by Pest arch tests

An architecture testarchitecture test: A test that states a rule about the shape of the code, such as which classes may use a function, and checks every class against it without running the code. More in “Browser tests, static analysis and CI” is a Pest rule about every class in the project’s own namespaces, checked without running any of the code. Each rule names a boundary ruleboundary rule: An architecture rule that says what one module may or may not import. 'The Fees module must not use the Admissions module' is a boundary rule written as one Pest arch() expectation. as a short sentence: “every action class is final and has an __invoke method”, “Fees may not use Admissions models or actions”. Pest finds the files of each namespace through Composer’s autoload paths and reads their source, so no request, database or browser is involved.

The test file states three rules, and the session runs it twice:

<?php

// Pest architecture tests are facts about every class in the project's own namespaces, checked without running
// any application code. Each arch() call names one rule: a short description, the classes it looks at and the
// shape it enforces.

arch('every action class is final and has an __invoke method')
    ->expect('App\\Domain\\Fees\\Actions')
    ->toBeFinal()
    ->toHaveMethod('__invoke');

// Admissions' events are its public face: a Fees listener may import StudentEnrolled. Its models and actions are
// private to Admissions, so the rule names those two namespaces rather than the whole module.
arch('Fees may not use Admissions models or actions')
    ->expect('App\\Domain\\Fees')
    ->not->toUse(['App\\Domain\\Admissions\\Models', 'App\\Domain\\Admissions\\Actions']);

arch('no debugging helpers are left behind in the domain code')
    ->expect(['dd', 'dump', 'var_dump', 'ray'])
    ->not->toBeUsed();

from session import run

# Pest architecture tests for the Pathshala project. The session installs Pest and its arch plugin offline from
# the course's repo-testing (lane 0147) with -q so the composer step prints nothing but its own line, then runs
# tests/Arch/BoundariesTest.php. The initial state has a boundary violation: the Fees IssueReceipt action imports
# Admissions' Enrolment model, which the rule refuses. The fix (good/IssueReceipt.php) takes plain values, and
# the Fees listener that calls the action shapes them from an event.
run(
    """
# Install Pest and its arch plugin offline from the course's repository (output suppressed with -q).
composer require --dev pestphp/pest -W -q
! vendor/bin/pest tests/Arch/BoundariesTest.php
cp good/IssueReceipt.php app/Domain/Fees/Actions/IssueReceipt.php
vendor/bin/pest tests/Arch/BoundariesTest.php
""",
    app=True,
    overlay=("arch",),
    repos=("repo-testing",),
)

# Install Pest and its arch plugin offline from the course's repository (output suppressed with -q).
$ composer require --dev pestphp/pest -W -q
$ vendor/bin/pest tests/Arch/BoundariesTest.php
   FAIL  Tests\Arch\BoundariesTest
  ✓ every action class is final and has an __invoke method               …s
  ⨯ Fees may not use Admissions models or actions                        …s
  ✓ no debugging helpers are left behind in the domain code              …s
  ────────────────────────────────────────────────────────────────────────────
   FAILED  Tests\Arch\BoundariesTest > Fees may not use Admissions models or…
  Expecting 'App\Domain\Fees' not to use 'App\Domain\Admissions\Models'.


  Tests:    1 failed, 2 passed (6 assertions)
  Duration: …s
[exit status 1]
$ cp good/IssueReceipt.php app/Domain/Fees/Actions/IssueReceipt.php
$ vendor/bin/pest tests/Arch/BoundariesTest.php
   PASS  Tests\Arch\BoundariesTest
  ✓ every action class is final and has an __invoke method               …s
  ✓ Fees may not use Admissions models or actions                        …s
  ✓ no debugging helpers are left behind in the domain code              …s

  Tests:    3 passed (7 assertions)
  Duration: …s

In the first run, the Fees module’s IssueReceipt action takes an Admissions\Models\Enrolment directly, so the second rule fails with Expecting 'App\Domain\Fees' not to use 'App\Domain\Admissions\Models'. and the run ends with exit status 1, which is what turns a CI job red. The message names the two namespaces, not the file, so the next step is a search for use App\Domain\Admissions\Models under app/Domain/Fees/. The fixed IssueReceipt takes plain values ($enrolmentId, $centre, $course, $amountPaise) and the second run passes all three rules.

The rule names Admissions’ models and actions rather than the whole module on purpose. A Fees listener for StudentEnrolled has to import that event class, and Admissions’ events and published interfaces are the classes other modules are meant to use; a rule against all of App\Domain\Admissions would fail on the very design the previous section recommends.

The Pest documentation calls each arch() call a test: its body is a fluent chain of expectations rather than assertions written by hand. One more pattern worth refusing in the same file is a generic repositorygeneric repository: A class whose methods forward to an Eloquent model (findById, findAll, save, delete). In Laravel this layer duplicates the query builder and rarely enables a storage swap; scopes or query objects usually serve better. that only wraps Eloquent: a UserRepository whose methods call User::query()->where(...) duplicates the query builder and adds a layer whose only trick is to name the parameter. Prefer a scope on the model or a plain query object; keep a repository for storage you may really swap, such as a cache in front of a slow HTTP source, where the interface pays for itself.

Practise

Build the receipt area for Pathshala in your own project, with the same shape as the Admissions module in examples/after/:

1. Make an app/Domain/Receipts/ folder with Actions/, Data/ and Listeners/.
2. Write a MintReceipt action with a single __invoke that takes $enrolmentId, $centre, $course, $amountPaise and returns a readonly Receipt.
3. Add a listener in app/Domain/Receipts/Listeners/ that handles App\Domain\Admissions\Events\StudentEnrolled, calls MintReceipt and writes the Receipt somewhere Receipts owns.
4. Copy the tests/Arch/BoundariesTest.php of the arch session and add a rule that App\Domain\Receipts may not use App\Domain\Admissions\Models.

The self-check covers all four sections:

Interview questions

A couple of warm-ups to answer in your own words, then two more with the deeper answers in the module’s bank.

Warm-up (fresher to 2–5 years): when do you split code into app/Domain/<Area>?

Not from the day the project is new. Laravel 13’s slim skeleton is kind as long as one or two people own the whole app. The signal is a controller or a model folder past the size one person can hold in their head: hundreds of lines, three concerns in one method, a search for “fees” that keeps dragging a reader into the admissions controller. Once four developers edit the same file in a week, the split pays for itself. Start by cutting one noisy folder at a time into app/Domain/<Area>/ with its own Actions, Data and Events; a big-bang split of a running codebase is painful and rarely finishes. Keep an architecture test ready for the first module, so the second module cannot reach into the first a week after the move.

Warm-up (fresher to 2–5 years): when is an event a better fit than a direct call?

When the caller does not need the receiver’s return value in the same response and the receivers may grow in number without the caller knowing their names. The admissions controller that must return a 201 to the parent should not call the Fees receipt code, the Attendance seat code and the welcome SMS code inline: it dispatches StudentEnrolled, and each module adds a listener in its own folder. A direct call fits when the caller needs the value or the exception back right away; a queued job fits when the work is slow enough to need retries. A synchronous event that calls an outside service holds up every request, so a listener that reaches an SMS gateway or a payment provider implements ShouldQueue.

Two more questions go further, into one costly pattern and one easy slip; the longer answers live in the module’s bank:

Key takeaways

• Split into app/Domain/<Area> folders when a folder outgrows what one person can hold in their head, not before.
• An action class is a plain class with one __invoke method, called from controllers, jobs, commands and Livewire with the same arguments.
• A readonly data object stops HTTP shapes from leaking into the module, so a renamed form field is one line of change.
• Modules talk through events or the interfaces a module publishes; a listener never type-hints another module’s model, and an architecture test refuses it when one does.
• A generic repository that only wraps Eloquent duplicates the query builder; prefer scopes, query objects or model methods unless you really will swap storage.