Documentation on stop events and redirects

[mirko-pagliai]

There is nothing in the documentation about stopping events when used with redirects.

Here (Controllers) we find a link to stopping events:
https://book.cakephp.org/5/en/controllers.html#controller-callback-methods

Which then leads to this section:
https://book.cakephp.org/5/en/core-libraries/events.html#stopping-events

Moreover, I found this (Components):
https://book.cakephp.org/5/en/controllers/components.html#using-redirects-in-component-events
So actually there is something, but it is probably (?) an obsolete example and described in relation to the components only.
Even in the upper section, there is probably something obsolete (see description for beforeRedirect, where it says it can return false)

In my opinion, instead, something like this should be documented:

public function beforeFilter(EventInterface $event): void
{
    if ($needsStopAndRedirect) {
        $event->stopPropagation();

        $this->redirect('/');

        return;
    }

    //This code should be executed only if `$needsStopAndRedirect` is false
    // ...
}

Also because I'm not sure that this is the correct procedure either.

[dereuromark]

The docs need to be updated indeed

    $event->setResult($this->redirect(...));

    return;

Is all that is needed

[mirko-pagliai]

@dereuromark is this ok?

Even in the upper section, there is probably something obsolete (see description for beforeRedirect, where it says it can return false)

It's here

[dereuromark]

StopPropagation is only needed in cases where there is no clear value to be set.

And no, always void.

[LordSimal]

cakephp/cakephp#16854

[dereuromark]

Anything missing?
#8045

[mirko-pagliai]

Thank you as usual.

If

And no, always void.

Maybe this section should be revised too?

Also, could it be useful to explicitly specify the return void for anonymous functions as well (a little further up)?
Example:

$this->Orders->getEventManager()->on('Order.afterPlace', function ($event) {

this however could be excessive for the documentation and perhaps too much.

I apologize if I don't do any PR myself, but I'm here because the thing isn't/wasn't very clear to me either.

[mirko-pagliai]

Again.

Perhaps here too it would be appropriate to make it clear that any values ​​should be tested with setResult()/getResult()?

Maybe postponing reading this?

But here too I see this example:

// A listener callback
public function doSomething($event)
{
    // ...
    $alteredData = $event->getData('order') + $moreData;

    return $alteredData;
}

// Another listener callback
public function doSomethingElse($event)
{
    // ...
    $event->setResult(['order' => $alteredData] + $this->result());
}