[Update] Documentation for WP Alternative Functions

[bhubbard]

• Finalizing work started in PR Add documentation for WordPress.WP.AlternativeFunctions.xml #2496
• Moved File to proper location, added em tags, and removed docs for nonce as it was in the incorrect location.

At wordcamp us 2025 contributor day.

Closes #2496

[rodrigoprimo]

Thanks for working on this, @bhubbard!

Before I review this PR, there are some points that I would like to discuss with you:

• I believe it still includes two <standard>/<code_comparison> blocks for things that are not flagged by the sniff, and they can be removed together with the block that you already removed. A way to check what is flagged or not flagged by the sniff is to add the invalid examples to a PHP file and then run phpcs against it. Here is a step-by-step guide in case it helps:

  • Create a file with the following content:

  <?php
  
  json_encode( $data );
  
  $response = file_get_contents( $url );
  
  echo 'Hello, World!';
  
  echo $user_input;

  • Run vendor/bin/phpcs -s --standard=WordPress --sniffs=WordPress.WP.AlternativeFunctions pathToYourFile.php
  • Note that the first two invalid examples are flagged by the sniff, but the last two are not. This sniff does not check for use of WP translation and escaping functions.

• I wonder whether the documentation should contain a single generic <standard>/<code_comparison> that mentions that some PHP functions shouldn't be used and WP functions should be used instead, or if it should contain one <standard>/<code_comparison> per function group. I can see examples of both approaches in the codebase: WordPress.WP.DeprecatedFunctions uses the generic and short approach, while WordPress.DateTime.RestrictedFunctions uses the function group approach (but the sniff contains just two function groups, while WordPress.WP.AlternativeFunctions contains much more than that). Currently, the documentation in this PR documents just two function groups. Is there a reason for that? If not, I would suggest using one of the approaches mentioned above (cc @jrfnl @GaryJones @dingo-d if you have a preference from the perspective of WPCS maintainers).