[#46687] - Make consistent the names of plugin event arguments.
- New
- Medium
- Build: 6.0
- # 46687
With the advent of concrete classes for plugin events, getter functions have been provided to access the arguments easily. For example, for the onAfterInitialise event with the concrete class Joomla\CMS\Event\Application\AfterInitialiseEvent you can use $event->getApplication() to get the Application instance passed as an argument.
However the names of the getter functions don't always match the name of the arguments you get by calling $event->getArguments(), which for AfterInitialiseEvent returns the argument as 'subject' rather than 'application'.
In particular there are lots of instances where 'subject' is passed as an argument, and from the events I've looked at 'subject' can be:
- an Application instance
- a Form instance
- a Table instance
- a Module instance
- an article or contact item
- an array of primary keys
So consumers of the interfaces have no idea what 'subject' actually is and it's pretty useless as an argument name.
So this change request is to address this and provide consistency between the argument names and getter functions. It would mean changing code such as
$this->dispatchEvent(
'onAfterInitialise',
new AfterInitialiseEvent('onAfterInitialise', ['subject' => $this])
);
to
$this->dispatchEvent(
'onAfterInitialise',
new AfterInitialiseEvent('onAfterInitialise', ['application' => $this])
);
This would provide consistency between the argument name returned by $event->getArguments() and the $event->getApplication() call.
The main problem is with the 'subject' argument, but there are probably other cases where the naming is inconsistent, eg for onBeforeExtensionBoot the second argument is 'type' but the getter function is actually $event->getExtensionType().
I realise this is likely to be a breaking change which would need to be made in a major release; it would be worth it to consider how to make things as easy as possible for consumers.
| Labels |
Removed:
?
|
||
joomla-cms-bot
- | Labels |
Added:
No Code Attached Yet
|
||
richard67
- | Labels |
Added:
Feature
|
||
I raised this CR really to try and get an agreed strategic approach to naming of plugin event arguments, and I would argue that the best approach is to have
-
argument names which are informative - that reflect what is being passed
-
consistency between where the event is triggered (arguments passed to the event constructor), and where it's consumed in the plugin (getter functions used in plugins).
If we can agree on that aim then the question is how to get there. (I am a believer in the API-first design principle!).
The use of 'subject' everywhere is uninformative - it's like defining a function signature where the first parameter is called "first_parameter". It tells consumers of the function nothing about what is passed.
So defining a getSubject() getter is actually the wrong thing to do - it just reinforces something that we should really get rid of.
As an alternative approach, would something along the following lines be possible?
Support the triggering of events using meaningful argument names instead of 'subject', as
$this->dispatchEvent(
'onAfterInitialise',
new AfterInitialiseEvent('onAfterInitialise', ['application' => $this])
);
To do this the code would have to recognise that 'application' is replacing 'subject', and would have to return the 'application' value if someone called $event->getArgument('subject'); or used PHP Array Access to get the 'subject'.
Also $event->getArguments() would have to include a 'subject' element at the end of the array - this would be a change to the current return value of $event->getArguments() - there would be 1 more element that currently returned - but might be ok.
If people were getting the arguments using
[$context, $item, $params, $page] = array_values($event->getArguments());
then I that should still be ok. If the 'subject' argument is the last element in the array then it just gets ignored in the above.
During Joomla 6 change where events are triggered to use what are deemed to be the best argument names.
Then in Joomla 7 (or at some major revision in the future) remove the code which creates the pseudo 'subject' argument.
And do a similar thing for any arguments where the getter doesn't match the input argument name where the event is triggered (like 'type' in onBeforeExtensionBoot and onAfterExtensionBoot)
This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/46687.
We can also just create a
getSubject()getter.This will remove confusion and be simpler change that will work for whom want it :)