Make WordPress Core

Opened 4 years ago

Closed 4 years ago

#52243 closed enhancement (fixed)

Rename `$this` when used in `@param` tags

Reported by: johnbillion's profile johnbillion Owned by: johnbillion's profile johnbillion
Milestone: 5.7 Priority: normal
Severity: normal Version:
Component: Plugins Keywords: has-patch
Focuses: docs Cc:

Description

Several filters and actions pass $this as a parameter. $this is a pseudo-variable that cannot be used as the name of a function parameter.

I've identified a few problems caused by using $this as the name of a parameter for actions and filters:

  • Inexperienced developers may copy and paste the list of parameters from the apply_filters() call or from the developer.wordpress.org site when adding their filter and then experience a fatal error
  • Developer tools that consume filter and action docblocks, for example code generators, have to rename $this to avoid the same
  • PHPStan and other static analysis tools report $this as invalid when used in a @param tag

Usage of $this in @param tags for actions and filters should be replaced with a more appropriate variable name.

Attachments (1)

52243.diff (37.6 KB) - added by johnbillion 4 years ago.

Download all attachments as: .zip

Change History (6)

@johnbillion
4 years ago

#1 @johnbillion
4 years ago

  • Keywords has-patch added

#2 @audrasjb
4 years ago

Hi John, great point!

Maybe we may also want to provide more descriptive params for functions/hooks that are passing $array.
I found few occurrences, for example:

In class-requests.php

/**
 * Convert a key => value array to a 'key: value' array for headers
 *
 * @param array $array Dictionary of header values
 * @return string[] List of headers
 */
public static function flatten($array) {

Or maybe you'll prefer this to be another ticket :)

#3 @johnbillion
4 years ago

Yes that's a good idea too. Can you open another ticket please?

#4 @audrasjb
4 years ago

Sure!

#5 @johnbillion
4 years ago

  • Owner set to johnbillion
  • Resolution set to fixed
  • Status changed from new to closed

In 49946:

Plugins: Replace usage of $this in action and filter parameter docblocks with more appropriate variable names.

See #51800, #52217

Fixes #52243

Note: See TracTickets for help on using tickets.