Object-Design on Brian Faust

A Composition Root Makes Choices Visible

Thu, 01 Sep 2022 00:00:00 +0000

Remove the ProductPrices binding from a Laravel service provider, then ask the container for QuoteProduct. Laravel refuses to construct it:

Target [App\Application\ProductPrices] is not instantiable while building
[App\Application\QuoteProduct].

Move the same lookup into QuoteProduct::execute() and construction succeeds. That can look like simplification because the constructor now says nothing. The object graph did not become simpler. Part of it moved into method code and configuration, where Laravel cannot reject it until a quote reaches that line.

A Constructor Should Leave a Usable Object

Wed, 01 Dec 2021 00:00:00 +0000

This Subscription exists before it can safely answer a question:

$subscription = new Subscription();
$subscription->id = $ids->next();
$subscription->customerId = $customerId;
$subscription->plan = $plans->get($planCode);
$subscription->status = 'trial';
$subscription->startsAt = $clock->now();
$subscription->trialEndsAt = $subscription->startsAt->modify('+14 days');

Between the first and last line, another method can observe an object without a plan, status, or start time. Forget the last assignment and an active subscription can carry a trial end. Reorder the calls and identity may be consumed for a plan which does not exist.

Strategy Chooses How; Command Records What to Do

Sun, 01 Aug 2021 00:00:00 +0000

Two PHP types can have almost identical shapes and still solve different problems:

interface ShippingRate
{
 public function quote(Shipment $shipment): Money;
}

interface ApplicationCommand
{
 public function execute(): void;
}

Both hide behavior behind a method. Both can be injected and tested. They look similar enough that “algorithm versus action” sounds like a sufficient answer. It is not, at least not for application architecture.

Wait for execution to fail and the difference becomes clearer. A strategy is a collaborator used while another operation is already in progress. A command represents work that can acquire its own lifecycle. Once that work must be queued, retried, deduplicated, authorized, or audited independently, calling it an implementation choice misses most of the problem.

Composition Over Inheritance Is a Decision, Not a Rule

Thu, 01 Jul 2021 00:00:00 +0000

“Favor composition over inheritance” is useful advice right up to the point where it becomes a reflex. Replacing every parent class with an interface and a service-container binding does not improve the design. It just exchanges one form of coupling for another, usually with more files.

What matters is how behavior is allowed to vary. Inheritance fixes variation into a type hierarchy. Composition puts it behind collaborators that can change independently. When tax, discounts, shipping, and payment rules evolve along different axes, forcing them into one family tree gets expensive. When a subtype genuinely preserves a small, stable parent contract, inheritance may be the clearest tool available. “Has-a” versus “is-a” is too shallow to decide between them.

Dependencies Should Be Visible at Construction

Mon, 01 Jun 2020 00:00:00 +0000

This line created a database record:

$user = UserFactory::new()->create([
 'external_id' => 123,
]);

It also performed an HTTP request.

The factory did not mention a client. The model did not accept one. A synchronous observer noticed the external identifier, prepared a profile export, and resolved a connector from global framework state. The connector then looked up a remote account.

In tests without a fake, that lookup reached DNS or the network and retried three times with exponential backoff. Tests which had run in under five seconds took more than thirty. The slow test was annoying, but it was only the visible symptom. A local-looking construction operation had acquired an undeclared remote dependency.

A Service Class Can Become a Procedural Junk Drawer

Fri, 01 May 2020 00:00:00 +0000

A web controller contained nearly two thousand lines of shipment creation. Moving those lines into a class described as a creation orchestrator sounded like an architectural improvement.

The new class contained nearly two thousand lines of shipment creation.

The first move was still useful. It removed the procedure from the HTTP adapter. What it did not do was make the procedure cohesive. Validation, payment gating, draft persistence, provider booking, tracking, document creation, response mapping, notifications, and indexing still changed inside one file. Service and orchestrator are roles only when the code earns those names. Otherwise they are folders for procedures we no longer want in controllers.

A Primitive Can Hide a Domain Decision

Wed, 01 Apr 2020 00:00:00 +0000

Uppercasing a country code looks like normalization:

return mb_strtoupper($input);

It makes fi and FI equal. It also turns finland into FINLAND and leaves FIN looking plausible.

The string is tidier, not safer. The function has changed its shape without answering the domain question: is this a supported country identity in the representation this boundary promises? A primitive becomes expensive when every caller must remember that answer. The reason to introduce a domain type isn’t that strings are unfashionable. It is that the scalar no longer carries enough of the contract.

Boolean Parameters Hide Different Operations

Sun, 01 Mar 2020 00:00:00 +0000

This method call is legal:

$exporter->execute($accountId, true, true);

It is also semantically wrong.

The first boolean in the exporter meant “source billing details from the effective payer.” The payload still targeted the original account and kept that account’s operational fields. The second boolean meant “the source’s billing mode is an authoritative instruction.”

An effective-payer export described who pays; it was not allowed to change the original account’s billing mode. The true, true combination therefore had to be neutralized by a later guard.

Invalid State Should Be Difficult to Construct

Sat, 01 Feb 2020 00:00:00 +0000

A wallet reservation held one amount while a booking was in progress. When the booking later reached the billing system, an imported record could contain no price. The reservation knew how much money had been held, but not how that amount divided into net price and VAT. There was no authoritative way to create the final sale from the hold alone; inferring a tax rate would turn a guess into accounting data.

A Class Name Should Describe a Role

Wed, 01 Jan 2020 00:00:00 +0000

Several classes in one application had almost the same shape. Each extended a connection manager, read named configuration, and delegated object creation to a factory. One managed payment gateways, another rating clients, and another booking clients.

The shared abstraction made their code look alike. Their callers were asking different questions.

Payment callers needed a gateway with a given name. Rating callers sometimes needed to decide which connection matched a shipment. Booking callers selected connections from different rules for creating, collecting, and cancelling, then assembled operation-specific services around the result.