• Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
• Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
• My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
• Me: xgabriel.com | GitHub

Two PHP engineers are reviewing a pull request. One says "this should be an application service." The other says "no, a use case." They argue for fifteen minutes, agree they mean the same thing, merge the PR, and the next sprint someone opens app/Services/OrderService.php and finds nineteen public methods, two private helpers, and four injected dependencies that only two of those methods actually use.

That argument repeats in every PHP codebase that imports clean or hexagonal vocabulary without locking down what the words mean. The terms are not interchangeable. They describe two different things at two different sizes. Once a team agrees on the distinction, "where does this code go" stops being a debate.

Here is the rule that ends it: an ApplicationService is a layer that holds related operations. A UseCase is a single operation: one verb, one class, one public method. Both are valid. Picking one is a project-wide decision, not a per-feature one.

What the two words actually point at

Eric Evans introduced application services in Domain-Driven Design (2003) as the thin orchestration layer that sits between the inbound side (controllers, CLI, queue workers) and the domain. Robert Martin used use cases in Clean Architecture (2017) for the same orchestration responsibility, but framed each one as its own object. Both authors agree on what the code does. They disagree on how to package it.

In a PHP codebase the difference shows up at the file level.

An ApplicationService groups verbs that share a noun:

final class OrderApplicationService
{
    public function __construct(
        private readonly OrderRepository $orders,
        private readonly PaymentGateway $payments,
        private readonly EventDispatcher $events,
        private readonly Clock $clock,
    ) {}

    public function create(CreateOrderCommand $cmd): OrderId { /* ... */ }
    public function cancel(CancelOrderCommand $cmd): void    { /* ... */ }
    public function refund(RefundOrderCommand $cmd): void    { /* ... */ }
}

A UseCase isolates one verb in its own class:

final class CreateOrderUseCase
{
    public function __construct(
        private readonly OrderRepository $orders,
        private readonly Clock $clock,
    ) {}

    public function execute(CreateOrderCommand $cmd): OrderId { /* ... */ }
}

The orchestration, dependency set, and domain boundary are identical. Only the packaging changes. That is the whole disagreement.

The worked example: three verbs, two packagings

Here is the same order feature written both ways, in PHP 8.3, against the same domain. The domain types and ports are constant across both versions; only the application layer changes.

Shared pieces first.

<?php
declare(strict_types=1);

namespace App\Domain\Order;

final readonly class OrderId
{
    public function __construct(public string $value) {}
}

final class Order
{
    public function __construct(
        public readonly OrderId $id,
        public readonly string $customerId,
        public readonly int $totalCents,
        public readonly \DateTimeImmutable $createdAt,
        private string $status,
    ) {}

    public function cancel(): void
    {
        if ($this->status !== 'pending') {
            throw new \DomainException(
                "cannot cancel order in status {$this->status}"
            );
        }
        $this->status = 'cancelled';
    }

    public function refund(): void
    {
        if ($this->status !== 'paid') {
            throw new \DomainException(
                "cannot refund order in status {$this->status}"
            );
        }
        $this->status = 'refunded';
    }

    public function status(): string
    {
        return $this->status;
    }
}

Two ports, one for persistence and one for the payment side.

<?php
declare(strict_types=1);

namespace App\Application\Port;

use App\Domain\Order\Order;
use App\Domain\Order\OrderId;

interface OrderRepository
{
    public function save(Order $order): void;
    public function get(OrderId $id): Order;
}

interface PaymentGateway
{
    public function refund(OrderId $id, int $amountCents): void;
}

Three commands, one per verb.

<?php
declare(strict_types=1);

namespace App\Application\Command;

final readonly class CreateOrderCommand
{
    public function __construct(
        public string $customerId,
        public int $totalCents,
    ) {}
}

final readonly class CancelOrderCommand
{
    public function __construct(public string $orderId) {}
}

final readonly class RefundOrderCommand
{
    public function __construct(public string $orderId) {}
}

Version A — one ApplicationService class with three verbs

<?php
declare(strict_types=1);

namespace App\Application\Service;

use App\Application\Command\CancelOrderCommand;
use App\Application\Command\CreateOrderCommand;
use App\Application\Command\RefundOrderCommand;
use App\Application\Port\OrderRepository;
use App\Application\Port\PaymentGateway;
use App\Domain\Clock;
use App\Domain\Order\Order;
use App\Domain\Order\OrderId;

final class OrderApplicationService
{
    public function __construct(
        private readonly OrderRepository $orders,
        private readonly PaymentGateway $payments,
        private readonly Clock $clock,
    ) {}

    public function create(CreateOrderCommand $cmd): OrderId
    {
        $order = new Order(
            id:         new OrderId(bin2hex(random_bytes(8))),
            customerId: $cmd->customerId,
            totalCents: $cmd->totalCents,
            createdAt:  $this->clock->now(),
            status:     'pending',
        );
        $this->orders->save($order);
        return $order->id;
    }

    public function cancel(CancelOrderCommand $cmd): void
    {
        $order = $this->orders->get(new OrderId($cmd->orderId));
        $order->cancel();
        $this->orders->save($order);
    }

    public function refund(RefundOrderCommand $cmd): void
    {
        $order = $this->orders->get(new OrderId($cmd->orderId));
        $order->refund();
        $this->payments->refund($order->id, $order->totalCents);
        $this->orders->save($order);
    }
}

Notice what this version pays: every method has access to every constructor dependency, whether it needs it or not. create and cancel never touch $this->payments, but it is wired in regardless. That is the trade-off: convenience of grouping in exchange for looser dependency hygiene.

Version B — three UseCase classes, one verb each

<?php
declare(strict_types=1);

namespace App\Application\UseCase;

use App\Application\Command\CreateOrderCommand;
use App\Application\Port\OrderRepository;
use App\Domain\Clock;
use App\Domain\Order\Order;
use App\Domain\Order\OrderId;

final class CreateOrderUseCase
{
    public function __construct(
        private readonly OrderRepository $orders,
        private readonly Clock $clock,
    ) {}

    public function execute(CreateOrderCommand $cmd): OrderId
    {
        $order = new Order(
            id:         new OrderId(bin2hex(random_bytes(8))),
            customerId: $cmd->customerId,
            totalCents: $cmd->totalCents,
            createdAt:  $this->clock->now(),
            status:     'pending',
        );
        $this->orders->save($order);
        return $order->id;
    }
}

<?php
declare(strict_types=1);

namespace App\Application\UseCase;

use App\Application\Command\CancelOrderCommand;
use App\Application\Port\OrderRepository;
use App\Domain\Order\OrderId;

final class CancelOrderUseCase
{
    public function __construct(
        private readonly OrderRepository $orders,
    ) {}

    public function execute(CancelOrderCommand $cmd): void
    {
        $order = $this->orders->get(new OrderId($cmd->orderId));
        $order->cancel();
        $this->orders->save($order);
    }
}

<?php
declare(strict_types=1);

namespace App\Application\UseCase;

use App\Application\Command\RefundOrderCommand;
use App\Application\Port\OrderRepository;
use App\Application\Port\PaymentGateway;
use App\Domain\Order\OrderId;

final class RefundOrderUseCase
{
    public function __construct(
        private readonly OrderRepository $orders,
        private readonly PaymentGateway $payments,
    ) {}

    public function execute(RefundOrderCommand $cmd): void
    {
        $order = $this->orders->get(new OrderId($cmd->orderId));
        $order->refund();
        $this->payments->refund($order->id, $order->totalCents);
        $this->orders->save($order);
    }
}

Three files instead of one. Each class names exactly what it needs. CancelOrderUseCase has no idea PaymentGateway exists; CreateOrderUseCase does not pull in either of the other dependencies. The signature of each constructor is a precise inventory of the verb.

Side-by-side: what each style costs and pays for

Neither column is wrong. The right column is what Robert Martin draws on the whiteboard; the left column is what most Laravel and Symfony tutorials write. Teams get into trouble when half the codebase is one and half is the other.

How to pick one and stop arguing

Use ApplicationService when:

• The team is small and the surface area is small. Three to six verbs per noun, no plans to grow much.
• You are not running a command bus or a CQRS-style handler discovery. The orchestration entry point is the controller, and one injected service per noun is easier to wire than ten.
• The verbs share a lot of state-validation logic and pulling it into private methods on the same class is cleaner than extracting a shared collaborator.
• The team is new to clean/hexagonal vocabulary and you want a forgiving starting layer that won't explode into hundreds of files in week two.

Use UseCase when:

• The team uses a command bus (Symfony Messenger, Tactician, a homemade one) and each command needs a single handler. The 1-to-1 mapping is exactly what these libraries expect.
• Constructor hygiene matters more than file count. Reviewers should see at a glance which ports a single operation touches.
• The codebase has fifty or more verbs across a few nouns and the would-be OrderApplicationService is heading toward a thousand-line file with thirty dependencies.
• You want a one-screen unit of work that can be reasoned about, tested, and replaced in isolation.

The team makes one of those calls, writes it into the project's architecture doc, and stops debating it per-PR.

Two anti-patterns that ruin both styles

The God service. An OrderApplicationService with twenty-two public methods, fourteen injected dependencies, and a private function ensureOrderIsValid() that two-thirds of the methods call. This is the version everyone has met, and it is the reason people write angry blog posts about service layers. Renaming to UseCase changes nothing. The fix is to split the noun (OrderLifecycle, OrderRefunds, OrderFulfilment) or go per-verb.

The shadow service. A folder of UseCase classes where every class extends a BaseUseCase that injects a ServiceContainer and pulls dependencies out of it. The constructor lists nothing; the body calls $this->container->get(OrderRepository::class). This is an ApplicationService wearing a UseCase costume. It defeats the whole point: the constructor no longer tells you what the verb needs, and tests have to stub a container instead of passing two arguments. If the team picks UseCase, the constructor lists the real ports. Otherwise, pick ApplicationService and stop pretending.

Both anti-patterns come from the same place: treating the naming choice as decoration instead of a structural commitment. The structural commitment is what matters.

What survives across both styles

Whatever you pick, the rules below hold:

• The application layer never imports from the framework. No Eloquent models, no Symfony attributes, no Laravel facades. The application orchestrates the domain through ports.
• The domain knows nothing about the application layer. Entities and value objects sit one ring further in and stay there.
• One command class per verb, no matter whether the verb lives in its own UseCase or as a method on an ApplicationService. The command is the contract; the handler is the implementation.
• Controllers and CLI commands and queue workers are inbound adapters. They translate transport-level input into a command and call the application. They do not contain business logic.
• Ports live with the application layer (or the domain), not with the adapters that implement them. The application names the shape of what it needs; infrastructure conforms.

If those five rules hold, you can swap an OrderApplicationService for three UseCase classes in an afternoon without touching the domain, the controllers, or the tests beyond their setup blocks. The two styles are swap-compatible inside the same architecture. They are not swap-compatible in everyday code review. That is the conversation worth having on your team this week.

If this was useful

The "where does this code go" question is half of what makes hexagonal and clean architecture feel hard in PHP, and naming conventions are the other half. Decoupled PHP walks the full project shape (domain, ports, application, adapters) with both architectures side by side, in PHP 8.3, with a public examples repo for each chapter. If your team has been arguing about service-versus-use-case for longer than is healthy, the book picks a side and shows the trade.

Available on Kindle, Paperback, and Hardcover. English, German, and Japanese editions out now — Portuguese and Spanish coming soon.