Wrong PHPDoc wp_get_active_and_valid_plugins

[herrvigg]

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.

[sebastienserre]

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"

[herrvigg]

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]

[herrvigg]

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'.

[herrvigg]

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.

[azouamauriac]

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].

Trac Ticket: Core-49599

## Overview

• This pull request aims to improve the documentation for the wp_get_active_and_valid_plugins() function in wp-includes/load.php. The current documentation incorrectly states that the function returns paths to plugin files "relative to the plugins directory." This wording can lead to confusion, as the function actually returns absolute paths to the active plugin files.

## Changes Made

• Updated the @return annotation in the function's documentation to clarify that it returns an array of absolute paths to plugin files.

• Added a note explicitly stating that these paths are not relative to the plugins directory.

## Rationale

• Providing accurate documentation is crucial for developers using the WordPress API. By clearly indicating that the paths returned by this function are absolute, we can help prevent potential confusion and errors when developers attempt to work with plugin paths. This change aligns with the actual functionality of the method and enhances the overall clarity of the API documentation.

## Impact

• This change is purely a documentation update and will not affect existing functionality or backward compatibility. It aims to provide clearer guidance to developers, thereby improving their experience when working with WordPress plugins.