A young adventurer enters a village before facing the guardian of the northern gate. Three locations offer different services: the blacksmith can strengthen weapons, the healer can restore health, and the merchant can provide gold for supplies.
Each location is a different kind of object, but the hero must interact with all of them. Later, the game may introduce inspectors, collectors or special event characters that perform completely different operations on the same locations.
The Visitor design pattern offers a way to separate operations from the objects they operate on. Instead of placing every possible behavior inside each location class, visitors implement the operations externally.
The problem: new operations across existing objects
Imagine a village with Forge, Clinic and Market classes. Each contains data relevant to its service. A player interacts with these locations to gain attack power, health or currency.
Now imagine adding a traveling inspector who calculates the economic value of each location. Without a suitable design, developers might add inspection methods to every location class, even though inspection is not part of the location’s essential responsibility.
Visitor moves these operations into separate classes. The locations expose a stable accept() method, while visitors provide type-specific behavior.
The village’s three locations
Our game includes a Forge containing two units of ore, a Clinic containing two medicinal herbs and a Market holding fifteen gold coins. The hero begins with five attack points and twelve health points.
Visiting the Forge increases attack strength. Visiting the Clinic restores health, up to a maximum of twenty. Visiting the Market collects gold. After completing these visits, the hero fights a guardian with fourteen health points.
A working PHP 8.2+ game
Save the following program as visitor-rpg.php. It uses readonly location objects, two interfaces and a concrete Adventurer visitor. No Composer dependencies are required.
<?php
declare(strict_types=1);
interface VillageVisitor
{
public function visitForge(Forge $place): void;
public function visitClinic(Clinic $place): void;
public function visitMarket(Market $place): void;
}
interface VillagePlace
{
public function accept(
VillageVisitor $visitor
): void;
}
final readonly class Forge implements VillagePlace
{
public function __construct(
public int $ore
) {}
public function accept(
VillageVisitor $visitor
): void {
$visitor->visitForge($this);
}
}
final readonly class Clinic implements VillagePlace
{
public function __construct(
public int $herbs
) {}
public function accept(
VillageVisitor $visitor
): void {
$visitor->visitClinic($this);
}
}
final readonly class Market implements VillagePlace
{
public function __construct(
public int $coins
) {}
public function accept(
VillageVisitor $visitor
): void {
$visitor->visitMarket($this);
}
}
final class Adventurer implements VillageVisitor
{
private int $attack = 5;
private int $health = 12;
private int $gold = 0;
public function visitForge(Forge $place): void
{
$this->attack += $place->ore * 2;
echo "Forge: attack {$this->attack}\n";
}
public function visitClinic(Clinic $place): void
{
$this->health = min(
20,
$this->health + $place->herbs * 3
);
echo "Clinic: health {$this->health}\n";
}
public function visitMarket(Market $place): void
{
$this->gold += $place->coins;
echo "Market: gold {$this->gold}\n";
}
public function fight(): void
{
$guardian = 14;
while ($guardian > 0) {
$guardian = max(
0,
$guardian - $this->attack
);
echo "Guardian HP: {$guardian}\n";
}
echo "Victory! HP {$this->health}, "
. "gold {$this->gold}\n";
}
}
$places = [
new Forge(2),
new Clinic(2),
new Market(15),
];
$hero = new Adventurer();
foreach ($places as $place) {
$place->accept($hero);
}
$hero->fight();Run the village quest
php visitor-rpg.phpThe Forge increases the hero’s attack power from five to nine. The Clinic restores health from twelve to eighteen. The Market adds fifteen gold coins. The guardian then falls after two attacks.
Understanding double dispatch
The central mechanism is the accept() method. When a Forge receives a visitor, it calls visitForge($this). A Clinic calls visitClinic($this), and a Market calls visitMarket($this).
This is known as double dispatch. The selected operation depends on the concrete location and the visitor’s implementation. The caller can treat all locations as VillagePlace objects without manually checking each type through instanceof.
Adding another visitor
Suppose the game introduces an inspector who records the value of village resources. A new Inspector class could implement VillageVisitor with separate calculations for Forge, Clinic and Market. The three existing location classes would not need new inspection methods.
This is the main advantage of Visitor: adding new operations over a stable set of element types is relatively straightforward. It is particularly useful for compilers, syntax trees, document processing and other structures where many operations apply to the same kinds of objects.
The tradeoff: adding new location types
Visitor has an important limitation. Adding a new location, such as a Library, requires adding a visitLibrary() method to the visitor interface and implementing it in every existing visitor. That can be expensive when many visitors already exist.
The pattern therefore works best when the collection of element types changes infrequently, but the operations performed on those elements change regularly.
Reader challenge: The Tax Collector
Create a TaxCollector visitor that calculates a tax value for each location without changing Forge, Clinic or Market. Then add a second visitor that produces a text report describing the village economy.
Finally, consider adding a fourth location and observe how many interfaces and classes must change. This exercise demonstrates both the strength and the cost of Visitor.
In our village, the locations define what they are, while visitors define what happens when someone interacts with them. That separation is the essence of the Visitor pattern—and a useful technique when a stable object structure must support many different operations.

























