DEV Community

Cover image for Laravel Service Classes: A Stateless Service Layer That Works
Shakil Alam
Shakil Alam

Posted on Originally published at blog.shakiltech.com

Laravel Service Classes: A Stateless Service Layer That Works

Series: Every Laravel Project Should Have These Building Blocks

Part: 8 of 35 | Level: Intermediate | Prerequisites: Thin Controllers


What You’ll Learn

  • What a Service class is and what it is not
  • The stateless rule and why it matters
  • How to organize services by domain
  • When to use a Service vs. an Action
  • How to test service classes
  • The Services/Core/ infrastructure pattern

What Is a Service Class?

A Service is a class that encapsulates a body of business logic that is too complex for a single Action, involves multiple models or external systems, or needs to be called from multiple places.

Services are stateless: they don’t hold data between method calls. They receive everything they need as arguments and return results. They have no $this->currentUser or $this->cachedResult properties.

// ✅ Stateless — everything comes in, everything goes out
final class OrderService
{
    public function __construct(
        private readonly StripePaymentServiceInterface $stripe,
        private readonly InventoryService $inventory,
    ) {}

    public function processPaymentAndReserveStock(
        Order $order,
        string $paymentIntentId
    ): PaymentResult {
        $result = $this->stripe->confirm($paymentIntentId);

        if ($result->succeeded()) {
            $this->inventory->reserveForOrder($order);
        }

        return $result;
    }
}

// ❌ Stateful — holds data between calls, causes bugs
final class OrderService
{
    private Order $currentOrder; // ← DON'T DO THIS

    public function setOrder(Order $order): void
    {
        $this->currentOrder = $order;
    }

    public function process(): void
    {
        // uses $this->currentOrder — but what if setOrder() wasn't called?
    }
}
Enter fullscreen mode Exit fullscreen mode

Organizing Services by Domain

When you have more than 2–3 services, group them in subdirectories by the domain they belong to:

app/Services/
├── Core/
│   └── ErrorReporter.php      # Cross-cutting infrastructure
│
├── Status/
│   ├── StatusService.php
│   ├── Contracts/
│   │   ├── StatusCheckInterface.php
│   │   └── StatusServiceInterface.php
│   └── Checks/
│       ├── DatabaseCheck.php
│       ├── CacheCheck.php
│       └── QueueCheck.php
│
├── Order/
│   ├── OrderService.php
│   ├── OrderPaymentService.php
│   └── CouponValidationService.php
│
├── Stripe/
│   ├── StripePaymentService.php
│   └── StripePaymentServiceInterface.php
│
└── Ai/
    ├── OllamaService.php
    ├── OllamaServiceInterface.php
    ├── EmbeddingService.php
    └── ChatContextService.php
Enter fullscreen mode Exit fullscreen mode

The domain grouping has two benefits: you can find services by feature, and you can see at a glance how complex each domain is.


Service with a Contract (Interface)

When a service talks to an external system (Stripe, AWS, a third-party API), back it with an interface. This lets you swap the implementation in tests or if you change providers.

// app/Services/Stripe/StripePaymentServiceInterface.php
<?php

declare(strict_types=1);

namespace App\Services\Stripe;

interface StripePaymentServiceInterface
{
    public function createPaymentIntent(int $amountInCents, string $currency): PaymentIntent;

    public function confirmPayment(string $paymentIntentId): PaymentResult;

    public function refund(string $chargeId, ?int $amountInCents = null): Refund;
}
Enter fullscreen mode Exit fullscreen mode
// app/Services/Stripe/StripePaymentService.php
<?php

declare(strict_types=1);

namespace App\Services\Stripe;

use Stripe\StripeClient;

final class StripePaymentService implements StripePaymentServiceInterface
{
    private StripeClient $client;

    public function __construct()
    {
        $this->client = new StripeClient(config('services.stripe.secret'));
    }

    public function createPaymentIntent(int $amountInCents, string $currency): PaymentIntent
    {
        $intent = $this->client->paymentIntents->create([
            'amount'   => $amountInCents,
            'currency' => $currency,
        ]);

        return new PaymentIntent(id: $intent->id, clientSecret: $intent->client_secret);
    }

    // ...
}
Enter fullscreen mode Exit fullscreen mode

Bind in AppServiceProvider::register():

$this->app->singleton(StripePaymentServiceInterface::class, StripePaymentService::class);
Enter fullscreen mode Exit fullscreen mode

Service with Multiple Responsibilities

When a domain has multiple responsibilities, split them into separate service classes rather than one large class:

// app/Services/ServiceRequest/
// ├── CreationService.php       — creates a new service request
// ├── PlanService.php           — assigns tasks and capacity
// ├── ReplanService.php         — re-plans an existing request
// ├── RejectionService.php      — handles the rejection workflow
// ├── EditService.php           — handles edits to a draft request
// ├── ReportService.php         — generates reports
// └── ProcessCompletionService.php — marks processes complete
Enter fullscreen mode Exit fullscreen mode

Each class has one responsibility. If you need to change how planning works, you touch PlanService – nothing else.

// app/Services/ServiceRequest/CreationService.php
final class CreationService
{
    public function __construct(
        private readonly CustomerRepository $customers,
        private readonly NotificationService $notifications,
    ) {}

    public function create(Merchandiser $merchandiser, array $data): ServiceRequest
    {
        return DB::transaction(function () use ($merchandiser, $data): ServiceRequest {
            $serviceRequest = ServiceRequest::create([
                ...$data,
                'created_by' => $merchandiser->id,
                'status'     => ServiceRequestStatus::Draft,
            ]);

            $this->notifications->notifyAdminsOfNewRequest($serviceRequest);

            return $serviceRequest;
        });
    }
}
Enter fullscreen mode Exit fullscreen mode

Service vs. Action – When to Use Each

This is the question developers ask most. Here’s the rule:

Use an Action when… Use a Service when…
The operation is atomic (one thing) The operation coordinates multiple things
It’s called from one place It’s called from multiple places
It has a clear before/after state It runs complex computations or queries
It wraps a DB transaction It talks to external APIs
Example: CreateOrderAction Example: OrderPaymentService

An Action typically calls a Service, not the other way around.

// Action orchestrates the high-level flow
final class CheckoutAction
{
    public function __construct(
        private readonly CartService $cart,
        private readonly CreateOrderAction $createOrder,
        private readonly StripePaymentServiceInterface $stripe,
    ) {}

    public function execute(User $user, OrderCustomerData $data): Order
    {
        $cartItems = $this->cart->getItems($user);

        $paymentIntent = $this->stripe->createPaymentIntent(
            $this->cart->calculateTotal($cartItems),
            'usd'
        );

        return $this->createOrder->execute($user, $data, $cartItems);
    }
}
Enter fullscreen mode Exit fullscreen mode

Services/Core/ – Infrastructure Services

Services/Core/ is for services that cut across the entire application and have no specific domain. The most important one is ErrorReporter:

// app/Services/Core/ErrorReporter.php
final class ErrorReporter
{
    public static function report(Throwable $e): void
    {
        // 1. Check we have recipients
        $recipients = self::validRecipients();
        if ($recipients === []) {
            return;
        }

        // 2 + 3. Deduplicate, then email. Wrapped: this runs inside the exception
        //        handler, so it must never throw (a DB-backed cache can be down)
        try {
            $key = 'exception:' . hash('sha256', $e->getMessage() . $e->getFile() . $e->getLine());
            if (Cache::add($key, true, now()->addMinutes(5)) === false) {
                return;
            }

            Mail::to($recipients)->send(new ExceptionOccurred(self::buildPayload($e)));
        } catch (Throwable $reporterError) {
            Log::error('ErrorReporter could not send the alert.', ['exception' => $reporterError]);
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

It’s a static utility class, not a traditional service – but it belongs in Services/Core/ because it’s a core infrastructure concern, not a domain concept.


Testing Services

Because services are stateless and receive their dependencies via constructor injection, they’re easy to test:

// tests/Unit/OrderServiceTest.php
class OrderServiceTest extends TestCase
{
    #[Test]
    public function it_creates_order_with_correct_total(): void
    {
        // Arrange
        $order  = new Order();
        $result = Mockery::mock(PaymentResult::class);
        $result->shouldReceive('succeeded')->andReturnTrue();

        $stripe = Mockery::mock(StripePaymentServiceInterface::class);
        $stripe->shouldReceive('confirm')->with('pi_123')->once()->andReturn($result);

        $inventory = Mockery::mock(InventoryService::class);
        $inventory->shouldReceive('reserveForOrder')->with($order)->once();

        $service = new OrderService($stripe, $inventory);

        // Act
        $outcome = $service->processPaymentAndReserveStock($order, 'pi_123');

        // Assert
        $this->assertTrue($outcome->succeeded());
    }
}
Enter fullscreen mode Exit fullscreen mode

No HTTP requests, no database calls in unit tests. Fast, reliable, focused.


Key Takeaways

  • Services are stateless – they receive input, return output, and don’t store state between calls.
  • Group services by domain in subdirectories: Services/Order/, Services/Stripe/, Services/Core/.
  • Back external service integrations with an interface so you can swap them in tests.
  • Services/Core/ is for infrastructure concerns that cut across the whole application.
  • When a service grows beyond one cohesive responsibility, split it: CreationService, EditService, ReportService.
  • Use an Action for atomic operations; use a Service for coordination, computation, and integration.

Frequently Asked Questions

When should I use a Service vs an Action?

Use an Action for a single named operation (CreateOrder, RejectRequest) that wraps a DB transaction and fires an event. Use a Service when you need reusable business logic that multiple Actions or commands share, or when you’re integrating with an external API.

The short rule: Action = do this thing once; Service = this knowledge is used in many places.

Should every Service have an interface?

Only when the Service talks to an external system (Stripe, AWS, a third-party API) or when you need to swap implementations in tests without real HTTP calls. Internal domain services that only touch your own database don’t need interfaces – the overhead isn’t worth it.

Can a Service call another Service?

Yes. OrderService can inject and call StripePaymentService or InventoryService. Just keep the dependency graph acyclic – no circular dependencies. If ServiceA needs ServiceB and ServiceB needs ServiceA, you have a design problem, not a PHP problem.


Tips and Gotchas

⚠️ Warning: Stateful services are a hidden bug. If your service stores $this->currentUser or $this->requestData, it will break when the same service instance is reused across requests (e.g., in queue workers or after auth()->login() is called multiple times in a test). Keep services stateless – pass data as method parameters.

💡 Tip: Services bound as singleton in the container should be stateless. Services that need per-request state should use bind() (a new instance per resolve) or accept state as constructor arguments and be resolved fresh each time.

🔥 Expert Note: Always bind service interfaces in the container, not concrete classes. $this->app->bind(PaymentServiceInterface::class, StripePaymentService::class) lets you swap implementations without touching any calling code – critical for testing and vendor migration.

Further Reading


← Route Organisation | Next: Action Classes →

Top comments (0)