WordPress.org

Make WordPress Core

Opened 2 years ago

Closed 16 months ago

#43304 closed enhancement (fixed)

Data type of deprecated parameter of load_plugin_textdomain function should be bool and not string

Reported by: sudar Owned by: SergeyBiryukov
Milestone: 5.2 Priority: low
Severity: minor Version:
Component: I18N Keywords: has-patch
Focuses: docs Cc:

Description

The second parameter of the load_plugin_textdomain function has been deprecated. The default value of this parameter is set to false and if we pass anything other than false, then a deprecated notice is triggered.

<?php
        if ( false !== $plugin_rel_path ) {
                $path = WP_PLUGIN_DIR . '/' . trim( $plugin_rel_path, '/' );
        } elseif ( false !== $deprecated ) {
                _deprecated_argument( __FUNCTION__, '2.7.0' );
                $path = ABSPATH . trim( $deprecated, '/' );
        } else {
                $path = WP_PLUGIN_DIR;
        }

But in the phpdoc block of this function the second parameter is still specified as string. But in practise the only value that can be passed to this function that does not trigger a deprecated warning is false.

This generates a error in lot of static code analysers/services like scrutinizer that deduces the data type of the parameter from phpdoc block.

The data type of the parameter should be changed to either bool or should be explicitly stated as false (even better)

Attachments (4)

43304.diff (807 bytes) - added by sudar 2 years ago.
Patch to fix the phpdoc blcok
43304.1.patch (806 bytes) - added by hardik2221 2 years ago.
43304.2.patch (807 bytes) - added by hardik2221 2 years ago.
43304.2.diff (1.2 KB) - added by sudar 16 months ago.

Download all attachments as: .zip

Change History (14)

@sudar
2 years ago

Patch to fix the phpdoc blcok

#1 @hardik2221
2 years ago

  • Focuses administration added
  • Keywords has-patch added

I have made changes to existing patch.

@hardik2221
2 years ago

#2 @sudar
2 years ago

@hardik2221 Any specific reason for changing it from false to bool?

Also in your patch the @param statements are not aligned.

#3 @hardik2221
2 years ago

I think it is the parameter type bool where it will take the value true or false.

@hardik2221
2 years ago

#4 @SergeyBiryukov
2 years ago

  • Milestone changed from Awaiting Review to 5.0

#5 @pento
22 months ago

  • Milestone changed from 5.0 to 5.1

#6 @swissspidy
19 months ago

  • Milestone changed from 5.1 to Future Release
  • Priority changed from normal to low
  • Severity changed from normal to minor
  • Type changed from defect (bug) to enhancement
  • Version trunk deleted

It's still possible to pass a string to $deprecated, so the docblock is technically correct. It's just so that in WordPress we often use false as a default value when we expect other data types otherwise.

If anything I'd annotate it as string|false, but I don't see it as a pressing problem.

#7 @swissspidy
18 months ago

  • Focuses administration coding-standards removed

@sudar
16 months ago

#8 @sudar
16 months ago

@swissspidy

If anything I'd annotate it as string|false,

I have added a new patch that changes the param type to string|false instead of just false.

but I don't see it as a pressing problem.

Here is a usecase that prompted me to create this ticket and also submit the patch.

I am using load_plugin_textdomain function in a plugin and I have to use set a value for the 3rd parameter, which means I have to explicitly set the second parameter to false.

Now when I set the second parameter to false both the IDE and static code analyser starts to flag the function call saying that a bool value is passed to string parameter.

I agree that it may not be a pressing problem, but it is still a minor annoyance for all the developers who have to use the call the function and specify the 3rd parameter.

#9 @SergeyBiryukov
16 months ago

  • Milestone changed from Future Release to 5.2

#10 @SergeyBiryukov
16 months ago

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

In 45254:

Docs: Correct @param type for $deprecated and $plugin_rel_path arguments of load_plugin_textdomain().

Props sudar.
Fixes #43304.

Note: See TracTickets for help on using tickets.