[5.x] Add hook to query on entries listing

[duncanmcclean]

This pull request adds a hook that allows developers to modify the query used to return entries for the entries listing table.

Here's a super simple example of how you might use it to only display a user's posts on the news collection, which could go hand in hand with a policy:

use Statamic\Hooks\CP\EntriesIndexQuery;

EntriesIndexQuery::hook('query', function ($payload, $next) {
    if ($payload->collection === 'news') {
        $query->where('author', User::current()->id());
    }

    return $next($payload);
});

Closes statamic/ideas#591.

[ryanmitchell]

I think we'd need some way of knowing what collection this was for, as you'd want to apply it conditionally, not on every index query.

Maybe the hook could be renamed per collection. eg pages:index-query, or alternatively it could pass a DTO but thats a bit yuck.

[jasonvarga]

I've made a generic Payload DTO with some magic so it's a bit easier to work with. Pass an array, it uses the DTO and you can access the keys with property access.

You can now use

$this->runHooksWith('name', ['array' => 'of', 'payload' => 'stuff'])

then your hooks can be like:

Whatever::hook('name', function ($payload, $next) {
  // getters
  $payload->array;
  $payload->stuff;

  // setters
  $payload->stuff = 'changed';

  return $next($payload);
});

The way you'd actually set up this would be something like this:

use Statamic\Hooks\CP\EntriesIndexQuery;

EntriesIndexQuery::hook('query', function ($payload, $next) {
    if ($payload->collection === 'blog') {
        $payload->query->where('foo', 'bar');
    }

    return $next($payload);
});