Long parameter list: introduce a parameter object
Group the values that travel together, so a new one stops touching every signature.
Watch the narrated video
Every step
Problem
Steps 1–4Refactor
Steps 5–9Payoff
Steps 10–11PHP bonus
Steps 12–13Recap
Steps 14–15The code: before and after
Before
final class ShippingService
{
public function __construct(private RateTable $rates) {}
public function quote(string $fromPostal, string $fromCountry,
string $toPostal, string $toCountry, float $weightKg,
float $lengthCm, float $widthCm, float $heightCm,
bool $express): Quote
{
$price = $this->price($fromCountry, $toCountry, $weightKg,
$lengthCm, $widthCm, $heightCm, $express);
return new Quote($fromPostal, $toPostal, $price);
}
private function price(string $fromCountry, string $toCountry,
float $weightKg, float $lengthCm, float $widthCm,
float $heightCm, bool $express): float
{
$volumetricKg = $lengthCm * $widthCm * $heightCm / 5000;
$cost = $this->rates->perKg($fromCountry, $toCountry)
* max($weightKg, $volumetricKg);
return $express ? $cost * 1.5 : $cost;
}
}
final class Checkout
{
private const WAREHOUSE_POSTAL = '10115';
private const WAREHOUSE_COUNTRY = 'DE';
public function __construct(private ShippingService $shipping) {}
public function shippingFor(Cart $cart, Customer $customer): Quote
{
return $this->shipping->quote(self::WAREHOUSE_POSTAL,
self::WAREHOUSE_COUNTRY, $customer->postalCode,
$customer->country, $cart->weightKg, $cart->lengthCm,
$cart->widthCm, $cart->heightCm,
$cart->express);
}
}After
final readonly class Address
{
public function __construct(public string $postal,
public string $country) {}
}
final readonly class Parcel
{
public function __construct(public float $weightKg,
public float $lengthCm, public float $widthCm,
public float $heightCm, public bool $fragile) {}
public function billableKg(): float
{
$volumetricKg = $this->lengthCm * $this->widthCm
* $this->heightCm / 5000;
return max($this->weightKg, $volumetricKg);
}
}
final class ShippingService
{
public function __construct(private RateTable $rates) {}
public function quote(Address $from, Address $to, Parcel $parcel,
bool $express): Quote
{
$price = $this->price($from, $to, $parcel, $express);
return new Quote($from->postal, $to->postal, $price);
}
private function price(Address $from, Address $to, Parcel $parcel,
bool $express): float
{
$cost = $this->rates->perKg($from->country, $to->country)
* $parcel->billableKg();
$cost *= $parcel->fragile ? 1.2 : 1.0;
return $express ? $cost * 1.5 : $cost;
}
}
final class Checkout
{
private const WAREHOUSE_POSTAL = '10115';
private const WAREHOUSE_COUNTRY = 'DE';
public function __construct(private ShippingService $shipping) {}
public function shippingFor(Cart $cart, Customer $customer): Quote
{
$from = new Address(self::WAREHOUSE_POSTAL, self::WAREHOUSE_COUNTRY);
$to = new Address($customer->postalCode, $customer->country);
$parcel = new Parcel(
weightKg: $cart->weightKg,
lengthCm: $cart->lengthCm,
widthCm: $cart->widthCm,
heightCm: $cart->heightCm,
fragile: $cart->fragile,
);
return $this->shipping->quote($from, $to, $parcel,
express: $cart->express);
}
}Transcript, step by step
Problem
Step 1: A quote with nine parameters Before
At checkout, this method asks the shipping service for a quote. It passes the warehouse address from two constants, then the customer's address, then five values from the cart. The quote method takes all nine, and hands seven of them on to the price method. Price works out a volumetric weight from the box size, charges for whichever weight is larger, and adds half again for express.
Step 2: One flag, five edits Code smell
The carrier now charges twenty percent more for fragile parcels. Price needs a fragile flag, so the quote method, the call inside it and the checkout call all have to carry one there. A long parameter list is a method that takes so many values that every caller must line them up in the right order. You can see it here in the quote signature, here in the price signature, here in the call inside quote, and here in the checkout call. Quote uses two of its ten values itself, and the other eight pass straight through to price.
Step 3: Two booleans side by side Code smell
One new value cost four edits to signatures and calls before we reached the one line that uses it. And now express and fragile sit side by side as two booleans in every list. If someone swaps them, the types still match, and the customer pays the wrong surcharge.
Step 4: Back it out, then group Plan
Let's back that change out and refactor first. Look at which values travel together, because the same groups show up in every list. The origin postal code and country always come as a pair, so do the destination's, and so do the weight and the three box sizes. A group like that is called a data clump, and Introduce Parameter Object turns each clump into one small type. We'll do it one clump at a time, and after each step PHPStan passes and the price comes out the same.
Refactor
Step 5: The origin becomes an Address Introduce Parameter Object
The origin comes first, so we add an Address class with a postal code and a country. Quote and price now take one Address called from, where they took two strings. Quote reads the postal code from it, and price reads the country. Checkout builds that address from the two warehouse constants.
Step 6: The destination is an Address too Introduce Parameter Object
The destination is the same kind of clump, so it reuses the same Address type. Both methods take from and to now, and the quote reads both postal codes off them. Checkout builds the second address from the customer.
Step 7: Four floats become a Parcel Introduce Parameter Object
The last clump is the weight and the three box sizes, so they become a Parcel class. Four floats leave both signatures, and quote takes four parameters where it took nine. Checkout builds the parcel from the cart, next to the two addresses. Price now reaches into the parcel four times to work out the weight it charges for.
Step 8: Name the weight rule Extract Method
That weight rule deserves a name, so we extract it into a method called billable kg. Price multiplies the rate by billable kg, and no longer cares how that weight is worked out. But the new method reads four values from the parcel and nothing from the shipping service.
Step 9: The rule moves onto Parcel Move Method
So it moves onto Parcel, where those four values live. Inside the class it reads its own properties, and price asks the parcel for its billable weight. Quote and price take four parameters each now, and the call between them fits on one line.
Payoff
Step 10: Fragile, in three edits Payoff
Now the fragile surcharge goes back in. Fragile is a fact about the parcel, so it becomes one more property on Parcel. Checkout passes the cart's flag where it builds the parcel, and price adds the surcharge, so that's three edits, each where the value is made or used. The quote signature, the price signature and the call inside quote didn't change.
Step 11: Why the clumps paid off Payoff
Each data clump is one type now, so a new fact about the parcel joins Parcel, and quote, which only passes values on, stays the same. And the two booleans no longer sit side by side, because express is a parameter and fragile lives inside the parcel. Passing the whole cart and customer would look shorter, but the origin is warehouse constants, and the shipping service would then depend on checkout's types. Two addresses can still be swapped, though, and the parcel's floats still go into its constructor by position.
PHP bonus
Step 12: Values by position PHP bonus
Checkout still builds the parcel from four floats and a flag that go in by position. Swap the weight and the length, and the types still match, so nothing complains and the price comes out wrong. The express flag at the end of the quote call is a bare boolean too. PHP eight has named arguments, so a call can put the parameter's name next to each value.
Step 13: Name the arguments PHP bonus
Checkout now names every value it hands to Parcel, so a swap shows up right on the line. The express flag gets its name too, where the call used to end in a lone true or false. PHPStan rejects a name the constructor doesn't have, so a typo fails the check before it runs. Names are optional, though, so PHP still accepts a call by position, and the next lesson on domain types turns a swap into a type error.
Recap
Step 14: Where we started, where we ended Before / after
On the left, quote took nine parameters and handed seven of them on to price. Two country strings, four floats and a boolean sat in a row, and any two of the floats could trade places without PHPStan noticing. On the right, two small readonly classes hold the clumps, and the weight rule lives in the parcel. Quote and price take four parameters each, and fragile is already in.
Step 15: When to reach for it Takeaways
Reach for a parameter object when the same group of values goes through several methods in the same order. Skip it for a method with a few unrelated values, like a log call with a level, a message and an error, because a wrapper would group things that don't belong together. You'll spot it by the same names repeated across signatures, long runs of floats or strings, and methods that only pass their parameters on. PHP's date classes already work this way, so diff takes one Date Time Immutable where mktime took six numbers.