Skip to content

catch Throwable in dispatch and server error boundaries - #230

Merged
falkenhawk merged 2 commits into
masterfrom
catch-throwable
Apr 13, 2026
Merged

falkenhawk merged 2 commits into
masterfrom
catch-throwable

Conversation

@falkenhawk

@falkenhawk falkenhawk commented Apr 8, 2026 •

Copy link
Copy Markdown
Member

closes #201

Since PHP 7, Error classes (TypeError, DivisionByZeroError, etc.) extend Throwable but not Exception. The framework's catch (Exception) blocks in dispatch chains and server handlers let these slip through as unhandled crashes.

Mainly affects zend-controller (front controller, dispatcher, plugin broker). The same pattern is also fixed in server components (zend-rest, zend-soap, zend-json, zend-xmlrpc) and zend-tool.

Now that PHP 7.1 is the minimum (#218), all error boundary catch blocks are widened to catch (Throwable).

setException() compatibility

Zend_Controller_Response_Abstract::setException() and Zend_Tool_Framework_Client_Response::setException() type-hint Exception. To avoid a BC break in the method signature, non-Exception throwables are wrapped in the appropriate framework exception class before being passed, with the original preserved as $previous.

Wrapping means that e.g. a DivisionByZeroError will appear in the response as Zend_Controller_Exception, so hasExceptionOfType('DivisionByZeroError') won't match - but the original is accessible via getPrevious(). This is a non-issue in practice: nobody can be checking for Error subtypes in the response because they were never caught before. Any existing hasExceptionOfType() usage checks for Exception subclasses, which still pass through unwrapped.

If you need to handle a specific error type, catch it directly in your controller action before it reaches the dispatch boundary.

server fault() methods

instanceof Exception checks in Zend_Rest_Server::fault(), Zend_Soap_Server::fault(), and Zend_XmlRpc_Server::fault() are updated to instanceof Throwable so error details (message, code) are properly extracted instead of falling through to generic "Unknown error" messages.

@falkenhawk

Copy link
Copy Markdown
Member Author

@fredericgboutin-yapla would you please take a look, if this is still relevant to you?

@falkenhawk
falkenhawk marked this pull request as ready for review April 8, 2026 21:31
@falkenhawk
falkenhawk requested a review from partikus April 8, 2026 21:33
PHP 7+ introduced Error classes (TypeError, DivisionByZeroError, etc.) that
extend Throwable but not Exception. These were slipping through catch blocks
in the dispatch chain and server handlers, causing unhandled crashes instead of
being processed by the framework's error handling.

Where the caught throwable is passed to `setException()` (which type-hints
`Exception`), non-Exception throwables are wrapped in the appropriate
framework exception class, preserving the original as `$previous`.

Server `fault()` methods also updated to recognize `Throwable` (not just
`Exception`) so error details are properly extracted.

Closes #201

@partikus partikus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it looks ok, just few thoughts

Comment on lines 913 to +918
if ($this->throwExceptions()) {
throw $e;
}

if (!$e instanceof Exception) {
$e = new Zend_Controller_Exception($e->getMessage(), $e->getCode(), $e);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we decorate before forwarding?

Suggested change
if ($this->throwExceptions()) {
throw $e;
}
if (!$e instanceof Exception) {
$e = new Zend_Controller_Exception($e->getMessage(), $e->getCode(), $e);
}
if (!$e instanceof Exception) {
$e = new Zend_Controller_Exception($e->getMessage(), $e->getCode(), $e);
}
if ($this->throwExceptions()) {
throw $e;
}

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should really Error-s be treated that way, wrapped with Zend_Controller_Exception, even when throwExceptions() is true? I'd rather expect them to be re-thrown as is 🤔

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

heh but on the other hand, in Zend_Controller_Plugin_Broker, i.a. https://github.com/zf1s/zf1/pull/230/changes#diff-51643978e1b538318ad62e0bfe12d049ede90a15231adb3574018f76c9812821L243
all exceptions caught are wrapped with Zend_Controller_Exception, when throwExceptions() is true. 🤡

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i delegated the investigation on this to claude and here are the results:


Should Front.php also wrap before rethrowing when throwExceptions=true?

No, and here's why. The two behaviors are intentionally different in the original ZF1 code:

throwExceptions=true throwExceptions=false
Broker wraps ALL throwables in Zend_Controller_Exception wraps only non-Exception, stores in response
Front rethrows raw wraps only non-Exception, stores in response

The Broker wraps even regular Exception subclasses when rethrowing - it's a normalization layer for plugin code. Front.php never wraps on rethrow - it preserves whatever came through. This is the original design, predating our changes.

If we started wrapping only Error types (but not Exception types) in Front's throwExceptions path, that would be inconsistent - different wrapping rules depending on the exception class hierarchy.

In practice, Errors from plugins never reach Front raw - the Broker wraps them first. The only raw Errors that hit Front directly come from $router->route() or $dispatcher->dispatch() - framework internals where preserving the original type is more useful.

Added tests in 9724f4d covering both paths - plugin errors (wrapped by Broker) and controller action errors (raw TypeError rethrown by Front).

@fredericgboutin-yapla

Copy link
Copy Markdown
Contributor

Looks good to me once we observe the decorators when applicable, as suggested.

@falkenhawk
falkenhawk force-pushed the catch-throwable branch 3 times, most recently from 1fc8973 to ccc60c7 Compare April 10, 2026 16:33
test Plugin Broker with a plugin that throws TypeError:
- throwExceptions=false: response contains Zend_Controller_Exception
  wrapping the original TypeError as $previous
- throwExceptions=true: throws Zend_Controller_Exception wrapping TypeError

test Front controller dispatch with a controller action that throws TypeError:
- throwExceptions=false: response contains Zend_Controller_Exception
  wrapping the original TypeError
- throwExceptions=true: raw TypeError is rethrown (no wrapping,
  because the Broker is not in this path)
@falkenhawk
falkenhawk merged commit d3f6829 into master Apr 13, 2026
11 checks passed
@falkenhawk
falkenhawk deleted the catch-throwable branch April 14, 2026 05:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Front controller won't catch exceptions of type Error

3 participants