Make WordPress Core

Opened 4 years ago

Last modified 2 years ago

#49599 new defect (bug)

Wrong PHPDoc wp_get_active_and_valid_plugins

Reported by: herrvigg's profile herrvigg Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version: 5.3.2
Component: Plugins Keywords: 2nd-opinion needs-patch
Focuses: docs Cc:

Description

I found a misleading error in the documentation of wp_get_active_and_valid_plugins (in wp-includes/load.php):

<?php
* @return string[] $plugin_file Array of paths to plugin files relative to the plugins directory.
*/ 
function wp_get_active_and_valid_plugins() {

This is wrong, the plugin files are returned as absolute path - not relative. The files are returned as follows:

<?php
$plugins[] = WP_PLUGIN_DIR . '/' . $plugin;

This is not very consistent with the rest of the API working rather with relative paths, but changing the code would break many plugins for sure. The documentation should be updated.

Change History (5)

#1 follow-up: @sebastienserre
4 years ago

Hello,
I'm not sure but I think it did not say that it's a relative path but that the returned path is relative to the plugin path. With relative in sense of "concern"

#2 in reply to: ↑ 1 @herrvigg
4 years ago

Uh ... what? The function concerns plugins so it's obvious it's related to plugins... But related does not mean relative. I think you are doing a confusion with the semantics.

Here it's quite clear it should concern the paths. What would "relative to the plugin directory" mean, if not relative to WP_PLUGIN_DIR? Either you speak about absolute path or relative path with respect to WP_PLUGIN_DIR. Any other definition of "relative" is really not intuitive at all and it's just creating some confusions.

Already the concept of 'plugin name' is quite confusing (combining dir/file.php), but functions such as is_active_plugin($plugin) take the relative path, as defined from WP_PLUGIN_DIR. The API would gain to be more consistent, but at least the documentation should be clear.

[Correction: my first example which was wrong, as `plugin_basename($file)` take absolute path and give the relative path]

Last edited 4 years ago by herrvigg (previous) (diff)

#3 @herrvigg
4 years ago

Sorry i even managed to mix everything up in my example with plugin_basename... which is actually taking the absolute path, not relative which is the result (!). So i've corrected my comment.

But here is a clear example of "relative path":
https://developer.wordpress.org/reference/functions/is_plugin_active/

is_plugin_active( string $plugin )
Determines whether a plugin is active.

$plugin
(string) (Required) Path to the plugin file relative to the plugins directory.

"Relative to the plugins directory" means $plugin is expected to be e.g. 'jetpack/jetpack.php'.

Last edited 4 years ago by herrvigg (previous) (diff)

#4 @herrvigg
4 years ago

Said differently, if you give a path returned by wp_get_active_and_valid_plugins and send it to is_plugin_active you won't get the result you expect, though the documentation both refers as "relative to the plugins directory".

So this is wrong, i believe wp_get_active_and_valid_plugins should in fact return relative paths as the doc claims... but as said, this would break many things... so the easiest fix for now is surely to correct the documentation.

#5 @azouamauriac
2 years ago

  • Keywords 2nd-opinion needs-patch added

Hello there thanks for the report, I think you right, but let's ask second opinion and may be a patch; or do you have any suggestion please?

this doc's comment was introduced here [42787].

Note: See TracTickets for help on using tickets.