Add optional callback argument to stopListening()

[larsnystrom]

(Second attempt, see #291)

This makes it possible to unregister a single callback for an event, without unregistering all other callbacks for that event on that channel. This is very helpful for example when using react hooks, where you need to stop listening as the component is unmounted. Here's an example React component using this new functionality:

const MyEventMessagesList = () => {
    const [messages, setMessages] = useState([]);

    useEffect(() => {
        const pushMessage = message => setMessages(prev => [...prev, message]);
        const channel = Echo.private("my.channel")
            .listen("MyEvent", pushMessage);

        // It used to be impossible to unregister a single callback
        // for an event, but now you can do this:
        return () => channel.stopListening("MyEvent", pushMessage); // Unregister only the pushMessage callback for this event
    }, [setMessages]);

    return (
        <ul>
            {messages.map((m, i) =>
                <li key={i}>{m}</li>
            )}
        </ul>
    )
}

Prior to this PR it was not possible to unregister a callback for an event. This is because the callback was wrapped inside the channel class to filter out events from other channels (see

echo/src/channel/socketio-channel.ts

Line 112 in 8bd9a2b

let listener = (channel, data) => {

). It was therefore impossible to map the callback the user provided when calling channel.listen() to the callback which was actually registered with the socket. This in turn meant it was not possible to selectively remove just that callback from the socket.

I have solved this by registering just one callback per event, which in turn iterates over a list of user-provided callbacks. The list of user-provided callbacks can therefore be modified, and a single user-provided callback can be selectively unregistered.

I've added a few tests for the socket.io channel because the new code is a bit more complex than it used to be.

I have tried to not introduce any backwards incompatible changes here. That's why there's still an channel.on() function, despite it just proxying to the new channel.bindChannelEvent. All new functions has been marked as protected to discourage consumers of this package to call them directly. New properties have been marked as private.

This PR also fixes a bug in the socket.io channel, where calling stopListening(event) would stop the socket from listening to that event for all channels, not just the current one. If you look at this line:

echo/src/channel/socketio-channel.ts

Line 84 in 8bd9a2b

this.socket.removeListener(name);

you'll see that all listeners are removed for that event on the underlying socket, not just the listeners specific to this channel (since all channels share the same socket). This PR solves that by always keeping track of which callbacks have been registered with the socket, and unregistering just those.

[taylorotwell]

What is an event and what is a "channel event"?

[taylorotwell]

The order of the methods in the PR seems all weird. Can the methods be placed in a more logical order?

[larsnystrom]

What is an event and what is a "channel event"?

I have changed the PR now, so there are two props on SocketIoChannel: events and listeners. The events are callbacks applied to the socket given some event name. This means they are executed for every event with that name, regardless of which channel the event was sent to. The listeners are user-supplied callbacks, and they are only executed for the given event and on the given channel.

The order of the methods in the PR seems all weird. Can the methods be placed in a more logical order?

I have now split the PR in two commits, which has simplified the SocketIoChannel by moving some responsibility to SocketIoConnector. The result is that there is just one new method at the end of SocketIoChannel. I hope this makes the changes I've made more clear.

[larsnystrom]

I changed the return type of this method to be analogous to PusherChannel.on(). I'm not sure if that was a good idea or not.

[taylorotwell]

I guess I'm confused - why this difference between events and listeners is even needed at all? Does Echo let you listen to events with a given name across all channels?

[taylorotwell]

I think I understand the reasoning now. I have released this as Echo 1.10.0. Thanks.