[RFC] Context Managers

ср, 5 нояб. 2025 г., 09:42 Edmond Dantes [email protected]:

Hello.

Thank you for the RFC.
An excellent tool for a language that supports interfaces.

--
Ed

Hi, Larry!

Have you considered returning enum instead of ?bool? It would have a clear
self explanatory meaning.

—

Valentin

Hi Paul,

3. In the implementation code there is a lot of mention of "list" and zend_list .. why? Maybe the answer is obvious but I can't see, at first glance, why we are implementing list under the hood.

zend_list.h is the API for managing resources in core.

Best Regards,
Arnaud

Out of curiosity, what happens if GOTO is used inside a context block
to jump away from it?

I don't think this is crazy enough. I'm curious what is supposed to
happen if you goto into one!

Btw is the naming clash with global functions real? I've seen some
with() helpers here or there but you can't use a function in a
with($something) {} and you can't use the new control structure as a
callable, so where's the ambiguity requiring to make the keywordd
reserved?

BR,
Juris

break and continue are interesting keywords. (In the "may you live in interesting times" sense.) Sometimes they have the same effect, if a control structure is non-looping. Or they may have different effects in case it is. The main non-looping case is switch, where for reasons that were before my time the decision was made to deprecate continue in favor of just supporting break. However, blocking it entirely is a problem, because that would change where continue 2 would go (as switch would be removed as a "level" that it could go to). It is kind of a mess.

Nikita's original proposal was indeed to ban continue targeting switch:
https://wiki.php.net/rfc/continue_on_switch_deprecation

That doesn't mean any targets would get re-numbered, it just means that
the case which currently raises a Warning would have thrown an Error.

It was talked down to a Warning during discussion:
https://externals.io/message/102393 That was partly about backwards
compatibility, which doesn't apply here, so I personally think either
Warning or Error would be fine.

--
Rowan Tommins
[IMSoP]

Out of curiosity, what happens if GOTO is used inside a context
block to jump away from it?

That would be a success case, just like break or return. Basically
anything other than an exception is a success case. (That said,
please don't use Goto. :-) )

I do think you might need special attention to this case, as jumping out
of loops (such as foreach) needs to be handled with care.

And now the big one... also in off-list discussion, Seifeddine noted
that Laravel already defines a global function named with:
https://github.com/laravel/framework/blob/12.x/src/Illuminate/Support/helpers.php#L510

And since this RFC would require with to be a semi-reserved keyword
at the parser/token level, that creates a conflict. (This would be
true even if it was namespaced, although Laravel is definitely Doing
It Wrong(tm) by using an unnamespaced function.) Rendering all
Laravel deployments incompatible with PHP 8.6 until it makes a
breaking API change would be... not good for the ecosystem.

PHP owns the top level namespace. That's been the going for as long as I
can remember. It was unwise for Laravel to flaunt that rule.

1. Java uses a parenthetical block on try for similar functionality
   (though without a separate context manager). That would look like:

try (new Foo() as $foo) {
// ...
}
// catch and finally become optional if there is a context.

…

2. Either use or using. The semantics here would be identical to
   the current with proposal.

IMO, the try syntax is more confusing than another overload of use.

cheers,
Derick

I don't like that design, which effectively forces you to put safety
checks for all but the simplest cases onto the ContextManager
implementation.
And it forces the user to recognize "this returned object
DatabaseTranscation actually implements ContextManager, thus I should
put it into with() and not immediately call methods on it". (A problem
which the use() proposal from Tim does not have by design.)

I think you may have missed the key distinction between a "Context
Manager" (as designed by Python) and a "Disposable" (as used in C# and
others): the Context Manager is not the resource itself, it exists only
to meet the protocol/interface.

In this code:

with ( $dbConnection->transaction() as $handle ) {
   $handle->execute('I am in the transaction');
}

$handle is not the value returned by $dbConnection->transaction(),
it's the value returned by $dbConnection->transaction()->enterContext().

One of the things that means is that if you just write
$foo=$dbConnection->transaction() you can't accidentally run any methods
on $foo, if all it has is enterContext and exitContext.

It also means you can trivially wrap values that have no idea about
context managers, without needing a load of extra proxy code; it's why
the RFC can include implicit handling for resources; and why the
generator example in the Future Scope section works.

--
Rowan Tommins
[IMSoP]

The choice of adding the exception to the exitContext() is
interesting, but also very opinionated:

• It means, that the only way to abort, in non-exceptional cases, is
  to throw yourself an exception. And put a try/catch around the with()
  {} block. Or manually use enterContext() & exitContext() - with a fake
  "new Exception" essentially.
• Maybe you want to hold a transaction, but just ensure that
  everything gets executed together (i.e. atomicity), but not care about
  whether everything actually went through (i.e. not force a rollback on
  exception). You'll now have to catch the exception, store it to a
  variable, use break and check for the exception after the with block.
  Or, yes, manually using enterContext() and exitContext().

The Context Manager is given knowledge of the exception, but it's not
obliged to change its behaviour based on that knowledge. I don't think
that makes the interface opinionated, it makes it extremely flexible.

It means you can write this, which is impossible in a destructor:

function exitContext(?Throwable $exception) {
    if ( $exception === null ) {
        $this->commit();
    } else {
        $this->rollback();
    }
}

But you could also write any of these, which are exactly the same as
they would be in __destruct():

// Rollback unless explicitly committed
function exitContext(?Throwable $exception) {
    if ( ! $this->isCommitted ) {
        $this->rollback();
    }
}

// Expect explicit commit or rollback, but roll back as a safety net
function exitContext(?Throwable $exception) {
    if ( ! $this->isCommitted && ! $this->isRolledBack ) {
        $this->logger->warn('Transaction went out of scope without
explicit rollback, rolling back now.');
        $this->rollback();
    }
}

// User can choose at any time which action will be taken on destruct / exit
function exitContext(?Throwable $exception) {
    if ( $this->shouldCommitOnExit ) {
        $this->commit();
    } else {
        $this->rollback();
    }
}

You could also combine different approaches, using the exception as an
extra signal only if the user hasn't chosen explicitly:

function exitContext(?Throwable $exception) {
    if ($this->isCommitted || $this->isRolledBack) {
        return;
    }
    if ( $exception === null ) {
        $this->logger->debug('Implicit commit - consider calling
commit() for clearer code.');
        $this->commit();
    } else {
        $this->logger->debug('Implicit rollback - consider calling
rollback() for clearer code.');
        $this->rollback();
    }
}

--
Rowan Tommins
[IMSoP]

Hey Larry, Tim, Seifeddine and Arnauld,

Arnaud and I would like to present another RFC for consideration: Context Managers.

https://wiki.php.net/rfc/context-managers

You'll probably note that is very similar to the recent proposal from Tim and Seifeddine. Both proposals grew out of casual discussion several months ago; I don't believe either team was aware that the other was also actively working on such a proposal, so we now have two. C'est la vie. :-)

Naturally, Arnaud and I feel that our approach is the better one. In particular, as Arnaud noted in an earlier reply, __destruct() is unreliable if timing matters. It also does not allow differentiating between a success or failure exit condition, which for many use cases is absolutely mandatory (as shown in the examples in the context manager RFC).

The Context Manager proposal is a near direct port of Python's approach, which is generally very well thought-out. However, there are a few open questions as listed in the RFC that we are seeking feedback on.

Discuss. :-)

I've been looking at both RFCs and I don't think either RFC is good
enough yet.

As for this RFC:

It makes it very easy to not call the exitContext() method when calling
enterContext() manually. The language (obviously) doesn't prevent
calling enterContext() - and that's a good thing. But also, it will not
enforce that exitContext() gets ever called (and it also cannot,
realistically).

Thus, we have a big pitfall, wherein APIs may expect enterContext() and
exitContext() to be called in conjunction, but users don't - with
possibly non-trivial side-effects (locks not cleared, transactions not
committed etc.). Thus, to be safe, implementers of the interface will
also likely need the destructor to forward calls to exitContext() as
well. But it's an easy thing to forget - after all, the intended usage
of the API just works. Why would I think of that, as an implementer of
the interface, before someone complains?

Ultimately you definitely will need the capability of calling
enterContext() and exitContext() manually too (i.e. restricting that is
not realistic either), as lifetimes do not necessarily cleanly nest - as
a trivial example, you might want to obtain access to a handle which is
behind a lock. You'll have to enter the context of the lock, enter the
context of the handle, and close the lock (because more things are
locked behind that lock, including the handle). ... But you don't
necessarily want the hold on the lock to outlive the inner handle. In
short: The proposed approach only allows nesting contexts, but not
interleaving them.

Further, calling with() twice on an object is quite bad in general. But
it might easily happen - you have a function which wants a transaction.
e.g. function writeSomeData(DatabaseTransaction $t) { with ($t) {
$t->query("..."); } }. A naive caller might think, DatabaseTransaction
implements ContextManager ... so let's wrap it: with($db->transaction()
as $t) { writeSomeData($t); }. But now you are nesting a transaction,
which may have unexpected side effects - and the code probably not
prepared to handle it. So, you have to add yet another safeguard into
your implementation: check whether enterContext() is only active once.
... Or, maybe a caller assumes that $t = $db->transaction(); with ($t) {
$t->query("..."); } with ($t) { $t->query("..."); } is fine - but the
implementation is not equipped to handle multiple calls to enterContext().

Additionally, I would expect implementers to want to provide methods,
which can be called while the context is active. However, it's not
impossible to call these methods without wrapping it into with() or
calling the enterContext() method explicitly. One more failure mode,
which needs handling.
Like for example, calling $t->query() on a transaction without starting it.

I don't like that design, which effectively forces you to put safety
checks for all but the simplest cases onto the ContextManager
implementation.
And it forces the user to recognize "this returned object
DatabaseTranscation actually implements ContextManager, thus I should
put it into with() and not immediately call methods on it". (A problem
which the use() proposal from Tim does not have by design.)

The choice of adding the exception to the exitContext() is interesting,
but also very opinionated:

• It means, that the only way to abort, in non-exceptional cases, is to
  throw yourself an exception. And put a try/catch around the with() {}
  block. Or manually use enterContext() & exitContext() - with a fake "new
  Exception" essentially.
• Maybe you want to hold a transaction, but just ensure that everything
  gets executed together (i.e. atomicity), but not care about whether
  everything actually went through (i.e. not force a rollback on
  exception). You'll now have to catch the exception, store it to a
  variable, use break and check for the exception after the with block.
  Or, yes, manually using enterContext() and exitContext().

It feels like with() is designed to be covering 70% of the use cases,
with a load of hidden pitfalls and advanced usage requiring manual
enterContext() and exitContext() calls. It's not a very good solution.

As to the destructors (and also in reply to that other email from
Arnauld talking about PDO::disconnect() etc.):

It's already possible today to have live objects which are already
destructed. It's extremely common to have in shutdown code. It's
sometimes a pain, I agree. But it's an already known pain, and an
already handled pain in a lot of code.
If your object only knows "create" and "destruct", there's no way for a
double enterContext() (nested or consecutive) situation to ever happen.
(Well, yes, you could theoretically manually call __destruct(), but
why would you ever do that?)

Last thing - proper API usage forces you to use that construct.

To the use() proposal from Tim:

This proposal makes it very simple to inadvertently leak the use()'d
value. I don't think the current proposed form goes far enough.

However we could decide to force-destruct an object (just like we do in
shutdown too). It's just one single flag for child methods to check as
well - the object is either destructed or not. We could also trivially
prohibit nested use() calls by throwing an AlreadyDestructedError when
an use()'d and inside destructed object crosses the use() boundary.

The only disadvantage is that there's no information about thrown
exceptions. I.e. you cannot add a default behaviour of "on exception,
please do this", like rolling transactions back. But:

• Is it actually a big problem? Where is the specific disadvantage over
  simply $db->transaction(function($t) { /* do stuff */ }); - where the
  call of the passed Closure can be trivially wrapped in try/catch.
• If yes, can we e.g. add an interface ExceptionDestructed { public bool
  $destructedDuringException; }? Which will set that property if the
  property is still undefined - to true if the destructor gets triggered
  inside ZEND_HANDLE_EXCEPTION. To false otherwise. And, if an user
  desires to manually force success/failure handling, he may set
  $object->destructedDuringException = true; himself as a very simple -
  one-liner - escape hatch.

The use() proposal is not a bad one, but I feel like requiring the RC to
drop to zero first, misses a bit of potential to save users from mistakes.
The other nice thing about use() is that it's optional. You don't have
to use it. You use it if you want some scoping, otherwise the scope is
simply the function scope.

To both proposals:

It remains possible by default to call methods on the object, after
leaving the with or use block. So some checking on methods for a safe
API is probably still required.

I don't think it's possible to solve that problem at all with the
ContextManager RFC, except manual checking by the implementer in every
single method. But it's possibly possible to solve it with the use() RFC
in orthogonal ways - like a #[ProhibitDestructed] attribute, which can
be added onto a class (making it apply to all methods) or a specific
method and causes method calls to throw an exception when the object is
destructed.
Which is possible to provide by the language, as the language knows
about whether objects are already destructed, unlike e.g. the
ContextManager, where it would be object state, which has to be
maintained by the user.

TL;DR: ContextManagers are a buttload of pitfalls. use() is probably
better, with much less inherent problems. And with the remaining
problems of the proposal being actually solvable.

Thanks,

Bob

Hi Bob,

I agree with your points, especially this one:

It makes it very easy to not call the exitContext() method when calling enterContext() manually. [...] Thus, we have a big pitfall...

This is the exact reason why, in the use() thread, I suggested a
Disposable interface should not have an enter() method. The
language should just guarantee a single dispose() method is called
when the scope is exited (successfully or not). This completely avoids
the "unbalanced call" pitfall. SA tools can warn/error when
dispose() is called manually. API authors should be aware that the
resource might receive multiple dispose() calls and handle this
gracefully.

Regarding your other valid concerns (nested calls, using objects after
the block, "leaking" the variable), I believe those are all solvable
by how the use() construct evolves, which is why I prefer its
foundation.

You noted:

It remains possible by default to call methods on the object, after leaving the with or use block. So some checking on methods for a safe API is probably still required.

You're right, but the use() proposal has a clear path to solve this,
which is far superior IMO to the manual checks required by the
ContextManager design. As discussed in the use() thread, we could
later introduce:

1. A Resource marker interface: This would tell the engine to
   handle the object specially (e.g., use weak references in backtraces
   to prevent accidental refcount inflation).

2. A Disposable interface: This would have the dispose()
   logic and could (and probably should) also be a Resource.

Furthermore, a Disposable interface opens up the possibility of
being supported outside the use() construct entirely. The engine
could guarantee dispose() is called whenever the object goes out of
any scope, just like a destructor but with crucial exception
awareness:

function x() {
  $disposable = new SomeDisposable();
  return; // $disposable->dispose(null) called
}

function y() {
  $disposable = new SomeDisposable();
  throw new Error(); // $disposable->dispose($error) called
}

This would make Disposable a truly powerful, general-purpose RAII
mechanism, not just a feature tied to use().

With these (future) additions, the use() construct could be enhanced
to enforce a no-escape policy specifically for Resources. If
use($r = get_resource()) finishes and $r still has references, the
engine could throw an error.

This combination would programmatically prevent the "use after free"
pitfall you described, rather than relying on manual checks inside
every single method.

All of those powerful safety checks can be added in the future. I
don't see why we need to cram them into the initial use() RFC. Its
current __destruct-based implementation is already useful today
for APIs designed to leverage RAII (like the Psl lock example). It's
normal that few APIs are designed this way now; the feature doesn't
exist yet. Psl just happens to support it because of its Hack origins.

This seems like a much safer and more extensible path.

Hello all.

It makes it very easy to not call the exitContext() method when calling
enterContext() manually

Consider the code below:

class FileContext {
    private $handle;

    public function __construct(private string $filename, private
string $mode) {}

    public function __enter() {
        $this->handle = fopen($this->filename, $this->mode);
        return $this->handle;
    }

    public function __exit(?Throwable $e = null) {
        if ($this->handle) {
            fclose($this->handle);
        }
    }
}

$ctx = new FileContext('example.txt', 'w');
$f = $ctx->__enter();

try {
    fwrite($f, "Hello world");
} finally {
    $ctx->__exit();
}

Question: what is the probability of making a mistake in this code?
What is the likelihood that a programmer will forget to call enter and exit?

...

with (new FileContext('example.txt', 'w')) as $f {
    fwrite($f, "Hello world");
}

In this case, the probability of forgetting to call enter or exit is
zero, since the language now supports this paradigm at the syntax
level.

Question: what is the probability of accidentally calling a method
instead of not calling it?

...

with (new FileContext('example.txt', 'w')) as $f {
    $f->__enter(); // Error!
    fwrite($f, "Hello world");
}

I believe that finding a clear mathematical proof in this case is impossible.
But if we look at studies on error statistics, it is the absence of a
call that is the most common problem.
(https://tomgu1991.github.io/assets/files/19compsac.pdf)

Thus, we have a big pitfall, wherein APIs may expect enterContext() and exitContext()
Is it really a big pitfall? If so, then functions like fopen and
fclose should be removed from the language altogether,
because their existence is an even bigger pitfall.

Ultimately you definitely will need the capability of calling enterContext() and exitContext() manually too (i.e. restricting that is not realistic either)

Of course, they can be restricted: make the methods private, so that
only PHP itself can call them, and they cannot be accidentally called
anywhere else outside the class.
But I don't see any convincing reasons for doing that.

The proposed approach only allows nesting contexts, but not interleaving them.
Why does this need to be done at all?
I don't know what "interleaving contexts" means in practice.
But even if they do exist, that goes beyond the scope of the current proposal.

Nevertheless, it is worth noting that studying Python bugs for this
RFC is a good thing:
https://bugs.python.org/issue29988 - with statements are not ensuring
that exit is called if enter succeeds.

Also:
https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager

Total:
Advantages of with:

• better semantics than try–catch
• less control-flow code

It would be strange to demand that with be safer than the rest of PHP code.
That’s an odd requirement. Of course, if PHP were a compiled language,
many checks could be done at compile time.
But we have static analysis for that.

Best regards, Ed

• Is there any interest in turning using into an expression rather than a statement, so that it can be used in expression contexts?

What would it evaluate to? The value returned by exitContext()? That's
already controlling whether caught exceptions are rethrown, so the only
value that would ever reach an enclosing expression would be "true".

(I've sometimes thought about making return an expression in the same
spirit as throw. Its evaluated type would of course be "never" since
any enclosing expression would be abandoned.)

Morgan

Arnaud and I would like to present another RFC for consideration:
Context Managers.

https://wiki.php.net/rfc/context-managers

You'll probably note that is very similar to the recent proposal from
Tim and Seifeddine. Both proposals grew out of casual discussion
several months ago; I don't believe either team was aware that the
other was also actively working on such a proposal, so we now have two.
C'est la vie. :-)

Naturally, Arnaud and I feel that our approach is the better one. In
particular, as Arnaud noted in an earlier reply, __destruct() is
unreliable if timing matters. It also does not allow differentiating
between a success or failure exit condition, which for many use cases
is absolutely mandatory (as shown in the examples in the context
manager RFC).

The Context Manager proposal is a near direct port of Python's
approach, which is generally very well thought-out. However, there are
a few open questions as listed in the RFC that we are seeking feedback
on.

Discuss. :-)

More updates to Context Managers:

• We have added "masking" for the context variable, using essentially
  the same technique as the block scope RFC.
• We have added support for try using, as a shorthand for when you
  want to wrap a try-catch-finally around a using statement anyway.

More details of both are in the RFC.

As no one seems to have a strong opinion on continue, we will most
likely proceed with the current approach of matching switch behavior.

There doesn't seem to be much interest in making using an expression,
which I find unfortunate, but that means we'll probably drop that.
Fortunately it is probably possible to change in the future if the need
arises (the way throw was changed).

--Larry Garfield

Since the only feedback on what to use for "as" was that => makes sense, we have changed the RFC to use => instead. So the new syntax is

using (new CM() => $cVar) {
// Do stuff here.
}

--Larry Garfield

Hi

Note: I've not been able to fully work through the ML discussion and
meaningfully think about all the commentary. This includes some of the
older emails. I have also not yet given the RFC an in-depth read, like I
would have normally done.

Some (incomplete) notes for now:

Am 2026-01-13 23:19, schrieb Larry Garfield:

Once those issues are addressed, I think we're nearly able to take CMs
to a vote. (If anyone else wants to weigh in on some other part as
well, even if it's just a voice of support/approval, now is the time.)

Something that I had noted in response to Rowan in the (what you call)
“Bonus Thread” in https://news-web.php.net/php.internals/129582 and also
in this RFC's discussion in
https://news-web.php.net/php.internals/129618 and what was also
mentioned by Marco Deleu in
https://news-web.php.net/php.internals/129083 and what I feel is neither
properly justified within the RFC text and as far as I can tell was not
really discussed either:

The fact that break; and continue; target using() blocks. To me it
violates the principle of least surprise that

 foreach ($users as $user) {
     using (new SuppressErrors()) {
         if ($user->isAdmin()) {
             $firstAdmin = $user;
             break;
         }
     }
 }

is incorrect code. The RFC just states that this will happen as a
fact, but does not attempt to explain why that decision was made and
neither are there any examples showcasing how that could be useful.

I'd also like to note that there's also an “Open Issue” listed in the
RFC that is related to this topic.

With regard to the desugaring listed at the top: Can you please also
provide the desugaring for the case where no context variable is
specified for completeness?

Best regards
Tim Düsterhus

Hi

Once those issues are addressed, I think we're nearly able to take CMs to a vote. (If anyone else wants to weigh in on some other part as well, even if it's just a voice of support/approval, now is the time.)

Something I noticed while reviewing the block scoping RFC: Both RFCs
come with new OPcodes in the engine.

This can have an impact on extensions that work with OPcodes, for
example profilers and debuggers. Block scoping already mentioned this in
the RFC Impact section, but the context manager RFC does not.

For block scoping the two OPcodes are relatively straight-forward
assignments which should (hopefully) be easy to take into account for a
debugger. For context managers there seems to be more associated logic
to set up the scope within the ZEND_INIT_USING OPcode, which might be
more troublesome for debuggers to correctly reason about when stepping
through the code (e.g. with the $__RETURN_VALUE meta variable or
whatever it is called). Perhaps Derick can provide insight here?

Looking at that OPcode I'm also seeing the initialization of the
ResourceContextManager class. In the RFC it is called
ResourceContext and it is non-final there (final in the
implementation). This is an inconsistency that should be fixed. For that
one I was also wondering if it is possible to directly initialize it in
userland (the constructor seems to be public) and if it will then behave
as expected. I assume the answer is yes to both, but it would be useful
for the RFC to clarify this.

Best regards
Tim Düsterhus

Le 13 janv. 2026 à 23:19, Larry Garfield [email protected] a écrit :

Arnaud and I would like to present another RFC for consideration:
Context Managers.

https://wiki.php.net/rfc/context-managers

You'll probably note that is very similar to the recent proposal from
Tim and Seifeddine. Both proposals grew out of casual discussion
several months ago; I don't believe either team was aware that the
other was also actively working on such a proposal, so we now have two.
C'est la vie. :-)

Naturally, Arnaud and I feel that our approach is the better one. In
particular, as Arnaud noted in an earlier reply, __destruct() is
unreliable if timing matters. It also does not allow differentiating
between a success or failure exit condition, which for many use cases
is absolutely mandatory (as shown in the examples in the context
manager RFC).

The Context Manager proposal is a near direct port of Python's
approach, which is generally very well thought-out. However, there are
a few open questions as listed in the RFC that we are seeking feedback
on.

Discuss. :-)

Hi folks. The holidays are over, so we're back on Context Managers.

[...]

--Larry Garfield

Hi,

Just a small question. What happens when an exit/die instruction is executed inside a using block? Is the relevant exitContext() handler invoked, just like for an early return or break?

This is probably self-evident, but it is worth to state it explicitly, because, for some hysterical reason, relevant finally blocks are not executed with exit.

—Claude

Hi

a function is already a reasonable scope

That - together with the other points you raised - made me realize one
thing: In contrast to block scoping, the main purpose of “Context
Managers” is not managing arbitrary variables in the current scope in
combination with existing control structures. Instead it is just
managing a single variable in a reasonably self-contained fashion,
with other variables just needing to “exist”.

It could therefore also just be a regular function taking a callback, as
is already done in userland, e.g. with Laravel's DB::transaction() helper.

I believe something like this would be equivalent to the RFC:

 function using(
     callable $runInContext,
     ContextManager ...$managers
 ): void {
     $contexts = [];
     foreach ($managers as $manager) {
         $contexts[] = $manager->enterContext();
     }

     try {
         $runInContext(...$contexts);
         foreach (array_reverse($managers) as $manager) {
             $manager->exitContext();
         }
     } catch (Throwable $e) {
         foreach (array_reverse($managers) as $manager) {
             if ($manager->exitContext($e) === true) {
                 $e = null;
             }
         }
         if ($e !== null) {
             throw $e;
         }
     }
 }

This would completely side-steps the “break to exit” question, since a
return will just work. It also avoids introducing new keywords, it
just requires a new function in the global namespace.

I understand that using variables from the current scope in a Closure is
currently not particularly convenient, particularly when they need to be
changed. However this is something that can be solved in a generic
fashion, for example inspired by the C++ lambda syntax:

 // Captures everything by value and $result by reference.
 function ($context) use (*, &$result) { }

 // Captures everything by reference.
 function ($context) use (&*) { }

which would also be useful in other situations.

Best regards
Tim Düsterhus

Hi Larry, Hi Internals,

Last year I promised you (Larry) some feedback on-list as well and
didn't get around to it until now. I recognize the strain that
repeating arguments has on a discussion like this, and this topic has
already taken up a lot of focus and time for the folks here.

But I wanted to at least explain why I think PHP would be better off
without having this in core and why I think it would be a net negative
for PHP to have this.

So to summarize, I find the feature doesn't fit in PHP. It's
introducing more magically called methods, burdened with unnecessary
complexity, while being very limited in its potential (sensible) uses.
Combined with its class-only high-verbosity approach, I feel this is
lacking places where it would improve PHP code in general and better
suited for a library for people that want this type of, what I
consider, magical indirection.

As noted in Future Scope, we can add function-based context managers as well based on generators. At the moment we're not convinced it's necessary, but it's a straightforward add-on if we find that always writing a class for a context manager is too cumbersome.

The issue with punting this behavior to user-space is that a library cannot provide this sort of functionality in a clean way.

In an ideal world, if we had auto-capturing long-closures, then I would agree this is largely unnecessary and could instead be implemented like so (to reuse the examples from the RFC):

$conn->inTransaction(function () {
// SQL stuff.
});

$locker->lock('file.txt', function () {
// File stuff.
});

$scope->inScope(function () {
$scope->spawn(yadda yadda);
});

$errorHandlerScope->run(fn() => null, function () {
// Do stuff here with no error handling.
});

And so forth. If we had auto-capturing closures, I would probably argue that is a better approach.

However, auto-capturing closures have been rejected several times, and I have no confidence that we will ever get them. (Whether you approve or disapprove of that is your personal opinion.) The current alternative involves using lots of use clauses, which is needlessly clunky to the point that folks try to avoid it.

I literally have code like this in a project right now, and I've had to do this many times:

public function parseFolder(PhysicalPath $physicalPath, LogicalPath $logicalPath, array $mounts): bool
{
return $this->cache->inTransaction(function() use ($physicalPath, $logicalPath, $mounts) {
// Lots of SQL updates here.
});
}

That's just gross. :-) This is exactly the example that's been used in the past to argue in favor of auto-capturing closures, but it's never been successful.

So given the choices we have made to limit the language, context managers become the next logical option to encapsulate common error handling patterns.

We chose to pursue this syntax now because of the ongoing async discussions, as IMO, full structured-only concurrency is the Right Way forward. So rather than a one-off for async, it's better to have a generic syntax that would work for a dozen use cases, not just one.

As to it being too "magical," the definition of that is, as always, highly subjective. Magic is just code I don't understand. It should be noted that what is proposed here is almost identical in design to Python, which makes heavy use of this design and is widely regarded as one of the easiest languages to learn. So it's clearly not too magical for beginners.

With the name also being extremely generic and non-descriptive, this
all feels like bloat to me that complicates the language for no
tangible benefits.

The name was borrowed from Python, which should make it easily understandable for all of those beginners who started on Python. If there's a better name for the Interface you'd like to use, though, we're open to suggestions. Similar (if less robust) functionality exists in C#, also called Context Managers (https://useful.codes/working-with-context-managers-in-c-sharp/). Context Managers are also used in Java, again for similar but not as robust functionality (https://useful.codes/working-with-context-managers-in-java/).

We modeled on Python, as it was the most robust of the existing options, but "context manager" does seem to be the de facto standard name for this pattern.

To expand a bit on the points:

• Non-local behavior:

Every using statement is a couple of function calls that are
non-obvious in how they delegate to some __magic interface methods
that are not supposed to (but very able to) be called explicitly. With
the implicit catch and exitContext() ability to return true/false; to
rethrow/suppress an exception, adding even more hidden branching to
execution.

__construct, __destruct, __get, property hooks, ArrayAccess, Iterable, __serialize, ... PHP decided that triggering "hidden" behavior at certain points was acceptable decades ago. If anything, the use of a dedicated keyword here makes it less magical than __get or property hooks, as it clues the reader in that a context manager is being used. And in every one of those cases, it's technically possible to call the magic or interface method explicitly, but it's culturally discouraged. There's no reason Context Managers should not be in the exact same category.

If we could use auto-capturing closures, it would effectively just be the strategy pattern. But as above, PHP has decided that we need a few more steps to make that work, which Context Managers resolve.

• Variable masking:

A new block masking and restoring the context variables but not others
is an additional source of errors and confusion that I feel doesn't
pay off in terms of value vs. added complexity and error sources.

It's not behavior we have anywhere else in PHP and breaks the flow of
reading and reasoning about code in non-obvious ways.

This was added largely because it was requested for the block scoping RFC, and it seemed to make sense here too. If the consensus is that it's not worth it, we're OK with pulling that part back out. It's not core functionality.

Does anyone else feel strongly either way on this point?

• Break/Continue semantics:

There is no clear reason for me why this block scope should allow
early returns. If the content is growing to a point where it's needed,
a function is already a reasonable scope. Given that PHP allows for
break 2;, something that we'll see more of then, it's manageable. It
just adds to the, for me, unreasonable complexity of the feature.

Even a 4 line block could have an if statement in it, which may involve terminating the block early without throwing an exception. Without break or similar, the only option for the user would be a goto and a label after the using block ends. I hope we don't need to explain why that is an inferior solution.

As far as an example (to Tim's email):

function ensure_header(string $filename, array $header) {
using (open_file($filename) as $f) {
$first_line = fgets($f);
$first = parse_csv($first_line);
if ($first[0] === $header[0]) {
break; // The thing we want to ensure is already the case, so bail out.
}
// Logic here to prepend $header to the file.
}
}

While it would be possible to reverse the conditional, almost every modern recommendation is to use early returns as much as possible. Or in this case early break.

• Naming:

For me, despite having worked with Python, the name means absolutely
nothing. It doesn't even manage the context of the invocation. If
anything, it manages when a resource is released into and removed and
deallocated from a scoped context. And that sentence also is rough.

PHP, for better or worse, doesn't burden its users with having to
study many CS concepts beyond basic OO or procedural programming and
still allows them to write obvious, valuable, and predictable code. I
understand that with its evolution this has changed, and we have added
a lot of redundancy (short arrays, short functions, pipes, etc..) to
provide sugar that has steepened the learning curve for some.
Adding very specific single-use concepts to the language with their
own disconnected naming schemes, syntax, or, in this case, hidden
behaviors should be carefully considered. And while I'm sure you did
we came to different conclusions.

Again, I go back to the example of Python, often lauded as a great beginner language. It lets you write procedural or OOP (though it does have multiple inheritance), though it's weaker on functional than PHP 8.6 will be, I'd argue. But it makes heavy use of context managers, and it doesn't seem to hurt anyone.

As far as redundancy, that's in large part because PHP was never designed, it's just been patched over the last 30 years. But often, we're just moving up the abstraction curve along with the rest of the language community. Or identifying common patterns and problems and finding ways to extract out the hard bits to make them easier. CSS, incidentally, evolves the same way: Find common patterns and problems, figure out a general language-level solution, and add new features to the language to turn "500 lines of Javascript" into "2 CSS keywords."

Remember, all code is syntactic sugar over assembly. :-)

• Block scoping:

Personally, I don't see the need for block scoping in PHP in general.
But having a generic solution that works without creating a new class
for each case would feel like something that at least can be used by
everyone and every part of the language.

I disagree that "everyone" will have to write a CM. In practice, I'd expect most people wouldn't; it would be part of the API exposed by library X, and users of that library will use the CMs that are provided. The whole point is that the logic is reusable, and thus reduces the need for "everyone" to write it. For example, Doctrine could provide a single InTransaction CM, which every single user of Doctrine would benefit from. (Much the same as Doctrine's existing inTransaction() method, which suffers from the use-bloat problem described above.) PHP itself could provide a single CM for files, possibly using SplFile, so no one else would have to write one, ever, unless they needed some highly wonky custom logic. In which case they'd be custom writing something anyway. But this way, they get the recommended error handling out-of-the-box in the standard case.

As far as a "generic solution," I have added a section to the RFC on "value escape," based on an observation I made a while back in the bonus thread. Specifically, there will always be a failure case if the context variable escapes (or its equivalent in traditional code), but there is no universal answer to what failure case you want. A Context Manager approach allows you to explicitly decide that for each situation as needed.

Tying this to custom objects doesn't feel like a language level
feature but something that should be in a library.

As noted above, PHP has deliberately chosen to make library-based solutions to this space inferior.

The worst option would be to allow using() to take a context manager
or a plain expression and make people guess every time the statement
is used if hidden function calls are attached to it.

So we'll mark you as a no on having that fallback shorthand, then. :-) Would you rather a rudimentary UnsetAtEnd CM be included?

• Verbosity:

Having to implement three code paths for each ContextManager (enter,
exitWithoutError, exitWithError) within two functions, with a near
mandatory if in a separate class, doesn't strike me as useful over
patterns like getting and returning a connection out of a pool
“manually.” The trade-off between this and already existing solutions
to this problem with try/finally or construct/destruct isn't enticing.

I disagree, naturally. Just from the examples in the RFC, I'd say the resulting code is far cleaner, less redundant, easier to read, and you're less likely to forget error handling.

We debated a 2 method vs 3 method solution, that is, splitting exitContext() into exitSuccess() and exitFailure(). The challenge there is that if you have common logic to happen in both cases, you have to duplicate it. Merging them into exitContext(), you have to deal with an if-statement most of the time. Either way is a trade off. Additionally, you may not want anything to happen on one of exitSuccess() or exitFailure(), in which case you'd have an empty method, or else we use magic methods instead of an interface, which we weren't wild about.

So no approach is perfect, so we started with the one that Python has already shown is useful and effective. If there's a different way to organize that code that you think would be better, we're open to suggestions.

• Object lifecycle in PHP:

Just to reiterate because it bugs me as PHP zval life cycles are used
as an argument here: Reference counting in PHP is fully deterministic,
and code like function () { $x = new Foo(); return; } will
deterministically construct and destruct (at the end of the function
as the variable gets cleaned up). Use cases where the GC would
actually come into play are extremely rare from the real-world usages
we can see in Python. I also haven't seen an example in PHP nor
something in the RFC that looks overly convincing in improving this
with managed in-function unsets. The error handling option is nice,
but for maintainability, simplicity, and effort in writing code, I'd
still prefer this to try/(catch)/finally

To reiterate what I said above and in the new section in the RFC: The issue isn't about reference counting determinism at the engine level. The issue is developer A may expect something to happen when an object goes out of scope, but it won't because developer B stashed a copy of it somewhere so it won't actually destruct.

That problem is not created by context managers, and it affects the Block Scoping proposal as well. It's an unavoidable fact of basically any language with automatic garbage collection. You can predict when a variable goes out of scope, but you cannot prevent a reference to its value from continuing to exist past when you expect it, thus delaying any on-cleanup behavior beyond when you expect it.

What context managers offer is a way to decide what to do with that situation, because, again, there is no globally applicable answer.

But this is one reason that relying on destructors is a poor approach if you want cleanup X to happen at point Y: You can't be certain the destructor will be called then, even if the reference counting logic is fully deterministic. On top of that, destructors, as noted, cannot differentiate between success and failure cases, which often require different cleanup. Externalizing that logic out of the value itself (from the context variable to the context manager) allows flexibility in both cases that simply does not exist otherwise without a large amount of code.

Python recommends using CMs for files and similar values precisely for this reason, and has essentially the same ref-count-plus-cycle memory model.

Layering another level of lifecycle management on top of the existing
PHP behavior doesn't feel like a simplification but rather like
another source of complexity with this new niece special case.

--

In summary, this feels like beyond what's necessary to get rid of a
couple of try/finally blocks per application and encourages bad
patterns like using ContextMangers for async instead of more modern
APIs that have evolved since then.

I would argue that context managers for async is the more modern API, and creating/canceling/blocking async tasks manually is the legacy, poor approach.

--Larry Garfield

Larry,

Am 2026-03-22 19:19, schrieb Larry Garfield:

Arnaud and I have made a number of changes to the RFC that should make
it sleaker and more consistent. The notable ones (that impact
behavior) are as follows:

“Sleaker” is not a word my dictionary understands. Was this a typo for
“sleeker” in the sense of “refined”?

1. We went back and forth on the continue question several times,
   before coming to the conclusion that continue is a tool for looping
   structures only. That switch also uses it is just switch being
   silly because reasons, and there is no reason using must inherit its
   weirdness. Therefore, continue inside a using block now means
   nothing at all. continue will ignore it, the same way it ignores an
   if statement.

I fail to see how “making break; and continue; behave inconsistently” is
making the RFC (and by extension) the language any more consistent. In
this following example snippet it's not at all obvious that the break
is behaving incorrectly by targeting the using() with continue
targeting the foreach(), despite both using the same “number”:

 $processed = 0;
 foreach ($entries as $entry) {
     using ($db->transaction()) {
         switch ($entry['type']) {
         case 'EOF':
             break 2;
         default:
             if (should_skip($entry)) {
                 continue 2;
             }

             $db->insert($entry);
         }
     }

     $processed++;
 }

I'm also noticing that the RFC still does not explain why the decision
for break to target using() has been made. For your reference, my
last email asking that question is this one:
https://news-web.php.net/php.internals/129771. I didn't receive a reply
to that email either (and neither do the list archives have a reply).

2. Several people (including us) were uncomfortable with using a
   boolean return from the exitContext() method. While that is what
   Python does, it is indeed not self-evident how it works. (Should true
   mean "true, I'm done" or "true, rethrow"?) We debated using an enum
   value, but that appeared to be too verbose.

Instead, we decided that exitContext() should return ?Throwable, which
is the same thing it is passed. In a success case, it is passed null.
In a failure case, it is passed a throwable. So it can then return
null (meaning "we're done, nothing else to do here") or a throwable,
which will then get thrown. Since in most cases an error should be
allowed to propagate, it means simply calling return $exception at
the end of the method will "do the right thing" 95% of the time.
Simple and easy and self-documenting. (If there's a reason to wrap and
rethrow the exception, do that and return the new exception. Or to
swallow the exception and not propagate it, return null.)

That sounds like a “throw” statement with extra steps [1]. While nothing
stopped you from writing throw new SomeException(); within
exitContext() with the bool return value, it at least encouraged
you to not replace the original Exception with another Exception
entirely and to just make a decision between “suppress” or “not
suppress”. Now return is completely equivalent to throw (at least as
long as exitContext() doesn't contain a catch() itself) adding even
more layers of “using() is magically including behavior of other
language constructs” that will be hard to reason about for humans and
machines alike.

Best regards
Tim Düsterhus

[1]

 function raise(\Throwable $e): ContextManager {
     return new class ($e) implements ContextManager
     {
         public function __construct(private \Throwable $e) { }

         public function enterContext(): mixed { }

         public function exitContext(?\Throwable $e = null): 

?Throwable {
return $this->e;
}
};
}

 using(raise(new \Exception())) { }

Arnaud and I would like to present another RFC for consideration: Context Managers.

https://wiki.php.net/rfc/context-managers

You'll probably note that is very similar to the recent proposal from Tim and Seifeddine. Both proposals grew out of casual discussion several months ago; I don't believe either team was aware that the other was also actively working on such a proposal, so we now have two. C'est la vie. :-)

Naturally, Arnaud and I feel that our approach is the better one. In particular, as Arnaud noted in an earlier reply, __destruct() is unreliable if timing matters. It also does not allow differentiating between a success or failure exit condition, which for many use cases is absolutely mandatory (as shown in the examples in the context manager RFC).

The Context Manager proposal is a near direct port of Python's approach, which is generally very well thought-out. However, there are a few open questions as listed in the RFC that we are seeking feedback on.

Discuss. :-)

--
Larry Garfield
[email protected]

Hi Larry/Arnaud,

This is a pretty exciting thread and fascinating proposal. That being said, I have a couple of subtle questions that don't seem to be answered in the (very long) thread or the RFC itself -- If I missed it, please let me know:

1. What happens if a Fiber is suspended in the using block and never resumed? When is the using block released to clean up the context?
2. There's still no mention of how this should affect debugging, will we see the "desugared" or "sugared" version? Is that even a concern for the RFC?
3. I will say it is weird to have exitContext return an exception; but what happens if an exception is thrown during exitContext? Why not just have it return void and throw if you need to throw instead of having two paths to the same thing?
4. Looking at the desugared form ... I'm a bit confused: if exitContext is called during the finally path and returns an exception, it is just swallowed? But if it is thrown, it won't be?
5. That being said, I don't think the RFC shares with us when we should return an exception vs. throw an exception.

— Rob

Maybe the desugared version should look more like this?

} catch (\Throwable $e) {
try {
$__mgr->exitContext($e);
} catch (\Throwable $cleanupException) {
throw new ContextManagerException(
$cleanupException->getMessage(),
previous: $e
);
}
throw $e;
}

— Rob