SignalHub
Last updated: 2026-11-05
Canvas includes SignalHub, a Qt-inspired signal-slot system for decoupled event handling in PHP. Objects emit signals and connect them to handlers (slots) without tight coupling between components. If you are using signals inside Canvas controllers with @ListenTo auto-wiring, see Signal Wiring instead.
Core Concepts
- Signal — An event source connected to one or more slots. Declared as a typed property on a class and instantiated in the constructor.
- Slot — A wrapper around any callable (closure, method, function) that gives it stable object identity. Signal uses that identity to key connections, manage priorities, and enable explicit disconnection.
- SignalHub — A centralized registry that tracks named signals across the application. Discovers object-owned signals via reflection and supports manually registered standalone signals.
Adding Signals to a Class
Declare public Signal properties and initialize them in the constructor:
use Quellabs\SignalHub\Signal;
class Button {
public Signal $clicked;
public Signal $hovered;
public function __construct() {
$this->clicked = new Signal('clicked');
$this->hovered = new Signal('hovered');
}
public function click(int $x, int $y): void {
$this->clicked->emit($x, $y);
}
} The optional argument to new Signal() is the signal's name, used for hub registration and lookup. Unnamed signals can still be connected and emitted directly, but cannot be registered with the hub as standalone signals.
The Slot Wrapper
A Slot wraps any callable and gives it stable object identity. Signal uses that identity internally to key connections — not the callable itself. PHP closures and method references created from the same expression are distinct objects with no reliable equality, so keying by the Slot instance avoids ambiguity.
use Quellabs\SignalHub\Slot;
$slot = new Slot([$this, 'handleEvent']);
$signal->connect($slot);
$signal->disconnect($slot); // same instance required A single Slot instance may be connected to multiple signals simultaneously. Each signal tracks its own priority for that connection independently. Signal holds a strong reference to each connected Slot, so a slot stays alive for as long as it is connected, regardless of whether the caller holds their own reference. To remove a connection, call disconnect() explicitly.
Connecting Slots
Wrap any callable in a Slot and connect it to a signal using connect():
use Quellabs\SignalHub\Slot;
$button = new Button();
// Closure
$slot = new Slot(function(int $x, int $y) {
echo "Clicked at {$x}, {$y}";
});
$button->clicked->connect($slot);
// Object method
$slot = new Slot([$handler, 'onClicked']);
$button->clicked->connect($slot);
// Static method
$slot = new Slot(['MyClass', 'staticHandler']);
$button->clicked->connect($slot);
// Named function
$slot = new Slot('myHandlerFunction');
$button->clicked->connect($slot); Slots execute in priority order, highest first. The default priority is 0:
$signal->connect($lowPrioritySlot, priority: -10);
$signal->connect($normalSlot); // priority: 0
$signal->connect($highPrioritySlot, priority: 100); Connecting the same Slot instance twice updates its priority rather than creating a duplicate connection. Two separate Slot objects wrapping the same callable are treated as distinct connections.
One-Shot Connections
Use connectOnce() to connect a Slot that disconnects itself right after it runs, so it never fires a second time:
$slot = new Slot(fn(Payment $payment) => $this->sendWelcomeEmail($payment));
$paymentReceived->connectOnce($slot); The disconnect happens before the slot is invoked, so isConnected() already reports false from inside the slot's own callback. It accepts the same priority argument as connect() and still participates in normal priority ordering alongside regular connections. Connecting an already-connected Slot with connectOnce() upgrades the existing connection to one-shot rather than adding a second entry; a once-connection can still be removed early with a plain disconnect() before it ever fires.
Emitting Signals
Call emit() with any arguments you want to pass to connected slots:
$button->clicked->emit(42, 17); Disconnecting Slots
Remove a specific slot from a signal by passing the same Slot instance that was used to connect:
$slot = new Slot([$handler, 'onClicked']);
$button->clicked->connect($slot);
// Later:
$button->clicked->disconnect($slot);
// Returns true if the slot was connected and removed, false otherwise Because Signal keys connections by object identity, you must hold a reference to the Slot instance to disconnect it later. A Slot constructed inline and not assigned to a variable cannot be disconnected.
To remove every connection at once — e.g. when tearing down a signal's listeners without tracking each Slot individually — call disconnectAll():
$button->clicked->disconnectAll(); The SignalHub Registry
The SignalHub provides centralized discovery and management of named signals. Access the application-wide instance via the locator:
use Quellabs\SignalHub\SignalHubLocator;
$hub = SignalHubLocator::getInstance(); Canvas's dependency injection container is aware of SignalHub. Any class that type-hints SignalHub in its constructor receives the application-wide instance automatically — no locator calls needed inside the container.
Discovering Object Signals
Call discoverSignals() to register all Signal-typed properties on an object with the hub. The hub uses reflection to find them, caching results per class so reflection only runs once:
$button = new Button();
$hub->discoverSignals($button); Calling discoverSignals() twice on the same object throws a RuntimeException. All Signal properties must be initialized before discovery — an uninitialized property also throws.
When an object is done (e.g. at the end of a request), unregister its signals explicitly:
$hub->unregisterSignals($button); Because SignalHub stores object signals in a WeakMap, they are garbage collected automatically when the owning object goes out of scope. Explicit unregistration is still recommended so that meta-signal listeners are notified and connections are cleaned up promptly.
Looking Up Signals
Retrieve a signal by name scoped to a specific owner:
// Direct object reference — O(1) lookup
$signal = $hub->getSignal('clicked', $button);
// Class or interface name — scans all registered objects for a match
$signal = $hub->getSignal('clicked', Button::class);
// No owner — searches standalone signals only
$signal = $hub->getSignal('app.ready'); Search for signals using wildcard patterns:
// All standalone signals starting with "data."
$signals = $hub->findSignals('data.*');
// All signals on a specific object instance
$signals = $hub->findSignals('*', $button);
// All signals on any object of a given class or interface
$signals = $hub->findSignals('*', Button::class); One instance per class: The hub expects only one active instance of any given class at a time. When looking up signals by class name,
getSignal()returns the first match found. Register distinct signal names on distinct instances if you need to differentiate them.
Standalone Signals
Signals don't need to belong to an object. Register them directly with the hub for application-wide events:
$appReady = new Signal('app.ready');
$hub->registerSignal($appReady);
// Retrieve and connect from anywhere
$slot = new Slot(function(string $env) {
echo "App started in {$env} mode";
});
$hub->getSignal('app.ready')->connect($slot);
$appReady->emit('production'); A standalone signal must have a name. Registering two standalone signals with the same name throws a RuntimeException. Unlike object signals, standalone signals are not garbage collected automatically — remove them explicitly when no longer needed:
$hub->unregisterSignal($appReady); // Returns true if found and removed Hub Meta-Events
The hub emits its own signals when signals are registered or unregistered. Connect to these to monitor hub activity, implement audit logging, or auto-connect to signals as they appear:
$hub->signalRegistered()->connect(new Slot(function(Signal $signal) {
echo "New signal registered: " . $signal->getName();
}));
$hub->signalUnregistered()->connect(new Slot(function(Signal $signal) {
echo "Signal removed: " . $signal->getName();
})); Meta-events fire for both object signals (via discoverSignals() / unregisterSignals()) and standalone signals (via registerSignal() / unregisterSignal()).
Introspection
Inspect signals at runtime:
$signal->getName(); // 'clicked', or null if unnamed
$signal->countConnections(); // Number of currently connected slots
$signal->isConnected($slot); // True if the given Slot instance is connected Testing
Inject a fresh hub during tests to isolate signal behavior:
// In test setup
SignalHubLocator::setInstance(new SignalHub());
// Reset after test
SignalHubLocator::setInstance(null); Frequently Asked Questions
Why does Signal use a Slot wrapper instead of connecting callables directly?
PHP closures and method references created from the same expression are distinct objects with no reliable equality, so a bare callable can't be used as a dependable key. Wrapping it in a Slot gives it stable object identity, which Signal uses internally to key connections, track per-signal priority, and support explicit disconnection.
Does connecting the same callable twice create two connections?
It depends on whether it's the same Slot instance. Connecting the same Slot object twice just updates its priority rather than duplicating the connection. Two separate Slot objects wrapping the identical callable, though, are treated as two distinct connections — identity is what matters, not the callable itself.
Are object signals cleaned up automatically when the owning object goes away?
Yes, eventually — SignalHub stores object signals in a WeakMap, so they're garbage collected once the owning object goes out of scope. Explicit unregisterSignals() is still recommended, though, since it notifies meta-signal listeners and cleans up connections promptly instead of waiting on garbage collection.
Can signals exist without belonging to any object?
Yes — standalone signals, registered directly with the hub via registerSignal() for application-wide events. A standalone signal must have a name, and registering two with the same name throws a RuntimeException. Unlike object signals, they aren't garbage collected automatically; remove them explicitly with unregisterSignal().
How do I look up a signal when multiple instances of the same class exist?
getSignal('name', Button::class) scans all registered objects and returns the first match, since the hub expects only one active instance of a given class at a time. If you genuinely have several instances and need to tell their signals apart, look them up by direct object reference instead — getSignal('name', $specificInstance) — which is also the faster, O(1) path.
Can I monitor when signals are registered or unregistered hub-wide?
Yes — connect to the hub's own meta-signals, signalRegistered() and signalUnregistered(). They fire for both object signals (via discoverSignals() / unregisterSignals()) and standalone signals (via registerSignal() / unregisterSignal()), useful for audit logging or auto-connecting to signals as they appear.
Does a once-connection still run if I disconnect it right after connecting?
No — connectOnce() creates an ordinary connection that happens to disconnect itself before invocation; calling disconnect() on it beforehand removes it like any other connection, so it never fires at all.
Is there a quick way to remove every listener from a signal?
Yes — disconnectAll() clears every connected Slot in one call, which is useful when tearing down a signal's listeners without having kept a reference to each one individually.