The Singleton Labyrinth

Play the game first: voku.github.io/DevLabyrinth/

It teaches the problem faster than another architecture sermon ever could.

You enter a labyrinth.

Walls. Corridors. Turns. Dead ends.

Annoying, yes.

But fair.

You can explain where you are.

You can explain how you got there.

You can walk back.

You can draw a map.

That is maintainable software.

Not perfect software.

Not "clean" software.

Maintainable software.

The boring miracle where the structure you see is the structure you actually use.

Then Someone Adds a Hole

At some point, someone adds a hole in the floor.

You step into it and land somewhere else.

Nice.

Five corridors avoided.

Three turns skipped.

No ceremony.

Fast.

Someone says:

"This is much easier."

They are right.

For now.

And that is how most bad architecture starts.

Not with evil.

With convenience.

One Shortcut Is Not the Problem

One shortcut can be fine.

One hole can be documented.

One emergency tunnel can be marked on the map.

The problem starts when every frustrated developer adds their own shortcut.

A hole near the entrance.

A tunnel near the middle.

A ladder near the exit.

A trapdoor from room C to room Q because "we needed it for that one release."

The labyrinth still works.

Technically.

But nobody navigates anymore.

They remember tricks.

"Use the green hole, then skip the ladder, then don't touch the tunnel unless staging was reset."

That is not architecture.

That is folklore with deployment access.

The Map Starts Lying

The walls are still there.

The corridors still exist.

The official path still looks normal.

But the real movement happens underground.

The map says:

"Walk from A to B."

The system says:

"Actually, we jump from A to Q through a hidden tunnel depending on what happened earlier."

Congratulations.

Your code has two architectures now.

The visible one.

And the real one.

Guess which one breaks production.

This Is Where Bugs Become Archaeology

A user lands in the wrong room.

The corridor says impossible.

The wall says impossible.

The map says impossible.

But it happened.

So now you are not debugging the visible path anymore.

You are inspecting holes.

Where does this shortcut lead?

Who changed it?

Was it initialized?

Did a previous request mutate it?

Did a test forget to reset it?

Did someone patch it in 2019 and leave the company?

Beautiful.

We invented archaeology with syntax.

Now Call the Holes Singletons

A Singleton often starts exactly like that first hole.

Database::instance()

Looks useful.

No constructor.

No dependency wiring.

No container setup.

No passing objects around like an adult.

Just grab the thing from anywhere.

That is the hole in the floor.

One call is harmless.

Ten calls are convenient.

A hundred calls are architecture.

Bad architecture.

But architecture.

The Code Lies to Your Face

Look at this:

<?php

declare(strict_types=1);

final readonly class UserReportService
{
    /**
     * @return list<array{id: int, email: string}>
     */
    public function activeUsers(): array
    {
        return Database::instance()->fetchAll(
            'SELECT id, email FROM users WHERE active = 1'
        );
    }
}

Cute.

Looks dependency-free.

It is not.

It depends on:

• a database connection
• a concrete database wrapper
• global configuration
• initialization order
• hidden mutable state
• whatever the previous code did to Database::instance()

The constructor says nothing.

The method signature says nothing.

The class smiles at you like it is simple.

It is not simple.

It is hiding the body under the floorboards.

The Problem Is Not "One Instance"

This is where most Singleton articles become useless.

They scream:

"Singletons are evil!"

Great. Very brave. Very 2009.

The problem is not automatically that only one instance exists.

One instance can be fine.

The real problem is global reachability.

Any code can grab it.

Any code can mutate it.

Any code can depend on it without telling you.

That destroys locality.

And locality is the entire game.

You want to understand this class?

Too bad.

You now need to understand the class, the Singleton, the boot order, the test setup, the previous request, and some ancient static method named initLegacyMode().

Enjoy your afternoon.

Tell the Truth Instead

This code tells the truth:

<?php

declare(strict_types=1);

interface UserRepository
{
    /**
     * @return list<array{id: int, email: string}>
     */
    public function findActiveUsers(): array;
}

final readonly class UserReportService
{
    public function __construct(
        private UserRepository $userRepository,
    ) {
    }

    /**
     * @return list<array{id: int, email: string}>
     */
    public function activeUsers(): array
    {
        return $this->userRepository->findActiveUsers();
    }
}

Now we know what the class needs.

No magic.

No tunnel.

No "trust me bro" dependency.

Tests can pass a fake repository.

Production can pass the real one.

The path is visible again.

That is the point.

Not purity.

Visibility.

The Singleton Smell Test

A Singleton becomes dangerous when it:

• can be called from anywhere
• hides a dependency
• stores mutable state
• changes after initialization
• depends on the current request
• depends on the current user
• depends on the current tenant
• needs reset methods in tests
• makes behavior depend on call order

That last one is the killer.

Because now your code is no longer just code.

It is a ritual.

Call this first.

Then this.

Never that.

Unless CLI.

Unless tests.

Unless worker mode.

Unless Tuesday.

This is not engineering.

This is software necromancy.

The Worst Singletons

Some Singletons are merely annoying.

A global formatter? Bad smell.

A global database? Worse.

A global current user?

Now we are cooking garbage.

CurrentUser::instance()->id();
TenantContext::instance()->tenantId();
RequestContext::instance()->locale();

This is how request-specific state leaks into business logic.

Now your domain code secretly knows about HTTP.

Your CLI command needs a fake user.

Your queue worker leaks tenant state.

Your tests need global cleanup.

Your production bugs depend on what happened before.

Amazing.

You saved one constructor argument and bought yourself a haunted house.

But Shared Instances Are Not Evil

Do not be childish about this.

A shared instance can be fine.

This is fine:

<?php

declare(strict_types=1);

final readonly class AppConfig
{
    /**
     * @param non-empty-string $environment
     * @param non-empty-string $databaseDsn
     */
    public function __construct(
        public string $environment,
        public string $databaseDsn,
    ) {
    }
}

One config object per application boot?

Fine.

It is immutable.

It is lifecycle-owned.

It does not depend on the current user.

It does not remember the last request.

It does not mutate because someone opened another browser tab.

That is not a trapdoor.

That is a signpost.

Containers Are Not the Same Thing

A dependency injection container may reuse one service instance.

That does not make it the same mess.

This is fine:

<?php

declare(strict_types=1);

final readonly class Mailer
{
    public function __construct(
        private Transport $transport,
    ) {
    }
}

The container may share Mailer.

Who cares?

The class does not provide global access to itself.

The dependency is still visible.

Compare that with this:

Mailer::instance()->send($message);

The first version says:

"This object needs a mailer."

The second says:

"There is a hole in the floor. Jump."

No.

The Rule

Before adding global access, ask:

Would this still be correct if two users, two tenants, two jobs, or two tests touched it at the same time?

If not, stop.

Then ask:

Does passing this dependency explicitly actually make the code worse?

Usually, no.

It just makes the truth visible.

And developers hate visible complexity because it ruins the fantasy that the system is simple.

Bad news:

The complexity was already there.

You just hid it under ::instance().

Legacy Code: Do Not Start a War

If your codebase already has Singletons, do not run through the office yelling about global state.

Nobody cares.

Also, you will lose.

Start smaller.

Stop adding new holes.

Move old Singleton access toward the edges.

Keep infrastructure dirty if needed.

Keep new domain code clean.

This:

<?php

declare(strict_types=1);

final readonly class InvoiceService
{
    public function __construct(
        private InvoiceRepository $invoiceRepository,
        private Clock $clock,
    ) {
    }
}

Not this:

<?php

declare(strict_types=1);

final class InvoiceService
{
    public function createInvoice(): void
    {
        $now = Clock::instance()->now();
        $database = Database::instance();
    }
}

The first has corridors.

The second has trapdoors.

Refactor Like a Mechanic, Not a Prophet

Do not rewrite everything.

Do not "fix the architecture" in one heroic pull request.

That is how teams create new disasters with better naming.

Wrap the old mess.

<?php

declare(strict_types=1);

interface Clock
{
    public function now(): DateTimeImmutable;
}

final readonly class LegacyClockAdapter implements Clock
{
    public function now(): DateTimeImmutable
    {
        return LegacyClock::instance()->now();
    }
}

Now new code depends on Clock.

Old code can keep limping along.

You built a corridor around the trapdoor.

That is progress.

Not glamorous.

Useful.

The best kind.

The Real Lesson

A Singleton is not bad because it creates one object.

A Singleton is bad because it often creates hidden paths.

One controlled shortcut can help.

A labyrinth full of shortcuts becomes impossible to reason about.

The code still runs.

But nobody can explain why.

And when nobody can explain why, every change becomes risky.

That is the cost.

Not the pattern.

Not the theory.

The lost map.

Summary

Singletons are not automatically evil.

Hidden global access is the real problem.

A shared immutable object can be fine.

A globally reachable mutable dependency is usually a trap.

The question is not:

"Is this a Singleton?"

The question is:

"Does this keep the map honest?"

If not, fill the hole.

No new trapdoors.

Visible dependencies.

Boring code.

Maintainable software.

That is the exit.