Signal Wiring
Last updated: 2026-10-28
Canvas automatically discovers signals on controllers and aspects and wires them to listener methods declared with @ListenTo annotations. A Signal is an object that emits data to interested listeners identified by a shared signal name. No manual registration is required in application code. Signals are inspired by the Qt signal/slot model. For the underlying Signal/Slot API — connecting slots manually, priorities, and the SignalHub registry — see SignalHub.
Declaring Signals on a Controller
Declare public Signal properties and give each an explicit name. The name is the contract that listeners use to identify which signals they handle:
use Quellabs\SignalHub\Signal;
class MollieController extends BaseController {
public Signal $paymentPaid;
public Signal $paymentFailed;
public function __construct() {
$this->paymentPaid = new Signal('mollie.payment.paid');
$this->paymentFailed = new Signal('mollie.payment.failed');
}
/**
* @Route("/webhook/mollie")
*/
public function webhook(Request $request): Response {
$payment = $this->mollie->payments->get($request->get('id'));
if ($payment->isPaid()) {
$this->paymentPaid->emit($payment, 'hello');
} else {
$this->paymentFailed->emit($payment);
}
return new Response('OK');
}
} Declaring Signals on an Aspect
Aspects can declare signals the same way controllers do. Canvas discovers signals on all aspects applied to the current controller method. This allows reusable cross-cutting concerns — such as rate limiting, authentication, or tracking — to communicate with the rest of the application without coupling to any specific controller.
Creating Signal Listeners
A signal listener wires listener methods to signals using @ListenTo annotations. Canvas recursively discovers listener classes inside /src/Listeners, though the discovery location can be changed in app.php. Listener constructors support dependency injection through autowiring.
Alternatively, @ListenTo annotations can be placed directly on methods of the current controller, allowing controllers to respond to signals without a dedicated listener class.
Values passed to emit() are forwarded to listener method parameters in the same order they are provided. Multiple arguments are supported, and parameter types are not enforced by the signal system.
namespace App\Listeners;
use Quellabs\Canvas\Annotations\ListenTo;
class PaymentListener {
/**
* @ListenTo("mollie.payment.paid")
*/
public function onPaymentPaid(mixed $payment, string $message): void {
$this->logger->onPaymentPaid($payment, $message);
}
/**
* @ListenTo("mollie.payment.failed")
*/
public function onPaymentFailed(mixed $payment): void {
$this->invoiceService->onPaymentFailed($payment);
}
} Signal Lifecycle
Signals are scoped to the request lifetime. They are available only during the current request. Canvas discovers and initializes signals on both the controller and all active aspects before execution, and cleans them up automatically afterward — including when exceptions occur. No manual cleanup is needed in application code.
Frequently Asked Questions
Do I need to manually register signal listeners?
No. Canvas recursively discovers listener classes inside /src/Listeners (the location is configurable in app.php) and wires their @ListenTo-annotated methods automatically. You can also skip a dedicated listener class entirely and place @ListenTo directly on a method of the controller that owns the signal.
Can aspects emit signals, or only controllers?
Both. Canvas discovers signals on all aspects applied to the current controller method, the same way it discovers them on the controller itself — which lets a reusable cross-cutting concern like rate limiting or authentication communicate with the rest of the application without being coupled to any specific controller.
How do arguments passed to emit() reach the listener method?
Positionally, in the same order they're passed to emit(). Multiple arguments are supported, and the signal system doesn't enforce parameter types — whatever a listener's signature declares is what it receives, so keep emitter and listener argument order in sync.
Do I need to clean up signals after a request?
No. Signals are scoped to the request lifetime — Canvas initializes them before execution and cleans them up afterward automatically, including when an exception occurs partway through. There's no manual teardown to write.
What's the difference between a dedicated listener class and @ListenTo on a controller method?
A dedicated class in /src/Listeners supports constructor dependency injection through autowiring and keeps listener logic separate from the controller that emits the signal. Putting @ListenTo directly on a controller method skips that separation when a signal only needs a quick, local reaction within the same controller.
How does Signal Wiring relate to SignalHub?
SignalHub is the underlying Signal/Slot API — connecting slots manually, priorities, and the registry. Signal Wiring is the annotation-driven layer on top of it: @ListenTo handles discovery and connection automatically, so most application code never calls SignalHub's manual connection API directly.