Object-Oriented-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. Calling all of them “the order model” does not simplify anything. It makes a design conversation 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?

Answer those questions first. The labels come afterward.

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.

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.

Forget counting arrows. The useful part of the Law of Demeter is keeping structural knowledge near the object or module that owns the structure. A fluent query builder can have a long chain without crossing a boundary; one innocent getter can expose an object the caller has no business navigating. The question is who should know how to reach the value or perform the action, not how many dots the expression contains.

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. That is fine once. The mess starts when an API controller, an import command, and an admin action each reproduce the sequence with slightly different conditions.

“Tell, don’t ask” helps when it moves a decision back to the object that owns the relevant state. Turning it into a ban on getters, queries, or conditional logic misses the point. The problem is asking an object for its internals so somebody else 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. 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.

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 constructor is cleaner, but the direction is still wrong. The application use case knows an HTTP client, carrier endpoint, payload, response shape, and currency assumption. Moving new Client() into the container made assembly easier. It did nothing to keep carrier details out of application policy.

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. It is the provider’s feature catalogue pretending to be a client role.

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 type checker did its job; it just was not the whole job.

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, and method count is a lazy proxy for it.