Automattic / Automattic/VIP-Coding-Standards
Check the hook callback parameter count ?
- Vorherrschende Sprache
- PHP
- Sterne
- 261
- Forks
- 44
- Ø Merge
- 19 Min.
- Gemergte PRs (30 T.)
- 1
Beschreibung
## What problem would the enhancement address for VIP?
Prevent potential fatal `ArgumentCount` errors.
## Describe the solution you'd like
Inspired by the `AlwaysReturnInFilter` sniff, I was thinking that once the abstract hook/callback sniff exists, it wouldn't be that hard to create a sniff which would check synchronicity between the parameters requested from a hook-in and the callback function declaration.
This would apply to both `add_filter()` as well as `add_action()`.
Such a sniff would also be a candidate for (eventually moving to) WPCS, but I wanted to discuss the general idea here first, largely to see if the potential issue described above actually occurs in real life situations.
## What code should be reported as a violation?
```php
// Error: Two parameters expected, one (implicit) requested.
add_filter( 'the_title', function( $title, $id ) {
// Do something.
return $title;
} );
// Warning: One parameter expected, two requested.
add_filter( 'the_title', function( $title ) {
// Do something.
return $title;
}, 10, 2 );
```
## What code should *not* be reported as a violation?
```php
// OK: Two parameters expected, two requested.
add_filter( 'the_title', function( $title, $id ) {
// Do something.
return $title;
}, 10, 2 );
// OK: Three parameters expected, two requested, but third parameter is optional,
// which can be done by design to allow direct calls to the function to pass it.
function prefix_title_filter( $title, $id, $optional = null ) {
// Do something.
return $title;
}
add_filter( 'the_title', 'prefix_title_filter', 10, 2 );
```
## Additional context
### Future scope
* Once a list of WP native hooks + the amount of parameters they pass is known (via a trait in WPCS for instance), an additional check could be added that the `$accepted_args` parameter value is never higher than the number of passed parameters when the hook is called.
```php
function prefix_title_filter( $title, $id, $optional = null ) {
// Do something.
return $title;
}
// The `the_title` filter only passes two arguments max, so the code here is an error.
add_filter( 'the_title', 'prefix_title_filter', 10, 3 );
```
* For PHP native functions used in callbacks, reflection could be used to see how many (required) parameters these take and match that with the `$accepted_args` parameter.
* For WP native functions a list based solution would be needed to do the same.
## Relevant links
* https://developer.wordpress.org/reference/functions/add_action/
* https://developer.wordpress.org/reference/functions/add_filter/
Beitragsleitfaden
Rechercherichtung
Beginnen Sie mit der Überprüfung des vorhandenen AlwaysReturnInFilter-Sniffs sowie der in den verlinkten WordPress-Referenzen dokumentierten Einstiegspunkte add_filter() und add_action(). Klären Sie, wie Callback-Deklarationen und accepted_args verglichen werden sollten, einschließlich optionaler Parameter und Closures, bevor Sie den Umfang des Sniffs festlegen. Die Aufgabe ist abgeschlossen, wenn das Verhalten für die bereitgestellten Beispiele für Verstöße und Nichtverstöße spezifiziert ist.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- php
- Bereich
- tooling
- Issue-Typ
- Feature
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Veraltet
- Klarheit
- Muss geklärt werden
- Anfängerfreundlichkeit
- 25/100