From 69a81e612e92cc0ef29775905a3ce69db6c2994c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20=C5=BDoljom?= Date: Fri, 17 Jun 2022 12:32:32 +0200 Subject: [PATCH 1/6] Fix the code examples --- wordpress-coding-standards/php.md | 87 ++++++++++++++++--------------- 1 file changed, 45 insertions(+), 42 deletions(-) diff --git a/wordpress-coding-standards/php.md b/wordpress-coding-standards/php.md index ba07228..3f76195 100644 --- a/wordpress-coding-standards/php.md +++ b/wordpress-coding-standards/php.md @@ -15,8 +15,8 @@ If you want to automatically check your code against this standard, you can use Use single and double quotes when appropriate. If you're not evaluating anything in the string, use single quotes. You should almost never have to escape quotes in a string, because you can just alternate your quoting style, like so: ```php -echo 'Link name'; -echo "$linkname"; +echo 'Link name'; +echo "text with a ' single quote"; ``` Text that goes into HTML or XML attributes should be escaped so that single or double quotes do not end the attribute value and invalidate the HTML, causing a security issue. See [Data Validation](https://developer.wordpress.org/plugins/security/data-validation/) in the Plugin Handbook for further details. @@ -119,7 +119,7 @@ Note that requiring the use of braces means that _single-statement inline contro
-
+
@@ -166,7 +166,7 @@ $bar = array( ); $baz = sprintf( /* translators: %s: Friend's name */ - esc_html__( 'Hello, %s!', 'yourtextdomain' ), + __( 'Hello, %s!', 'yourtextdomain' ), $friend_name ); @@ -192,16 +192,18 @@ Correct (Multiline): ```php function foo() { - ?> -
- -
- +
+ +
+ - + ``` Incorrect: ```php - + ``` ## Remove Trailing Spaces @@ -246,12 +248,12 @@ Remove trailing whitespace at the end of each line. Omitting the closing PHP tag Always put spaces after commas, and on both sides of logical, comparison, string and assignment operators. ```php -x === 23 -foo && bar -! foo -array( 1, 2, 3 ) -$baz . '-5' -$term .= 'X' +SOME_CONST === 23; +foo() && bar(); +! $foo; +array( 1, 2, 3 ); +$baz . '-5'; +$term .= 'X'; ``` Put spaces on both sides of the opening and closing parentheses of control structure blocks. @@ -292,22 +294,22 @@ $foo = (bool) $bar; When referring to array items, only include a space around the index if it is a variable, for example: ```php -$x = $foo['bar']; // correct -$x = $foo[ 'bar' ]; // incorrect +$x = $foo['bar']; // Correct. +$x = $foo[ 'bar' ]; // Incorrect. -$x = $foo[0]; // correct -$x = $foo[ 0 ]; // incorrect +$x = $foo[0]; // Correct. +$x = $foo[ 0 ]; // Incorrect. -$x = $foo[ $bar ]; // correct -$x = $foo[$bar]; // incorrect +$x = $foo[ $bar ]; // Correct. +$x = $foo[$bar]; // Incorrect. ``` In a `switch` block, there must be no space between the `case` condition and the colon. ```php switch ( $foo ) { - case 'bar': // correct - case 'ba' : // incorrect + case 'bar': // Correct. + case 'ba' : // Incorrect. } ``` @@ -336,8 +338,8 @@ Functions that update the database should expect their parameters to lack SQL sl `$wpdb->prepare()` is a method that handles escaping, quoting, and int-casting for SQL queries. It uses a subset of the `sprintf()` style of formatting. Example : ```php -$var = "dangerous'"; // raw data that may or may not need to be escaped -$id = some_foo_number(); // data we expect to be an integer, but we're not certain +$var = "dangerous'"; // Raw data that may or may not need to be escaped. +$id = some_foo_number(); // Data we expect to be an integer, but we're not certain. $wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_title = %s WHERE ID = %d", $var, $id ) ); ``` @@ -421,20 +423,20 @@ class Example_Class_Extended { [...] } Prefer string values to just `true` and `false` when calling functions. ```php -// Incorrect +// Incorrect. function eat( $what, $slowly = true ) { ... } eat( 'mushrooms' ); -eat( 'mushrooms', true ); // what does true mean? -eat( 'dogfood', false ); // what does false mean? The opposite of true? +eat( 'mushrooms', true ); // What does true mean? +eat( 'dogfood', false ); // What does false mean? The opposite of true? ``` PHP only supports named arguments as of PHP 8.0. However, as WordPress currently still supports older PHP versions, we cannot yet use those. Without named arguments, the values of the flags are meaningless, and each time we come across a function call like the examples above, we have to search for the function definition. The code can be made more readable by using descriptive string values, instead of booleans. ```php -// Correct +// Correct. function eat( $what, $speed = 'slowly' ) { ... } @@ -446,13 +448,14 @@ eat( 'dogfood', 'quickly' ); When more words are needed to describe the function parameters, an `$args` array may be a better pattern. ```php -// Even Better function eat( $what, $args ) { ... } eat ( 'noodles', array( 'speed' => 'moderate' ) ); ``` +Be careful when using this pattern, as it can lead to "Undefined array index" notices in your code if proper checks are not set in place. Use this pattern only where it makes sense (i.e. multiple possible arguments), not just for the sake of it. + ## Interpolation for Naming Dynamic Hooks Dynamic hooks should be named using interpolation rather than concatenation for readability and discoverability purposes. @@ -519,7 +522,7 @@ Correct: ```php if ( 0 === strpos( 'WordPress', 'foo' ) ) { - echo __( 'Yay WordPress!' ); + echo esc_html__( 'Yay WordPress!' ); } ``` @@ -527,7 +530,7 @@ Incorrect: ```php if ( 0 == strpos( 'WordPress', 'foo' ) ) { - echo __( 'Yay WordPress!' ); + echo esc_html__( 'Yay WordPress!' ); } ``` @@ -538,7 +541,7 @@ Correct: ```php $data = $wpdb->get_var( '...' ); if ( $data ) { - // Use $data + // Use $data. } ``` @@ -546,7 +549,7 @@ Incorrect: ```php if ( $data = $wpdb->get_var( '...' ) ) { - // Use $data + // Use $data. } ``` @@ -556,7 +559,7 @@ In a `switch` statement, it's okay to have multiple empty cases fall through to switch ( $foo ) { case 'bar': // Correct, an empty case can fall through without comment. case 'baz': - echo $foo; // Incorrect, a case with a block must break, return, or have a comment. + echo esc_html( $foo ); // Incorrect, a case with a block must break, return, or have a comment. case 'cat': echo 'mouse'; break; // Correct, a case with a break does not require a comment. From 246b71aed201fa57d4be6e9403088c421597b981 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20=C5=BDoljom?= Date: Fri, 17 Jun 2022 16:20:04 +0200 Subject: [PATCH 2/6] Update wordpress-coding-standards/php.md Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com> --- wordpress-coding-standards/php.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wordpress-coding-standards/php.md b/wordpress-coding-standards/php.md index 3f76195..9e9202c 100644 --- a/wordpress-coding-standards/php.md +++ b/wordpress-coding-standards/php.md @@ -16,7 +16,7 @@ Use single and double quotes when appropriate. If you're not evaluating anything ```php echo 'Link name'; -echo "text with a ' single quote"; +echo "text with a ' single quote"; ``` Text that goes into HTML or XML attributes should be escaped so that single or double quotes do not end the attribute value and invalidate the HTML, causing a security issue. See [Data Validation](https://developer.wordpress.org/plugins/security/data-validation/) in the Plugin Handbook for further details. From 01a7e76eb95d6d63a646154ee0193c1043b8228b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20=C5=BDoljom?= Date: Fri, 17 Jun 2022 16:21:09 +0200 Subject: [PATCH 3/6] Update wordpress-coding-standards/php.md Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com> --- wordpress-coding-standards/php.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wordpress-coding-standards/php.md b/wordpress-coding-standards/php.md index 9e9202c..129703c 100644 --- a/wordpress-coding-standards/php.md +++ b/wordpress-coding-standards/php.md @@ -454,7 +454,7 @@ function eat( $what, $args ) { eat ( 'noodles', array( 'speed' => 'moderate' ) ); ``` -Be careful when using this pattern, as it can lead to "Undefined array index" notices in your code if proper checks are not set in place. Use this pattern only where it makes sense (i.e. multiple possible arguments), not just for the sake of it. +Be careful when using this pattern, as it can lead to "Undefined array index" notices if input isn't validated before use. Use this pattern only where it makes sense (i.e. multiple possible arguments), not just for the sake of it. ## Interpolation for Naming Dynamic Hooks From 1b6b4aae4c6f9a008025b80f4c437804f53fa1cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20=C5=BDoljom?= Date: Fri, 17 Jun 2022 16:21:40 +0200 Subject: [PATCH 4/6] Update wordpress-coding-standards/php.md Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com> --- wordpress-coding-standards/php.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wordpress-coding-standards/php.md b/wordpress-coding-standards/php.md index 129703c..9c76e97 100644 --- a/wordpress-coding-standards/php.md +++ b/wordpress-coding-standards/php.md @@ -521,7 +521,7 @@ Unless absolutely necessary, loose comparisons should not be used, as their beha Correct: ```php -if ( 0 === strpos( 'WordPress', 'foo' ) ) { +if ( 0 === strpos( $text, 'WordPress' ) ) { echo esc_html__( 'Yay WordPress!' ); } ``` From 0c2563ab0babf0b4175655e7fc8e619c2702d461 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20=C5=BDoljom?= Date: Fri, 17 Jun 2022 16:21:48 +0200 Subject: [PATCH 5/6] Update wordpress-coding-standards/php.md Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com> --- wordpress-coding-standards/php.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wordpress-coding-standards/php.md b/wordpress-coding-standards/php.md index 9c76e97..b0b9f7c 100644 --- a/wordpress-coding-standards/php.md +++ b/wordpress-coding-standards/php.md @@ -559,7 +559,7 @@ In a `switch` statement, it's okay to have multiple empty cases fall through to switch ( $foo ) { case 'bar': // Correct, an empty case can fall through without comment. case 'baz': - echo esc_html( $foo ); // Incorrect, a case with a block must break, return, or have a comment. + echo esc_html( $foo ); // Incorrect, a case with a block must break, return, or have a comment. case 'cat': echo 'mouse'; break; // Correct, a case with a break does not require a comment. From ea85a03a485943986300217741cedde3b74dc1d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20=C5=BDoljom?= Date: Sun, 3 Jul 2022 17:00:45 +0200 Subject: [PATCH 6/6] Update code example to include the text domain --- wordpress-coding-standards/php.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/wordpress-coding-standards/php.md b/wordpress-coding-standards/php.md index b0b9f7c..7e3c92f 100644 --- a/wordpress-coding-standards/php.md +++ b/wordpress-coding-standards/php.md @@ -522,7 +522,7 @@ Correct: ```php if ( 0 === strpos( $text, 'WordPress' ) ) { - echo esc_html__( 'Yay WordPress!' ); + echo esc_html__( 'Yay WordPress!', 'textdomain' ); } ``` @@ -530,7 +530,7 @@ Incorrect: ```php if ( 0 == strpos( 'WordPress', 'foo' ) ) { - echo esc_html__( 'Yay WordPress!' ); + echo esc_html__( 'Yay WordPress!', 'textdomain' ); } ```