Introduce Parameter Object: A Refactoring Pattern That Scales

Source: Dev.to

Introduction

There is one refactoring pattern I apply regularly that rarely gets the attention it deserves. It does not look impressive, yet it prevents codebases from slowly collapsing under their own weight.

The Problem: Long Parameter Lists

You have definitely seen a method signature like this:

public function createInvoice(
    int $customerId,
    string $currency,
    float $netAmount,
    float $taxRate,
    string $country,
    bool $isReverseCharge,
    ?string $discountCode,
    DateTime $issueDate
): Invoice

At first it works fine, but as business requirements grow the call sites become fragile. A long parameter list is not just an aesthetic problem; in practice it causes:

• Hard‑to‑read method calls
• High cognitive load during code reviews
• Frequent parameter‑misordering bugs
• Changes that ripple through dozens of call sites
• Fear‑driven refactoring (“don’t touch it” syndrome)

Most importantly, it hides implicit relationships between parameters. When several parameters are always passed together, represent a single domain idea, and change for the same business reasons, the signature fails to express the domain language clearly.

Introducing the Parameter Object

The pattern is not merely about reducing the number of arguments; it is about grouping related data into a meaningful object.

Example Groupings

// Tax‑related data
float $netAmount,
float $taxRate,
bool  $isReverseCharge,
string $country

// Pricing context
string $currency,
?string $discountCode

Small, Focused Objects

class TaxContext
{
    public function __construct(
        public float $netAmount,
        public float $taxRate,
        public bool $isReverseCharge,
        public string $country
    ) {}
}

class PricingContext
{
    public function __construct(
        public string $currency,
        public ?string $discountCode
    ) {}
}

Before → After

Before

public function createInvoice(
    int $customerId,
    string $currency,
    float $netAmount,
    float $taxRate,
    string $country,
    bool $isReverseCharge,
    ?string $discountCode,
    DateTime $issueDate
): Invoice

After

public function createInvoice(
    int $customerId,
    PricingContext $pricing,
    TaxContext $tax,
    DateTime $issueDate
): Invoice

The behavior does not change; only the interface becomes clearer.

Benefits

1. Readable Calls

Before

$service->createInvoice(
    $customerId,
    'EUR',
    1000,
    0.21,
    'DE',
    false,
    null,
    new DateTime()
);

After

$pricing = new PricingContext('EUR', null);
$tax = new TaxContext(1000, 0.21, false, 'DE');

$service->createInvoice(
    $customerId,
    $pricing,
    $tax,
    new DateTime()
);

No need to decode parameter positions.

2. Localized Future Changes

When a new tax‑related requirement appears, you only extend TaxContext:

class TaxContext
{
    public function __construct(
        public float $netAmount,
        public float $taxRate,
        public bool $isReverseCharge,
        public string $country,
        public ?string $vatId = null
    ) {}
}

The method signature remains unchanged.

3. Validation and Behavior Near the Data

class TaxContext
{
    public function isTaxApplicable(): bool
    {
        return !$this->isReverseCharge && $this->taxRate > 0;
    }
}

Encapsulating logic with the data lets the pattern pay compound interest over time.

When to Apply

• Three or more parameters already form a meaningful domain concept.
• The same group of arguments appears across multiple call sites.
• A single business change affects several parameters at once.

The exact number is less important than the signal that the code struggles to express intent through its interface.

Pitfalls & Tips

1. Avoid “dumb bags of data.” If the object never gains behavior, you missed part of the value.
2. Refactor incrementally. Start with one method; this is not a big‑bang change.
3. Ensure the object can answer domain questions. A Parameter Object that never gains behavior often indicates an incomplete refactoring.

Conclusion

Introducing a Parameter Object is not flashy, but it quietly improves:

• Readability
• Maintainability
• Change resilience
• Developer confidence

In mature codebases, these are the refactorings that matter most.

What’s Next?

In upcoming articles I will explore other “quiet” refactoring patterns, such as:

• Refactoring temporal coupling
• Extracting domain‑specific query objects
• Moving validation logic into domain concepts

Small changes, long‑term impact.