Object Design on Brian Faust

Entity, Value Object, Aggregate, Model, DTO: Name the Role

Sat, 01 Jan 2022 00:00:00 +0000

An Order can be an Eloquent model, a domain entity, an aggregate root, an API resource, and a row in a database. Those statements describe different roles. Treating them as synonyms makes design conversations sound precise while each person is discussing a different boundary.

DDD’s modelling vocabulary becomes useful through concrete questions:

Does this thing remain the same when its attributes change?
Is equality based on identity or on all constituent values?
Which rules must be consistent before one transaction commits?
Is this shape for domain behavior, persistence, or transfer?

The labels follow those answers.

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.

Adding a factory does not automatically repair this. Neither does replacing new Subscription() with Subscription::create(). The useful question is which boundary owns each decision.

A Null Object Should Mean Nothing Happened

Mon, 01 Nov 2021 00:00:00 +0000

A missing coupon is not an error. Checkout should continue, the discount should be zero, and callers should not care whether a coupon was supplied.

A missing payment gateway is different. Pretending that a charge succeeded would corrupt the order workflow. Even doing nothing would turn a deployment mistake into a plausible-looking transaction.

Both dependencies can be typed as nullable, but only one has an honest neutral behavior. That is the boundary for the Null Object pattern: use it when absence means “perform the same operation with no effect,” not whenever an if statement looks untidy.

The Law of Demeter Is About Knowledge, Not Dots

Fri, 01 Oct 2021 00:00:00 +0000

$order->customer->primaryAddress->city looks harmless. It may even execute the right number of queries. The problem appears six months later, when an order can have several delivery destinations and every caller has encoded the old path to a city.

This is the useful part of the Law of Demeter: keep structural knowledge near the object or module that owns the structure. Counting arrows is a poor substitute for that reasoning. A fluent query builder can have a long chain without crossing a boundary; a single getter can expose an object that the caller has no business navigating.

Tell, Don't Ask Means Keep the Decision with the State

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

This controller looks reasonable:

if ($order->status === OrderStatus::Draft && $order->lines->isNotEmpty()) {
 $order->status = OrderStatus::Placed;
 $order->placed_at = now();
 $order->save();
}

It reads state, makes a decision, mutates more state, and persists the result. The problem begins when an API controller, an import command, and an admin action each reproduce that sequence with slightly different conditions.

“Tell, don’t ask” is useful when it moves a decision back to the object that owns the relevant state. It is not a ban on queries, getters, or conditional logic. The smell is asking an object for its internals so another object can enforce its rules.

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. Their surface similarity makes “algorithm versus action” an easy first distinction, but it is not enough for application architecture.

The more useful distinction appears after execution fails. A strategy is a collaborator used while another operation is already in progress. A command represents work that can acquire its own lifecycle. Once work must be queued, retried, deduplicated, authorized, or audited independently, it is no longer merely a choice of implementation.

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 make a design better. It merely exchanges one form of coupling for another.

The decision is about how behavior is allowed to vary.

Inheritance fixes variation into a type hierarchy. Composition puts variation behind collaborators that can change independently. When tax, discounts, shipping, and payment rules evolve along different axes, forcing them into one family tree is expensive. When a subtype genuinely preserves a small, stable parent contract, inheritance may be the clearest tool available.

Dependency Inversion Lets Policy Own the Boundary

Tue, 01 Jun 2021 00:00:00 +0000

This class uses constructor injection and still points in the wrong direction:

final readonly class QuoteShipment
{
 public function __construct(private GuzzleHttp\Client $http) {}

 public function handle(Shipment $shipment): Money
 {
 $response = $this->http->post('/carrier/rates', [
 'json' => CarrierPayload::fromShipment($shipment),
 ]);

 return Money::EUR(
 json_decode($response->getBody(), true)['price_cents'],
 );
 }
}

The dependency is visible and testable, but the application use case knows an HTTP client, carrier endpoint, payload, response shape, and currency assumption. Replacing new Client() with an injected client improved assembly; it did not protect policy from the detail.

Interfaces Belong to Their Clients

Sat, 01 May 2021 00:00:00 +0000

A carrier integration often begins with one generous interface:

interface Carrier
{
 public function quote(Shipment $shipment): ShippingQuote;
 public function buyLabel(Shipment $shipment): Label;
 public function cancelLabel(LabelId $labelId): void;
 public function track(TrackingNumber $number): TrackingStatus;
 public function bookPickup(PickupRequest $request): Pickup;
 public function closeManifest(LocalDate $date): Manifest;
}

The checkout page needs only quote(). A tracking job needs only track(). One carrier may not support pickups; another may not use manifests. The broad interface makes every consumer and implementation participate in capabilities they do not share.

The Interface Segregation Principle asks for client-specific contracts. It does not demand one method per interface. Split where clients, implementations, or change reasons diverge.

Substitution Is a Behavioral Contract

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

Both of these classes implement the same interface:

interface InvoiceArchive
{
 public function store(InvoiceId $id, PdfDocument $document): Location;
 public function read(Location $location): PdfDocument;
}

final class NullInvoiceArchive implements InvoiceArchive
{
 public function store(InvoiceId $id, PdfDocument $document): Location
 {
 return Location::from("memory://{$id->value}.pdf");
 }

 public function read(Location $location): PdfDocument
 {
 throw new RuntimeException('Nothing was stored.');
 }
}

PHP accepts the implementation. A client that stores a document and later reads the returned location does not. The method signatures match while the behavioral contract is broken.

The Liskov Substitution Principle is about that gap. Code written against a supertype must continue to work when it receives any subtype. Interfaces, inheritance, fakes, decorators, and adapters all create subtype promises; the principle is not limited to class hierarchies.

Open–Closed Protects Stable Policy from Repeated Variation

Mon, 01 Mar 2021 00:00:00 +0000

The third shipping carrier usually exposes the design more clearly than the first.

With one carrier, a conditional is honest. With three, adding a carrier may require editing quote calculation, label purchase, tracking links, validation, service-provider bindings, and tests. The same variation keeps reopening code that was already working.

The Open–Closed Principle addresses that pattern: establish a stable policy that is closed to this recurring modification while new variants arrive through an explicit extension point. It does not say existing code must never change. It says repeated variation should stop causing shotgun surgery.

Single Responsibility Is About Change, Not Class Size

Mon, 01 Feb 2021 00:00:00 +0000

A class with one public method can still mix pricing policy, PDF layout, storage, and email delivery:

final class SendInvoice
{
 public function handle(Order $order): void
 {
 $tax = $order->subtotal * config('billing.tax_rate');
 $pdf = Pdf::html(view('invoice', compact('order', 'tax'))->render());
 Storage::disk('invoices')->put("{$order->id}.pdf", $pdf);
 Mail::to($order->customer)->send(new InvoiceMail($pdf));
 }
}

Its method count is one. Its reasons to change include tax rules, document presentation, retention, storage infrastructure, and delivery policy. “Do one thing” is too vague to expose that coupling.

The Single Responsibility Principle is more useful as a change rule: group code that changes for the same reason and separate code that changes for different reasons. Robert Martin’s clarification of SRP connects those reasons to the people or business functions requesting them.