Architecture of Complex Web Applications. With Laravel Examples

To avoid violating the Single Responsibility Principle (SRP) and creating high coupling, do not perform database lookups (like Post::find($id)) inside Web Controllers or Console Commands. Instead, encapsulate both the data retrieval and the business logic within a Service class. The controller should only pass the necessary identifier (e.g., $id) to the service, and the service should handle the database interaction internally. This ensures that changes to the database schema or infrastructure only require changes within the Service layer, rather than across all application interfaces (Web, API, Console).

class PostController
{
    public function publish($id, PostService $postService)
    {
        // The controller only passes the ID, not the entity
        if (!$postService->publish($id)) {
            return redirect()->back()->withMessage('...');
        }
        
        return redirect()->route('posts');
    }
}

final class PostService
{
    public function publish(int $id)
    {
        // The service handles the database lookup and logic
        $post = Post::find($id);
            
        if (!$post) {
            return false;
        }
        
        $post->published = true;
        
        return $post->save();
    }
}

When designing error handling in web applications, two primary architectural schools of thought exist:

1. The Ascetics (Exceptions only for exceptional situations):

   • Exceptions are reserved for truly unexpected events (e.g., database failure, filesystem errors).
   • Expected failures (e.g., invalid email, wrong password) are handled by returning a result object, such as a FunctionResult.
   • Pros: Logic is explicit; errors are not "thrown" up the stack.
   • Cons: Requires constant manual checking of return values (e.g., if ($result->isError())) throughout the Application Layer and Controllers.

2. The One True Path (Any negative situation is an exception):

   • Any deviation from the successful execution path (invalid data, unauthorized access, server failure) triggers an exception.
   • Pros: Results in cleaner, more unified code. Methods focus on the "happy path," and errors automatically propagate to a central handler.
   • Cons: Requires a mechanism to distinguish between Client Errors (4xx) and Server Errors (5xx) at the boundary (e.g., in the Controller or Global Exception Handler) to ensure correct HTTP status codes and logging levels.

In the context of Laravel, the book follows The One True Path, utilizing Laravel's HttpException to specify HTTP codes and Eloquent's *OrFail() methods to trigger exceptions automatically.

When refactoring code to eliminate duplication between store and update methods, avoid the trap of creating a single method that handles both actions via a boolean flag (e.g., updateOrCreateUser(..., boolean $update)).

As requirements evolve, the logic for creating a resource and updating a resource will inevitably diverge. Combining them into one method leads to 'monster methods' filled with complex if ($update) conditional blocks, which are difficult to debug and maintain.

Best Practice:

• Keep create and update logic in separate methods.
• Identify truly identical logic (e.g., file uploads, specific calculations) and extract only that shared logic into dedicated methods or classes with precise names.
• Use meaningful naming to identify architectural smells: names containing "Or" (like updateOrCreate) often signal that a single method is trying to perform two distinct logical operations.

// BAD: A monster method that tries to handle two different lifecycles
protected function updateOrCreateUser(..., boolean $update)
{
    if ($update)...
    if ($update)...
    if (!$update)...
}

A typical service class often mixes read methods (e.g., getById, getLatestPosts) and write methods (e.g., create, publish, delete). This violates the Single Responsibility Principle and complicates refactoring, such as adding caching. Since caching is typically only relevant for read operations, you should separate these responsibilities into distinct classes or interfaces.

To implement this, keep your write-only service (e.g., PostService) and create a separate interface (e.g., PostQueries) for read operations. This allows you to use the Decorator pattern to add caching to the read operations without affecting the write logic.

final class PostService
{
    public function create(PostCreateDto $dto){}
    public function publish($postId){}
    public function delete($postId){}
}

interface PostQueries
{
    public function getById($id): Post;
    public function getLatestPosts(): array;
    public function getAuthorPosts($authorId): array;
}

final class DatabasePostQueries implements PostQueries{}

final class CachedPostQueries implements PostQueries
{
    public function __construct(
        private PostQueries $baseQueries,
        private Cache $cache,
    ) {}
    
    public function getById($id): Post
    {
        return $this->cache->remember('post_' . $id, 
            function() use($id) {
                return $this->baseQueries->getById($id);
            });
    }
}

Using $model->update($request->all()) is a common but dangerous habit. It creates a loss of control because the code no longer explicitly states what business logic is being executed. It treats the application as a mere interface to database rows rather than a system of domain objects.

The Problem (Treating symptoms): Developers often try to fix the lack of control by observing changes after the fact, which is error-prone:

function afterUserUpdate(User $user)
{
    if (!$user->getOriginal('isBanned') && $user->isBanned) {
        // Send 'banned' email
    }
}

The Solution (Treating the cause): Instead of generic updates, use explicit methods or command classes that represent the business action. This makes the intent clear and provides a single point to trigger necessary side effects.

Recommended patterns:

• UserController::ban(int $id)
• $user->ban()
• BanUserCommand

In some frameworks like Laravel, traits are used to split a large class into multiple files (similar to partial class in C#). For example, the Laravel Request class uses several traits like InteractsWithContentTypes and InteractsWithInput to manage its various responsibilities.

Architectural Warning: If a class needs to be split using traits, it is often a sign that the class has too many responsibilities (violating the Single Responsibility Principle). Instead of using traits to split a class, it is better to decompose the class into smaller, focused objects and compose the main class using Dependency Injection.

// Example of a class split by traits (Laravel style)
class Request extends SymfonyRequest 
    implements Arrayable, ArrayAccess
{
    use Concerns\InteractsWithContentTypes,
        Concerns\InteractsWithFlashData,
        Concerns\InteractsWithInput;
}

// Better approach: Composition via DI
class Request
{
    private $session;
    private $input;
    private $cookies;

    public function __construct(
        Session $session, 
        RequestInput $input, 
        Cookies $cookies
    ) {
        $this->session = $session;
        $this->input = $input;
        $this->cookies = $cookies;
    }
}

Since PHP does not support extension methods (like Kotlin or C#), you cannot directly add methods to interfaces belonging to external libraries (e.g., Laravel's Dispatcher).

To add functionality like multiDispatch to an existing interface without using inheritance (which complicates constructors), use the Wrapper Interface pattern:

1. Define a new, minimal interface containing only the additional methods you need.
2. Create a concrete implementation that wraps the original third-party service.
3. Bind the new interface to the wrapper implementation in your application's Service Provider.
4. Inject the new interface into your service classes instead of the original one.

This approach keeps your services clean, avoids parent::__construct boilerplate, and reduces dependency on specific library implementations.

// 1. Define the new minimal interface
interface MultiDispatcher
{
    public function multiDispatch(array $events);
}

// 2. Implement the wrapper
use Illuminate\Contracts\Events\Dispatcher;

final class LaravelMultiDispatcher implements MultiDispatcher
{
    /** @var Dispatcher */
    private $dispatcher;

    public function __construct(Dispatcher $dispatcher)
    {
        $this->dispatcher = $dispatcher;
    }

    public function multiDispatch(array $events)
    {
        foreach($events as $event) {
            $this->dispatcher->dispatch($event);
        }
    }
}

// 3. Bind in Service Provider
class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $this->app->bind(
            MultiDispatcher::class, 
            LaravelMultiDispatcher::class
        );
    }
}

// 4. Use in your service
final class SomeService
{
    /** @var MultiDispatcher */
    private $dispatcher;
    
    public function __construct(..., MultiDispatcher $dispatcher)
    {
        $this->dispatcher = $dispatcher;
    }

    public function someMethod()
    {
        $this->dispatcher->multiDispatch($events);
    }
}