Add support for named queries and plugin hook in elgg_get_entities

[mrclay]

There are often situations where one needs to alter the entities query in a page of another plugin. E.g. changing members list to alpha order, choosing a larger limit, or applying an ElggCollection to implement sticky discussion topics.

Currently one has to completely fork the page code to do these things. I propose that elgg_get_entities accept an option "query_name". If passed in, $options would be passed through a plugin hook [Error: Query filter requires field and constraints separated by a "="]. This of course doesn't enable altering plugin queries until query names are added to the plugins, but this would be relatively easy.

[mrclay]

Wiki format fail! The plugin hook name would be something like query:alter_options and query_name would be the type.

[ewinslow]

Would this need go away if we made page handler scripts easier to override?

[mrclay]

I can already override routes via plugin hook to intercept individual pages, but as a plugin dev I'd rather not have to take over full page building responsibility (or copy/paste a bunch of code) just to alter a query.

[ewinslow]

OK, I think I can appreciate the benefits of this. It would allow for simple things like changing the default limit for certain queries without overriding the whole page. I'm also thinking of something like river comments -- a plugin could change it to show 5 instead of 3 without having to override the whole view.

I'd still like to see a few more concrete examples before we dive right in and add an API to a low-level function like that. Are there any possible bad side effects if we go this route?

[mrclay]

How about two hooks named: query:entities:before (passing $options through) and query:entities:after (passing back $options, raw data rows, an array of GUIDs returned, and passing through the entities).

By looking at $options['query_name'], a particular query can be modified, and the after hook would serve use cases described in #4296.

[mrclay]

I think the addition of collections will provide the bulk of use cases; adding ordering to widgets on profile pages, sticky discussion topics/blog posts, etc. With the before hook this should be implementable without modifying any core mods.

Bad side effects include exposing low-level functionality to plugin devs, but having this all through hooks makes it a little less-coupled; we can stop triggering hooks if there's a need to break BC...

[brettp]

This makes me uncomfortable. We always encourage plugin devs to use the built in API and not drop to raw SQL. If we adopt these changes, we'd have to consider the SQL as a public API and the same restrictions would apply to it as other public APIs. That's a pretty big investment to promise we won't change SQL queries between bugfix releases.

[brettp]

Ignore the above. I somehow missed that this only passed the options array. I'm fine adding this, with the assumption it's only for "named" calls and that the raw SQL is never able to be changed.

[mrclay]

Current state of this: I've outlined the basic idea ​in this blog post, and have a ​NamedQuery class that wraps up the hook triggering.

Consider you want to list entities and give plugins the ability to alter the options:

$q = new ElggNamedQuery('pages:listing', array(
    // options
));
$listing = elgg_list_entities($q->getOptions());

However, I'm returning to the opinion that using this class inside ege() would be better. API:

$listing = elgg_list_entities(array(
    // options
    'query_name' => 'pages:listing',
));

• Allowing the extension of your options is dead easy, no learning about query modifier classes
• The query mod classes don't have to be public API