[Update] Documentation for sniff WordPress.PHP.DiscouragedPHPFunctions

[jasonkenison]

Related to #1722

Continuing requested edits from #2494

Updated indentation, added tags and a line break at the end of the file.

Closes #2494

[jasonkenison]

Added more details with code obfuscation examples in the final standard.

[rodrigoprimo]

Thanks for creating this PR, @jasonkenison!

I left some comments with suggestions. Let me know if you have questions.

[rodrigoprimo]

This block and most of the blocks below are missing <em> tags.

[rodrigoprimo]

In some cases the <em> tag is used to highlight just the function name and in other cases it is used to highlight the whole function call. Is there a reason for that? If not, I suggest highlighting just the function name in all examples.

[rodrigoprimo]

I'm unsure (here and in other <code_comparison> blocks) if it is necessary to include an example for every single function that triggers the sniff. Please check other sniff XML docs if you can, but I believe it is more common to just include one example (if all the others are the same except for the function name). Then, if the list is not too long, you can consider mentioning all the functions in the corresponding <standard> description. What do you think?

[rodrigoprimo]

I can see you addressed this point for most <standard> blocks except for the one related to functions used to obfuscate code. Is there a reason for that? Would it make sense to list the functions that trigger this warning in the <standard> description as you did for the <standard> blocks?

[rodrigoprimo]

Maybe it is better to use a variable name other than $array here as this function takes an string as its first parameter? The same applies to the json_decode() example above.

Please check if other variables could be renamed as well for the same reason in the other examples.

[rodrigoprimo]

Apologies if my previous message was not clear. I can see you changed the variable name from $array to $my_array for all the function calls in this <code_comparison> block, but that is not exactly what I meant.

I think it is fine to use $array (or $my_array) for the functions that accept an array as the first parameter (wp_json_encode() and serialize()). But I don't think we should use $array (or $my_array) for functions that don't accept an array as the first parameter (json_decode() and unserialize()). $string (or something similar) would be fine in those two cases from my perspective. Do you agree?

[rodrigoprimo]

@jasonkenison, I was just wondering if you'll have a chance to finish this off in the near future. It would be great if this PR could be included in the next WPCS release.

If you haven't got time or lost interest, please let us know and we'll see if we can find someone to take over. Thanks!

[rodrigoprimo]

Besides the point that I raised above about the placement of the <em> tags, I believe a typo was introduced in this particular line in the recent commits: code>.

[rodrigoprimo]

I believe eval() is not flagged by the sniff so it should not be highlighted. More broadly, I'm not sure if it needs to be included as the sniff will trigger anyway for base64_decode() regardless of whether eval() is used.

[rodrigoprimo]

I migth be missing something but the name of this variable is a bit misleading to me as the function does not expect a ROT13 version of a string as it first parameter. Instead it will return a ROT13 version of a string.

[rodrigoprimo]

Thanks for working on the remaining remarks I had left in this PR, @jasonkenison. I checked everything and left a few follow up questions.

As I'm not a maintainer on this repo, I don't have permission to resolve the conversations for the things that you already addressed. For those, I left a thumbs up reaction on the last comment. Could you please resolve them?