Service Layer Pattern: Achieving True Decoupling in Laravel

Previously in this course, we explored implementing action classes to handle single-purpose domain operations. While Actions are excellent for specific tasks, a Service Layer provides the necessary orchestration for complex business processes that span multiple domain entities or external integrations.

By moving business logic out of controllers and into dedicated service classes, you achieve true decoupling of your application's core functionality from its delivery mechanism (HTTP requests, CLI commands, or queued jobs).

Why a Service Layer?

In a standard Laravel application, it's tempting to put logic inside controllers. As your SaaS platform grows, these controllers become "fat," leading to code duplication, difficult unit testing, and rigid dependencies.

A Service Layer acts as a mediator. It doesn't replace models or actions; it coordinates them to fulfill a business requirement. When you use Dependency Injection to resolve these services, you make your code modular and significantly easier to mock during testing.

Building a Service Layer: A Worked Example

Let's advance our SaaS project by creating a SubscriptionService. This service will handle the complex logic of upgrading a user's plan, which involves interacting with the database, our payment gateway, and broadcasting notifications.

1. Define the Service Interface

Always start with an interface to ensure your code remains swappable.

PHP
namespace App\Services\Contracts;

use App\Models\User;
use App\Models\Plan;

interface SubscriptionServiceInterface
{
    public function upgrade(User $user, Plan $plan): bool;
}

2. Implement the Concrete Service

The service orchestrates existing actions and repositories. Note how we inject dependencies via the constructor.

PHP
namespace App\Services;

use App\Services\Contracts\SubscriptionServiceInterface;
use App\Models\User;
use App\Models\Plan;
use App\Actions\Billing\ProcessPaymentAction;
use Illuminate\Support\Facades\DB;

class SubscriptionService implements SubscriptionServiceInterface
{
    public function __construct(
        protected ProcessPaymentAction $paymentAction
    ) {}

    public function upgrade(User $user, Plan $plan): bool
    {
        return DB::transaction(function () use ($user, $plan) {
            #6A9955">// Orchestrate business logic
            $this->paymentAction->execute($user, $plan->price);
            
            $user->update(['plan_id' => $plan->id]);
            
            return true;
        });
    }
}

3. Bind in a Service Provider

To leverage Laravel's container, bind the interface to the implementation in your AppServiceProvider or a dedicated DomainServiceProvider.

PHP
public function register()
{
    $this->app->bind(
        \App\Services\Contracts\SubscriptionServiceInterface::class,
        \App\Services\SubscriptionService::class
    );
}

Injecting Services into Controllers and Jobs

Because we've registered our service in the container, injecting it is trivial. Laravel automatically resolves the dependency.

In a Controller:

PHP
public function store(Request $request, SubscriptionServiceInterface $service)
{
    $service->upgrade($request->user(), $request->plan);
    return response()->json(['message' => 'Upgraded successfully']);
}

In a Queued Job:

PHP
class ProcessUserMigration implements ShouldQueue
{
    public function handle(SubscriptionServiceInterface $service)
    {
        #6A9955">// The container resolves the service even in background jobs
        $service->upgrade($this->user, $this->newPlan);
    }
}

Comparison: Action Classes vs. Service Layer

Hands-on Exercise

1. Identify one complex controller method in your current project that performs at least three distinct actions (e.g., updating a DB, sending an email, and calling an API).
2. Create a new Service class (e.g., UserOnboardingService) to encapsulate this orchestration.
3. Use advanced dependency injection to bind the service and inject it into the controller.
4. Refactor the controller to be a "thin" entry point that only handles the request/response cycle.

Common Pitfalls

• The "God Service": Avoid creating a single AppService that handles everything. Keep services aligned with bounded contexts.
• Service-to-Service Dependency: If ServiceA depends on ServiceB, ensure you aren't creating circular dependencies. If you find yourself doing this, reconsider your domain boundaries.
• Over-Engineering: Don't force every simple CRUD operation into a Service. If an action class suffices, keep it simple. Only elevate to a Service when orchestration becomes messy.

Recap

By implementing a Service Layer, you decouple your business rules from the HTTP layer. This makes your application easier to test, more modular, and resilient to change. Remember to use interfaces to maintain flexibility and leverage the service container for clean dependency management.

Up next: We will explore how to organize these services into a Modular Monolith Structure to keep your domain boundaries strictly enforced as the codebase scales.