Update return types to reflect the real return types. Remove mixed.

[ReneHermi]

In the DocBlocks, we document return values with mixed only.

That is no good practice as it does not show the real available and possible return types.
A better approach is to declare and document explicitly return values separated by a pipe character like this @return bool|string

That is much clearer because developers do not need to check the return values by reading the entire docBlock, reading the whole code of a method, or reading the (lengthy) function description under developer.wordpress.org.

A simplemixed is outdated and makes it hard for every severe developer to start with coding for WordPress as he has to continually check the expected return values when there is a mixed.

As a bonus, the documentation under developer.wordpress.org will be updated as well by this change automatically. It will help developers getting know the correct return values immediately from the docs without reading all the extra special explanations that we added to our docs whenever we use mixed.

That is a huge time saver and makes it much faster for every developer to write solid and better code faster.

If this is accepted for core, I will offer to work on this on all other methods as well.

That will be a long-lasting process due to the number of functions, but it's definitely worth the effort. We should make this change to all methods where we usemixed and make it to our daily little take-care moment when we add new methods to WordPress.

Sample Patch by using get_option() as an example for all methods that use mixed:
​https://github.com/WordPress/wordpress-develop/pull/523

get_option() is a special case, though as it automatically unserializes. So it supports all non-scalar types. Most other methods in WordPress uses mixed with only two return types like bool|string representation, which makes the updates easier.

In the DocBlocks, we document return values with mixed only.

That is no good practice as it does not show the real available and possible return types.
A better approach is to declare and document explicitly return values separated by a pipe character like this @return bool|string

That is much clearer because developers do not need to check the return values by reading the entire docBlock, reading the whole code of a method, or reading the (lengthy) function description under developer.wordpress.org.

A simplemixed is outdated and makes it hard for every severe developer to start with coding for WordPress as he has to continually check the expected return values when there is a mixed.

As a bonus, the documentation under developer.wordpress.org will be updated as well by this change automatically. It will help developers getting know the correct return values immediately from the docs without reading all the extra special explanations that we added to our docs whenever we use mixed.

That is a huge time saver and makes it much faster for every developer to write solid and better code faster.

If this is accepted for core, I will offer to work on this on all other methods as well.

That will be a long-lasting process due to the number of functions, but it's definitely worth the effort. We should make this change to all methods where we usemixed and make it to our daily little take-care moment when we add new methods to WordPress.

Sample Patch as an example for all methods that use mixed:

get_option() is a special case, though as it automatically unserializes. So it supports all non-scalar types. Most other methods in WordPress uses mixed with only two return types like bool|string representation, which makes the updates easier.

Trac ticket: https://core.trac.wordpress.org/ticket/51278#ticket

[johnbillion]

Thanks for the ticket and the PR @ReneHermi .

There's been quite a bit of work done to remove mixed types in docs over recent releases. See #50768 and its predecessors, and related tickets such as #41756.

I agree that continuing this work makes sense when listing the types really helps the developer. I don't think that @return bool|string|array|object for the get_option() function specifically is much more useful than @return mixed. In addition, the filter on its return value and the recent addition of a default value in #43941 means this function can return a value of any type, including integer, float, etc.

That said, there's over 100 other instances and I'm sure many of those would benefit from more accurate types! So yes, let's replace mixed with proper types when it makes sense to do so.

[ReneHermi]

Agree, it's counterproductive to list all available PHP types. I've updated the PR to make this more clear that any data type can be returned.

[johannadevos]

Having read this discussion and having inspected the ​accompanying PR, I would say it is ready to be merged:

• The ​feedback from @johnbillion has been taken into account.
• An alternative description has been provided.

[johnbillion]

In 49600:

Docs: For clarity, add some information about the return types of get_option().

Props ReneHermi, johannadevos

See #51278

[azaozz]

[49600] is a good addition but there are some "gotchas" there which are worth documenting more, imho. Most importantly that options are always saved as strings in the DB. Example:

add_option( 'my_test_option__false', false );
add_option( 'my_test_option__true', true );
add_option( 'my_test_option__0', 0 );
add_option( 'my_test_option__1', 1 );
add_option( 'my_test_option__str_0', '0' );
add_option( 'my_test_option__str_1', '1' );

Then doing var_dump( get_option( 'my_test_option...' ) ); will output:

string(0) ""
string(1) "1"
string(1) "0"
string(1) "1"
string(1) "0"
string(1) "1" 

This is especially important (big back-compat "gotcha") for PHP 8.0 as string to number comparison was changed there, see: https://core.trac.wordpress.org/changeset/48960.

There's already: Any scalar values will be returned as strings. but having some examples would be better :)

[johnbillion]

Agreed, this can be improved further. Worth noting that get_option() does return correctly typed values for a value that doesn't originate from the database storage, for example the value from the $default parameter when the option doesn't exist, or the return value from any of its filters (pre_option_{$option}, default_option_{$option}, and option_{$option}).

UPDATED: Elaborate documentation of get_option() due to the possible exceptional cases by using filters and $default

In the DocBlocks, we document return values with mixed only.

That is no good practice as it does not show the real available and possible return types.
A better approach is to declare and document explicitly return values separated by a pipe character like this @return bool|string

That is much clearer because developers do not need to check the return values by reading the entire docBlock, reading the whole code of a method, or reading the (lengthy) function description under developer.wordpress.org.

A simple mixed is outdated and makes it hard for every severe developer to start with coding for WordPress as he has to continually check the expected return values when there is a mixed.

As a bonus, the documentation under developer.wordpress.org will be updated as well by this change automatically. It will help developers getting know the correct return values immediately from the docs without reading all the extra special explanations that we added to our docs whenever we use mixed.

That is a huge time saver and makes it much faster for every developer to write solid and better code faster.

If this is accepted for core, I will offer to work on this on all other methods as well.

That will be a long-lasting process due to the number of functions, but it's definitely worth the effort. We should make this change to all methods where we use mixed and make it to our daily little take-care moment when we add new methods to WordPress.

Sample Patch as an example for all methods that use mixed:

get_option() is a special case, though as it automatically unserializes. So it supports all non-scalar types. Most other methods in WordPress uses mixed with only two return types like bool|string representation, which makes the updates easier.

Trac ticket: https://core.trac.wordpress.org/ticket/51278

Update docBlock of get_option() to better explain the expected return values, taking into account all the exceptions like using $default or the internal filters

Trac ticket: https://core.trac.wordpress.org/ticket/51278

[WP-Staging]

I've created another patch and improved docBlock further by applying your suggestions.
I tried to simplify the description and the wording to describe and added another example of showing the condition when a return value can be a scalar one.

[prbot]

​azaozz commented on ​PR #747:

Added some suggestions/changes. Also may be good to mention that as non-scalar option values are serialized before saving, they remain unchanged. For example adding array( true, false, 0, 1 ) will return the exact same array.

[prbot]

​rene-hermenau commented on ​PR #747:

Added some suggestions/changes. Also may be good to mention that as non-scalar option values are serialized before saving, they remain unchanged. For example adding array( true, false, 0, 1 ) will return the same array.

@azaozz Excellent points! I feel ashamed for overlooking that strings are scalar. You've passed my test:-)

get_option() is a very tricky method with all these possible different types of returns. We are right on time to work out this improvement. I've added your suggestions. Please have a look at them.

[SergeyBiryukov]

Related: [47397] / #48303.

[hellofromTonya]

5.7 Beta 1 is happening shortly. Ran out of time to get this ticket into the release. Punting to 5.8.

If any maintainer or committer feels this can be resolved in time, or wishes to assume ownership during a specific cycle, feel free to update the milestone accordingly.

[ReneHermi]

This is only a change of the docBlock. It does not require any UnitTests or similar as it does not touch any real code. It just needs a decision by a maintainer.