Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for WordPress.WP.AlternativeFunctions.xml #2496

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Add documentation for WordPress.WP.AlternativeFunctions.xml #2496

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions WordPress/Docs/PHP/WordPress.WP.AlternativeFunctions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
<?xml version="1.0"?>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The file name and its location are incorrect. There is more information about it in #1722 and https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/.github/CONTRIBUTING.md#writing-sniff-documentation.

The command below should display the documentation, but it doesn't because of that:

vendor/bin/phpcs --generator=Text --standard=WordPress --sniffs=WordPress.WP.AlternativeFunctions

The correct path should be WordPress/Docs/WP/AlternativeFunctionsStandard.xml

<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
title="WordPress Alternative Functions"
>
<standard>
<![CDATA[
Use WordPress functions instead of native PHP functions to maintain compatibility and benefit from WordPress's additional security and performance improvements.
]]>
</standard>
<code_comparison>
<code title="Valid: Using wp_safe_redirect().">
<![CDATA[
wp_safe_redirect( $url );
]]>
</code>
<code title="Invalid: Using PHP's header() function for redirection.">
<![CDATA[
header( "Location: $url" );
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use <em> tags to highlight the "good" and the "bad" bits in the code examples. More information in the description of #1722.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct me if I'm missing something, but as far as I can test, the use of header() does not trigger the WordPress.WP.AlternativeFunctions. I created a file with the contents of this invalid example and run PHPCS but got no errors:

$ cat test.inc 
<?php

header( "Location: $url" );
$ vendor/bin/phpcs --standard=WordPress test.inc -s --sniffs=WordPress.WP.AlternativeFunctions
$

I haven't tested all the other <code_comparison> blocks, but on a quick look, it seems to me file_get_contents() does this this sniff, but the others don't. Now I'm starting to question my self if I'm checking the correct sniff. This is the one that I'm looking:

WordPress-Coding-Standards/WordPress/Sniffs/WP/AlternativeFunctionsSniff.php

Line 27 in 38c950e

final class AlternativeFunctionsSniff extends AbstractFunctionRestrictionsSniff {
. Before I continue this review, could you please check and get back to me?

]]>
</code>
</code_comparison>
<standard>
<![CDATA[
WordPress provides the wp_remote_* functions for making HTTP requests. Avoid using file_get_contents() or cURL directly.
]]>
</standard>
<code_comparison>
<code title="Valid: Using wp_remote_get() for HTTP requests.">
<![CDATA[
$response = wp_remote_get( $url );
]]>
</code>
<code title="Invalid: Using file_get_contents() for HTTP requests.">
<![CDATA[
$response = file_get_contents( $url );
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Use WordPress's translation functions to ensure text is translatable and localized.
]]>
</standard>
<code_comparison>
<code title="Valid: Using _e() or __() for translatable text.">
<![CDATA[
_e( 'Hello, World!', 'text-domain' );
$greeting = __( 'Hello, World!', 'text-domain' );
]]>
Comment on lines +47 to +50
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<![CDATA[
_e( 'Hello, World!', 'text-domain' );
$greeting = __( 'Hello, World!', 'text-domain' );
]]>
<![CDATA[
_e( 'Hello, World!', 'text-domain' );
$greeting = __( 'Hello, World!', 'text-domain' );
]]>

The indentation for code samples should start at the beginning of the line. Otherwise, code samples with multiple lines will have incorrect indentation.

Screenshot from 2024-09-26 11-50-07

Also, per the #1722 description, each line within the code sample should be a maximum of 48 characters.

</code>
<code title="Invalid: Echoing plain text strings.">
<![CDATA[
echo 'Hello, World!';
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Always use WordPress functions for escaping output to prevent XSS vulnerabilities.
]]>
</standard>
<code_comparison>
<code title="Valid: Using esc_html() to escape HTML output.">
<![CDATA[
echo esc_html( $user_input );
]]>
</code>
<code title="Invalid: Outputting user input without escaping.">
<![CDATA[
echo $user_input;
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Use WordPress's wp_nonce_* functions for security and form validation.
]]>
</standard>
<code_comparison>
<code title="Valid: Using wp_nonce_field() and wp_verify_nonce().">
<![CDATA[
wp_nonce_field( 'save_post', 'my_nonce' );
if ( wp_verify_nonce( $_POST['my_nonce'], 'save_post' ) ) {
// Process form submission.
}
]]>
</code>
<code title="Invalid: Not using nonces for form validation.">
<![CDATA[
// No nonce used for form validation.
]]>
</code>
</code_comparison>
</documentation>
Loading