Laravel's scoped(): The Singleton That Knows When to Die

Laravel's service container has a familiar method:

$this->app->singleton(MyService::class);

It means Laravel creates the service once and reuses that instance. But there is an interesting question:

What happens when your PHP application doesn't restart between requests?

That's where scoped() comes in.

---

The problem with long-running workers

With the traditional PHP request lifecycle, things look roughly like this:

Request A -> Laravel boots -> Request ends -> PHP ends
Request B -> Laravel boots -> Request ends -> PHP ends

A singleton therefore appears to live only for one request.

But long-running environments such as Laravel Octane and queue workers work differently:

Long-running worker
      |
      |-- Request A
      |-- Request B
      |-- Request C
      |-- Request D

The Laravel application stays alive, that means a singleton can also stay alive.

Imagine a service that keeps some request-specific state:

class RequestContext
{
    public ?int $userId = null;
}

If registered as a singleton:

$this->app->singleton(RequestContext::class);

Request A might do:

$context->userId = 10;

Then Request B could receive the same instance:

$context->userId; // 10

That state has crossed a request boundary.

---

Enter scoped()

Laravel provides:

$this->app->scoped(RequestContext::class);

A scoped binding behaves like a singleton inside the current lifecycle.

So during one request:

$a = app(RequestContext::class);
$b = app(RequestContext::class);

$a === $b; // true

But when the lifecycle changes, Laravel clears the scoped instance and creates a new one. Conceptually:

Request A
   |
   |-- RequestContext #1

Request B
   |
   |-- RequestContext #2

Request C
   |
   |-- RequestContext #3

Laravel documents scoped bindings specifically for this kind of lifecycle: they are resolved once per request or job lifecycle and flushed when a new lifecycle begins.

---

Singleton vs scoped

The easiest way to remember the difference is the lifetime:

Binding	Lifetime
bind()	New instance when resolved
singleton()	Same instance for the application/container
scoped()	Same instance for the current request/job lifecycle

The important distinction is between the last two.

singleton() answers:

“Should this application use the same instance?”

scoped() answers:

“Should this execution use the same instance?”

---

Laravel actually resets scoped instances

This isn't just documentation terminology, Laravel's queue worker explicitly calls forgetScopedInstances:

$app->forgetScopedInstances();

when resetting the worker between jobs.

The container also exposes forgetScopedInstances() as a dedicated operation, showing that scoped instances have their own lifecycle management.

So the next job doesn't inherit the scoped objects created by the previous one.

---

When should you use scoped()?

Use it when an object should be shared during one execution, but must not leak into the next one.

Good examples can include:

• request-specific state
• tenant-specific state
• per-job state
• objects that accumulate information while processing one operation

A useful rule is:

If the object contains state that belongs to one request or job, scoped() is often a better fit than singleton().

And this becomes particularly important when your application runs in a long-lived process.

---

At the end

scoped() isn't really about creating another kind of singleton, it's about lifetime management.

Laravel is telling the container:

Reuse this object...
        |
        v
but only while this execution is alive.

That small difference becomes extremely important once PHP stops dying after every request.