Development and debugging tools for Recoil applications.
composer require --dev recoil/dev
Primarily, recoil/dev is a Composer plugin that automatically instruments
coroutine functions to provide meaningful stack traces in the event of an
exception. Without recoil/dev, stack traces tend to show details about the
internals of the Recoil kernel, rather than the coroutines it is executing.
Instrumentation is performed automatically, by plugging in to the autoload pipeline. For most use cases no change is required in your code (other than the note below), and you should immediately see more usable stack traces.
The instrumentor identifies functions as coroutines if they have a return type
hint of Coroutine, where Coroutine is an alias for Generator, for example:
// Alias Generator as Coroutine.
use Generator as Coroutine;
function doNothing(int $value): Coroutine // Mark function as a coroutine.
{
yield;
}The instrumentor will not instrument functions that use a return type hint of
Generator, as without the alias it has no way to distinguish between an actual
coroutine and a regular generator function.
Check the following:
- Ensure that assertions are enabled on your development environment.
- Ensure that your coroutines are explicitly identified using
: Coroutinetype hint, as described above. - Syntax errors in your source files may break the PHP parsing used to generate instrumentation, leaving those files uninstrumented -- check your syntax!
- For further issues with autoload, or to disable instrumentation, see these further notes.
Please see CONTRIBUTING.md for information about running the tests and submitting changes.