[RFC] Context Managers

Hi Am 2025-11-06 13:18, schrieb Rowan Tommins [IMSoP]:

The reference to the sibling thread probably fits even better here than in my previous reply. So I'm putting another reference: https://news-web.php.net/php.internals/129467

That is *technically* true and there are indeed some “expert-level” use cases where calling these manually - except for `parent::` I guess - is required (e.g. lazy objects), but there's a very significant difference: Those are magic methods following the naming scheme of magic methods. The `__` prefix is a visual indicator that the methods are somehow special and probably not meant to be used directly. The documentation at https://www.php.net/manual/en/language.oop5.magic.php states (highlighting mine):

This is not true for the context manager methods. From a developer's PoV these are normal methods on a class with nothing screaming “be careful”. The interface *could* serve as a invitation for folks to read the documentation on how the interface methods are meant to be used, but we all know how that works in practice with an IDE suggesting normal-looking methods that appear to do the right thing (until they don't). Best regards Tim Düsterhus

Hi Am 2025-11-09 16:07, schrieb Larry Garfield:

See my sibling reply to Rowan (https://news-web.php.net/php.internals/129468).

You are wrong here. Manually interacting with an Iterator is not just safe, it is also necessary for some use cases. The simplest example would be iterating two Iterators in lock-step (i.e. doing a `zip()` operation / array_combine()).

See sibling reply for an explanation how `__construct()` is different. Best regards Tim Düsterhus

On Mon, 15 Dec 2025 at 20:01 Ben Ramsey <ben@benramsey.com> wrote:

I also agree with Matthew but the reversed proposed here looks very very awkward to me. I think the most natural thing is the “as” but I may have missed the discussion on why it had to be changed. Thinking of foreach ($array as $value), an item from the array (left) is assigned to $value (right). That seems symmetrical to using (new Manager as $manager) where the instance (left) is assigned to the variable (right). Also when using aliases on the top of the file “use Foo as Bar;” as is also assigning the left to the right.

On Thu, Apr 2, 2026, at 5:13 AM, Tim Düsterhus wrote:

We've updated the RFC to address the break question (new section), the continue question (which is now a secondary vote), and expanded the reasoning for the `return $e` decision, including reference to the original Python PEP which explains the need for a distinction. --Larry Garfield

Le 15/04/2026 à 17:10, Larry Garfield a écrit :

Yep, I would have been much more okay with a revised version of the `let` scoping keyword, though the implementation also seems quite complex too.

I have read a few of the messages on externals.io, maybe not everything, but your answer indeed makes things a bit clearer. It mostly makes me think that this RFC is a bit complex and I don't see /many/ userland use-cases that would actually need this. IMO, it tries to /make some safeguards/ implicit, like closing resources. I recognize that it's useful for this case, but does PHP really need a new feature this big "just" to close resources 10 milliseconds earlier in a process that takes 100ms anyway? The benefits would only go to projects with huge amount of concurrent calls, which are not all of them.

No auto-capture in closures is IMO an actual *good* thing, because it avoids having issues with the current world of JS/TS where auto-capture is default, and it brings problems with references. My suggestion with the `scoped` keyword also carries auto-capture by design, which makes the "capturing system" (shadowing, references, etc.) less intuitive in the first place. It's "yet another thing to keep in mind" at first, but for legacy apps renovators like me, it's mostly "they haven't kept this in mind" debugging hell ^^', but considering there's always worse, it's negligible, especially if it's intended to be a new feature. Still: creating a new scope makes things safer. It creates a new stack with its own pointers, and frees it at finish. They are a pain to use for now mostly because there's more code to write, it needs to be called (or auto-called with `()` after it), and capture must be explicit via `use` . The `scoped` keyword proposal automates all this with existing PHP features, while the ContextManager adds new features for that, and we don't know (yet) the overhead. Sorry for being this picky :)

On Tue, Apr 21, 2026, at 7:16 AM, Rowan Tommins [IMSoP] wrote:

Since this seems like a contentious area, let me go back to first principles and try to explore the problem space. (This is an essay; meaning I don't know where it's going to end up yet as I write this.) ## The problem space A context manager may exit in one of two conditions: Success or Failure. There are three types of code that a CM may want to run, but not always all of them: * Code that happens on success. * Code that happens on failure. * Code that happens on both. In the case of Success, there is no value to propagate. In the case of Failure, there is a value (exception) to conditionally propagate, but the default case should be propagate. The CM may have its own error, in which case it will want to propagate that error (as a throwable). Would a CM ever want to wrap-and-rethrow a lower-level exception, rather than just passing it on itself? I suppose it's possible, though I'm not sure of a specific example off hand. ## Python's answer The Python answer is a single `__exit__` method, which may be passed optional exception information. In Python, not returning anything is equivalent to returning null, which is falsy, so "return true to stop propagation or do nothing to continue propagation" is reasonable and ergonomic. That is not the case in PHP, however; a function with a typed return MUST have a `return` statement in it, and it's not immediately obvious to a user what true-vs-false will do. (Does true mean "yes propagate" or "yes suppress"?) It also makes the return value meaningless in the success case, which is not immediately obvious. So mimicking Pythong in this case is not a viable approach. ## Basic structure In PHP, we could have the three different code paths in one, two, or three methods. The three method approach would be something like: ``` public function contextSuccess() { // Do stuff only on a success case. } public function contextFail(Throwable $e): bool { // Do stuff only on a failure case, you must return a value. } public function contextExit() { // Do stuff in any case. } ``` That approach has 2 problems: One, contextExit() must then be called either before or after the success/fail callback, always, which may not support the desired cleanup process. Two, if all three are on the CM interface then they all must be implemented, even if there's nothing for them to do. That's bad ergonomics. (Side note: interface-default-methods would help a ton here.) The second point could be resolved by making them all magic methods rather than an interface, but that brings with it all the lack-of-introspection challenges of magic methods. The two method approach would be: ``` public function contextSuccess() { // Do stuff only on a success case. // Do common stuff here. } public function contextFail(Throwable $e): bool { // Do stuff only on a failure case, you must return a value. // Do common stuff here, redundantly. } ``` Or alternatively, call out to a separate common method from both. This would probably work, but again has two problems: One, it makes common actions harder to do, as it requires either redundancy or another method (which may not always be viable in context). Two, the same "must define both of them even if you don't care" problem exists. (Again, interface-default-methods would solve this.) The single method approach is what the RFC currently proposes: ``` public function contextExit(?Throwable $e) { // Do whatever you want, in whatever order, and if ($e === null) to differentiate success/failure. } ``` This approach resolves both issues of the previous models, but creates one more: the exit condition (return, throw, etc.) from this method is quite complex: - In a Success case, there is no exit condition (return and continue) - In a Failure case, there is a binary exit condition (propagate or suppress) - In the case contextExit() itself has a failure, it would need to throw its own exception, which implies suppressing the original. I do believe the single-method approach is the least-bad, if we can resolve the exit condition question. ## Ways of handling a single method's returns Possible ways to do so off the top of my head, in no particular order: - Return True to suppress, return False to propagate, return Null on success, throw on CM error. (This is what earlier versions of the RFC had.) Pro: Clear delineation for each pathway. Con: Needlessly complex in practice and not self-documenting. Doesn't differentiate between CM exception and underlying exception. ``` public function exitContext(?Throwable $e): ?bool { if ($e) { // Error cleanup } else { // Success cleanup } // Oops, something went wrong. throw CMException(); // Common cleanup return $e === null; } ``` - Same as previous, but use enums. Pro: more self-documenting. Con: Still needlessly complex, now more verbose, too! Doesn't differentiate between CM exceptions and underlying exceptions. Returning one of the Failure case values on a Success case would, uh, just ignore it? That's not great. ``` public function exitContext(?Throwable $e): ?bool { if ($e) { // Error cleanup } else { // Success cleanup } // Oops, something went wrong. throw CMException(); // Common cleanup if ($e) { if (something) { return CMResult::Propagate; } return CMResult::Suppress; } else { return CMResult::Success; } } ``` - Return an exception to cause it to throw, or null to not throw. This folds the return value into a single line in most cases. (This is what the RFC says right now.) Pro: Ergonomically very convenient. Con: `return $e` and `throw $e` become effectively the same thing, so it's not clear when you'd use one or the other. Doesn't differentiate between CM exception and underlying exception. ``` public function exitContext(?Throwable $e): ?Throwable { if ($e) { // Error cleanup } else { // Success cleanup } // Oops, something went wrong. throw CMException(); // Common cleanup return $e; } ``` - As Rowan suggested, void return, only propagate on throw. Pro: Folds different pathways together in a natural way. Con: The most common case (propagate exception) is the one that requires additional work, not the rare case (not propagating), so I can see it being very common for people to forget to rethrow. Doesn't differentiate between CM exception and underlying exception. ``` public function exitContext(?Throwable $e): void { if ($e) { // Error cleanup throw $e; } else { // Success cleanup } // Oops, something went wrong. throw CMException(); // Common cleanup } ``` - Follow event-dispatcher patterns, like PSR-14, and call a built-in method to prevent propagation. Pro: In the typical case where you want to allow propagation, there's literally nothing to do. That makes the common case very ergonomic. Con: This would necessitate either a ContextManager base class instead of interface, or some black magic where adding the interface magically adds this method. (Side note: interface-default-methods would probably help here.) ``` public function exitContext(?Throwable $e): void { if ($e) { // Error cleanup throw $e; } else { // Success cleanup } // Oops, something went wrong. throw CMException(); // Common cleanup // $e will get propagated unless this is called. $this->stopPropagation(); } ``` - Totally wild thought: throw a special "don't throw anything else" exception, which gets special handling. Pro: In the typical case where you want to allow propagation, there's literally nothing to do. That makes the common case very ergonomic. Con: Throwing an exception to prevent an exception from being thrown is just... weird. ``` public function exitContext(?Throwable $e): void { if ($e) { // Error cleanup } else { // Success cleanup } // Oops, something went wrong. throw CMException(); // Common cleanup // If this line is missing, $e gets rethrown. throw new StopPropagationException(); } ``` None of these allow differentiating at runtime between a CM error and an underlying error. In most it could be differentiated in static analysis, but not at runtime. Whether or not that is a problem is, I think, an open question. The Python PEP for context managers suggests that if one cares, it's possible to avoid `using` and call it manually, allowing for that differentiation. If we use the `return $e` approach, a manual/higher-order CM could make the differentiation by calling the CM methods itself, rather than relying on `using`. ``` try { $cm = new SomeCM(); $cv = $cm->enterContext(); // Do code here. $e = $cm->exitContext($e); if ($e !== null) { // body failed, exit success } } catch (\Throwable $e) { // body failed, exit failed too } ``` However, the whole point of `using` blocks is to not need to do that, so if it's a common need, that would be highly sub-optimal. It also wouldn't be available in the other approaches. ## Conclusion I think a key question to answer here is: Do we care to differentiate between CM errors and underlying errors? If not being able to do so is a non-issue, or small enough that we don't care, then we have more options. I'm not sure which of the last 3 I like most/dislike least: "always rethrow", "call method to suppress", "throw special to suppress". They all have pros and cons. If we do care, then we may need to adapt the materialized code and expand the syntax in some way to allow for it. I'm not sure yet what that would look like. I will stop here, however, and ask for input from the audience. (Not just the regulars in this thread of late, but all of you reading this.) Including if you have an alternate approach to the three listed above that would have notably fewer cons. --Larry Garfield