Juliette Reinders Folmer 2:52 pm on March 20, 2020
Tags: #modernizeWP ( 3 ), codingstandards ( 5 ), PHP ( 71 ), WPCS ( 7 )

Updating the Coding standards for modern PHP

Until May last year, contributions to WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. were bound to PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 5.2 syntax and most plugins and themes stuck to the PHP 5.2 minimum requirement as well.

However, with the change to PHP 5.6 as the minimum PHP version for WordPress Core, new PHP features have become available for use in WP Core and with the outlook of a minimum version of PHP 7.x in the (near) future, even more interesting language features will soon become available for use in WordPress Core, plugins and themes.

With that in mind, we’d like to define coding standards for a number of these constructs and propose to implement automated checking for these in the WordPress Coding StandardsWordPress Coding Standards The Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook. May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards. tooling in the near future.

While it may still be a while before some of these features will actually be adopted for use in WordPress Core, defining the coding standards in advance will allow for a consistent code base when they do get adopted and will allow for plugins and themes, which are not necessarily bound to the PHP 5.6 minimum, to safeguard their code consistency when they start using more modern PHP already.

To be honest, none of these proposals are terribly exciting and some may not even seem worth mentioning. Most follow either prior art in WordPress Core or industry standards for the same, but in the spirit of openness, we’d like to verify our take on these before implementing them.

So without further ado, the following coding standards are proposed for implementation in the WordPress Coding Standards 3.0.0:

Rules for modern PHP constructs

Namespace declarations

Proposed standards:

The namespace keyword should be lowercase.
There should be exactly one space between the namespace keyword and the start of the namespace name in a namespace declaration.
And to be extra clear: namespace names in a namespace declaration should not start with a leading backslash \. This would be a parse error in most cases anyway.
Each “leaf” of a namespace name should be in Camel_Caps, i.e. each word should start with a capital and words should be separated by an underscore.
Consecutive caps, like for acronyms, will be allowed. This is in line with other WP naming conventions.
There should be no whitespace or comments within the name part of the namespace declaration.
There should be exactly one blank line before a namespace declaration.
There should be at least one blank line after a namespace declaration.
There should be only one namespace declaration per file.
This automatically implies that the namespace declaration should be at the top of a file, with only the file docblockdocblock (phpdoc, xref, inline docs) and an optional declare statement preceding it.
Namespace declaration using the curly brace blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. syntax are not allowed.
Namespace declarations without name (= explicit global namespace) are not allowed.

Related open WPCS issue: https://github.com/WordPress/WordPress-Coding-Standards/issues/1763

Valid code example

<?php
/**
 * File docblock.
 */

namespace Prefix\Admin\Domain_URL\Sub_Domain\Event;

use ...

Invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. code examples

<?php
/**
 * File docblock.
 */
namespace Prefix \
    /* Here comes the real namespace */ Admin\DomainURL\ SubDomain\Event;
use ...

<?php
/**
 * File docblock.
 */
namespace Foo {
    // Code.
}

namespace {
    // Code.
}

Usage in WordPress Core

As previously stated, the introduction of namespaces into WordPress Core will need to be a concerted effort with careful thought about the implications for the architecture as a whole.
There is currently no timeline for introducing namespaces to WordPress Core.

Usage in plugins and themes

The use of namespaces in plugins and themes is strongly encouraged. It is a great way to prefix a lot of your code to prevent naming conflicts with other plugins, themes and/or WordPress Core.

Please do make sure you use a unique and long enough namespace prefix to actually prevent conflicts. Generally speaking, using a namespace prefix along the lines of Vendor\Packagename is a good idea.

And while not new, this may also be a good time to remind you that using wp or WordPress as a prefix is not allowed (regardless of case).

// Correct.
namespace My_Awesome_Plugin\Admin;

// Incorrect.
namespace MAP\Admin;

Also be aware that namespacing has no effect on variables declared outside of functions/classes, constants declared with define() or non-PHP native constructs, like the hook names as used in WordPress.
Those still need to be prefixed individually.

Import `use` statements

Proposed standards:

Import use statements should be at the top of a file and should directly follow the (optional) namespace declaration.
Import use statements should be ordered by type: first import use statements for classes, interfaces and traits, next import use statements for functions and lastly import use statements for constants.
No rules are currently set for the ordering of import use statements of the same type. This will be revisited at a later point in time.
There should be exactly one blank line before the first import use statement of each type and at least one blank line after the last import use statement.
The use, function, const and as keywords should be lowercase.
There should be exactly one space after each keyword.
Names in an import use statement should not start with a leading backslash \.
All names in import use statements must be fully qualified by nature, so a \ at the start is redundant.
There should be no whitespace or comments within the name part of a use declaration.
Alias names should comply with the existing WordPress naming conventions for class/function/constant names.
Only set an alias when using a different name.
I.e. this is not allowed: use My\Project\ClassName as ClassName.
Note: as these names are case-insensitive in PHP, aliasing to the same name in a different case falls under this rule and is forbidden.
When using group use statements:
1. There should be one statement for each type – OO constructs (classes/interfaces/traits), functions, constants. The various types should not be combined in one group use statement.
2. There should be no space between the namespace separator and the opening curly brace for the group use.
3. The opening curly brace should be the last code element of the line.
4. Each sub-statement must be one a line by itself and should be indented one tab in from the use statement keyword.
5. When possible (PHP 7.2+), the last statement should be followed by a trailing comma.
  This will not be enforced until the minimum PHP requirement has been raised to PHP 7.2.
6. The closing curly brace should be on a line by itself with no blank line(s) before it.
7. The closing curly brace must be indented the same as the use keyword.

At this time, no standards are defined (yet) on when an import use statement should be used and when to use a fully qualified name inline. Guidelines to that effect may be added at a later point in time.

Valid code example

<?php
/**
 * File doc block.
 */

namespace WordPress\subnamespace;

use Some\Namespace\Class_A;
use Some\Namespace\Class_C as Aliased_Class_C;
use Some\Namespace\{
    Class_D,
    Class_E as Aliased_Class_E,
}

use function Some\Namespace\function_a;
use function Some\Namespace\function_b as aliased_function;

use const Some\Namespace\CONSTANT_A;
use const Some\Namespace\CONSTANT_D as ALIASED_CONSTANT;

// Rest of the code

Invalid code example

<?php
/**
 * File doc block.
 */

namespace WordPress\subnamespace;

use Some\Namespace \ /*comment*/ Class_A;
use   const   Some\Namespace\CONSTANT_A;
use function Some\Namespace\function_a;
use \Some\Namespace\Class_C as aliased_class_c;
use Some\Namespace\{Class_D, Class_E   as   Aliased_Class_E}
use Vendor\Package\{ function function_a, function function_b,
     Class_C,
        const CONSTANT_NAME};

class Foo {
    // Code.
}

use const \Some\Namespace\CONSTANT_D as Aliased_constant;
use function Some\Namespace\function_b as Aliased_Function;

// Rest of the code

Usage in WordPress Core

While import use statements can already be used in WordPress Core, it is, for the moment, strongly discouraged.

Import use statements are most useful when combined with namespaces and a class autoloading implementation. As neither of these are currently in place for WordPress Core and discussions about this are ongoing, holding off on adding import use statements to WordPress Core is the sane choice for now.

Important notes:

Adding a use statement does not automatically load whatever is being imported. You still need to load the file containing the class/function/constant with a require/include statement before the imported code is used.
Import use statements have no effect on dynamic class, function or constant names.
Group use statements can not be used in WordPress Core until the minimum PHP version has been raised to PHP 7.0.
Trailing commas in group use statements can not be used in WordPress Core until the minimum PHP version has been raised to PHP 7.2.

Fully qualified names in inline code

Proposed standards:

When using a fully or partially qualified name, no whitespace or comments are allowed within the name.

Code example

// Correct.
$foo = new \Vendor\Domain\Foo();

$result = namespace\function_name();

// Incorrect.
$foo = new \Vendor // Source: external dependency.
           \Domain
           \Foo();

$result = namespace \function_name();

Usage in WordPress Core

Until the introduction of namespaces, there is no need to introduce the use of fully qualified names in inline code into WordPress Core.

Traits and interfaces

Proposed standards for trait/interface declarations:

Trait and interface names should use capitalized words separated by underscores, same as class names. Any acronyms should be all upper case.
The word “Trait” is not required in a trait name, but won’t be forbidden either.
The word “Interface” is not required in an interface name, but won’t be forbidden either.
Trait file names should be based on the trait name with trait- prepended and the underscores in the trait name replaced with hyphens.
The same goes for interface file names where the name should be based on the interface name with interface- prepended and the underscores in the interface name replaced with hyphens.
Example: for a trait called Form_Field_Generator, the file should be named trait-form-field-generator.php.

For everything else, the same formatting rules as already in place for class declarations apply.

Proposed standards for the formatting of trait use statements:

Trait use statements should be at the top of a class.
Trait use statements should have exactly one blank line before the first use statement and at least one blank line after, with the exception of a class only containing a trait use statement in which case the blank line after may be omitted.
Comments/docblocks directly above a trait use statement will be regarded as belonging with the statement and the blank line will be enforced above it.
The use, insteadof and as keywords must be in lowercase.
There must be exactly one space between the use keyword and the name of the trait.
When grouping multiple traits in one use statement, there should be no space between a trait name and the comma and exactly one space between the comma and the next trait name.
When using the insteadof or as statements:
1. There must be exactly one space before and after each of these keywords.
2. For single-line use statements, there must be exactly one space between the last trait name and the opening curly brace and exactly one space between the opening curly brace and start of the enclosed statement.
  There must also be exactly one space between the semi-colon at the end of the enclosed statement and the closing curly brace and the closing curly brace should be the last code element on the line.
3. For multi-line use statements, there must be exactly one space between the last trait name and the opening curly brace and a new line after the opening curly brace.
  The closing curly brace should be on a line by itself with no blank line(s) before it.
  The closing brace must be indented the same as the use keyword.
4. When using multiple insteadof or as statements grouped within curly braces, the statement must become a multi-line use statement and each of the insteadof or as statements must be on a line by itself, indented exactly one tab from the use keyword.

Code example

// Correct.
class Foo {

    // Comments above a use statement will be regarded as documentation for the statement.
    use BarTrait;
    use FooTrait, BazingaTrait {
        BarTrait::method_name insteadof FooTrait;
        BazingaTrait::method_name as bazinga_method;
    }
    use LoopyTrait { eat as protected; }

    public $baz = true;

    ...
}

class Foo {

    use BarTrait;
}

// Incorrect.
class Foo {
    use       BarTrait;


    use FooTrait,   BazingaTrait{BarTrait::method_name    insteadof     FooTrait; BazingaTrait::method_name
        as     bazinga_method;
            };
    public $baz = true;

    ...
}

Usage in WordPress Core

Interfaces could already previously be used in WordPress Core and are encouraged to be used to clarify the public interface of sets of related classes.

Traits may be used in WordPress Core, though it should be carefully evaluated in each individual instance whether using a trait is the right decision from an architectural point of view.

Type declarations

Proposed standards:

Type declarations must have exactly one space before and after the type.
In case of a multi-line function declaration, a new line + appropriate indentation should be used before the type declaration.
The nullability operator is regarded as part of the type declaration and there should be no space between this operator and the actual type.
Keyword-based type declarations should use lowercase.
Class/interface name based type declarations should use the case of the class/interface name as declared.

And specifically for return type declarations:

There should be no space between the closing parenthesis of the function declaration and the colon starting a return type.

These rules apply to all structures allowing for type declarations: functions, closures, catch conditions as well as the PHP 7.4 arrow functions and typed properties.

Code example

// Correct.
function foo( Class_Name $param_a, ?string $param_b, callable $param_c ): ?\Class_Name {
    // Do something.
}

function bar(
    Interface_Name $param_a,
    ?int $param_b,
    bool $param_c
): ?\Class_Name {
    // Do something.
}

// Incorrect.
function baz(Class_Name $param_a, ? Float$param_b,      CALLABLE     $param_c )  :   ?  \Class_Name{
    // Do something.
}

Usage in WordPress Core

While rare, array and class/interface name based type declarations already exist in WordPress Core.

Adding type declarations to existing WordPress Core functions should be done with extreme care.
The function signature of any function (method) which can be overloaded by plugins or themes should not be touched.
This includes all existing public and protected class methods and any conditionally declared (pluggable) functions in the global namespace.

This leaves, for now, only unconditionally declared functions in the global namespace, private class methods and code newly being introduced as candidates for adding type declarations.

For those, adding callable, class and interface name based parameter type declarations where the parameter type only expects one type and it would allow for simplification of existing/new code is allowed and tentatively encouraged.

Using the array keyword in type declarations is strongly discouraged for now, as most often, it would be better to use iterable to allow for more flexibility in the implementation and that keyword is not yet available for use in WordPress Core until the minimum requirements are upped to PHP 7.1.

Note:

The scalar bool, int, float and string type declarations can not be used in WordPress Core until the minimum PHP version has been raised to PHP 7.0.
Return type declarations can not be used until the minimum PHP version has been raised to PHP 7.0.
Nullable type declarations can not be used until the minimum PHP version has been raised to PHP 7.1.
The iterable, void and object type declarations can not be used until the minimum PHP version has been raised to PHP 7.1 and 7.2 respectively.
Property type declarations can not be used until the minimum PHP version has been raised to PHP 7.4.

Declare statements / strict typing

Proposed standards:

There should be exactly one blank line above the declare statement and at least one blank line below.
The keywords used – declare, strict_types, ticks and encoding – should be lowercase.
There should be no space between the declare keyword and the open parenthesis.
There should be no space on the inside of the parentheses.
There should be no space on either side of the = operator used within declare statements.
declare statements using the curly brace block syntax are allowed for ticks only. For declare statements using the curly brace block syntax:
1. There should be exactly one space between the closing parenthesis and the opening curly brace and the opening curly should be the last code element on the line.
2. The block contents should be indented one tab in from the indentation of the declare keyword.
3. And the closing curly brace should be on a line by itself with no blank line above it and at least one blank line below it.

Note: these standards are different from those used for function calls. Keep in mind that declare is not a function.

Code example

// Correct.
<?php
/**
 * File doc block.
 */

declare(strict_types=1);

use ...

declare(ticks=1) {
    // Do something.
}

// Incorrect.
<?php
/**
 * File doc block.
 */
declare ( strict_types = 1 );
use ...

Usage in WordPress Core

Strict typing should not be used in WordPress Core at this time.

It is a PHP 7.0+ feature, but even when WordPress Core would get a PHP 7.0 minimum requirement, implementing strict typing will need careful consideration as a lot of WordPress Core relies on the loose type nature of PHP, so this is not something to be undertaken lightly and is not on the agenda for the foreseeable future.

The other declare statements, ticks and encoding, can be used in WordPress Core when appropriate.

The `::class` constant

Proposed standards:

There should be no space between ::class and the preceding class name it applies to.
There should be no space between the double colon and the class keyword.
The class keyword should be in lowercase.

Code example

// Correct.
add_action( 'action_name', array( My_Class::class, 'method_name' ) );

// Incorrect.
add_action( 'action_name', array( My_Class :: CLASS, 'method_name' ) );

Usage in WordPress Core

The ::class constant can be freely used in WordPress Core.
Replacing existing uses of __CLASS__ with self::class and get_called_class() with static::class, where appropriate, is encouraged.

Operators

Spread operator `...`

Proposed standards:

There should be one space, or a new line + appropriate indentation, before the spread operator.
There should be no space between the spread operator and the variable/function call it applies to.
When combining the spread operator with the reference operator, there should be no space between them.

Related open WPCS issue: https://github.com/WordPress/WordPress-Coding-Standards/issues/1762

Code example

// Correct.
function foo( &...$spread ) {
    bar( ...$spread );

    bar(
        array( ...$foo ),
        ...array_values( $keyed_array )
    );
}

// Incorrect.
function fool( &   ... $spread ) {
    bar(...
             $spread );

    bar(
        [...  $foo ],.../*comment*/array_values( $keyed_array )
    );
}

Usage in WordPress Core

The spread operator for packing arguments in function declarations and unpacking them in function calls has been introduced in WordPress Core in WP 5.3 and can be freely used when appropriate.

If you want to learn more about the caveats of when the spread operator can/can not be used, reading the implementation notes in the associated Trac ticket is highly recommended.

The spread operator can not be used to unpack arrays until the minimum PHP version has been raised to PHP 7.4.

`instanceof`, pow ``, pow equals `=`, spaceship `<=>`, null coalesce `??` and null coalesce equals `??=`

The already existing rules regarding operators apply:

Always put spaces on both sides of logical, comparison, string and assignment operators.
Equality operators in blocks of code should be aligned for readability.

Usage in WordPress Core

instanceof could already be used in WordPress Core and it is encouraged to use this operator instead of a function call to is_a() as it is more performant.

The pow ** and pow equals **= operators can be freely used in WordPress Core and have been introduced in WP 5.3.

The spaceship <=>, null coalesce ?? and null coalesce equals ??= operators can not be used in WordPress Core until the minimum PHP version has been raised to PHP 7.0 (spaceship and null coalesce) or PHP 7.4 (null coalesce equals).

Additional new rules

One class-like definition per file

Proposed standards:

There should only be one class-like definition (class/trait/interface) per file.

This has already been a best practice for a while and will now be formalized.

Related open WPCS PR: https://github.com/WordPress/WordPress-Coding-Standards/pull/1802

Visibility should always be declared

Proposed standards:

For all constructs which allow it (properties, methods), visibility should be explicitly declared.
Using the var keyword for property declarations is not allowed.

This has already been a best practice for a while and will now be formalized.

Code example

// Correct.
class Foo {
    public $foo;

    protected function bar() {}
}

// Incorrect.
class Foo {
    var $foo;

    function bar() {}
}

Usage in WordPress Core

If any visibility modifiers are missing in WordPress Core code, they should be set to public so as not to break backward-compatibility.

Visibility for class constants can not be used in WordPress Core until the minimum PHP version has been raised to PHP 7.1 (and won’t be enforced until that time).

Property and method modifier order

Proposed standards:

When using multiple modifiers for a property or method declaration, the order should be as follows:
1. First the optional abstract or final keyword.
2. Next a visibility keyword.
3. Lastly, the optional static keyword.

This has already been a best practice for a while and will now be formalized.

Code example

// Correct.
abstract class Foo {
    public static $foo;

    abstract protected static function bar();
}

// Incorrect.
abstract class Foo {
    static public $foo;

    static abstract protected function bar();
}

Object instantiation

Proposed standards:

When instantiating a new instance of an object, parenthesis must always be used, even when not strictly necessary.
There should be no space between the name of the class being instantiated and the opening parenthesis.
Assigning the return value of an object instantiation by reference is not allowed.
New by reference has not been supported by PHP for quite a long while now.

This has already been a best practice for a while and will now be formalized.

Code example

// Correct.
$foo = new Foo();
$anon = new class() { ... };
$instance = new static();

// Incorrect.
$foo = & new Foo;
$foo = new Foo ();

Function closing brace

Proposed standards:

There should be no blank line between the content of a function and the function’s closing brace.

Code example

// Correct.
function foo() {
    // Do something.
}

// Incorrect.
function foo() {
    // Do something.

}

Method chaining

Proposed standards:

When chaining method calls over multiple lines, subsequent lines should be indented at least one tab in from the start of the statement and have no more than one tab indent difference between the indentation of the current line and indentation of the previous line.
The arrow should be placed on the same line as the subsequent method call.

Code example

// Correct.
$someObject
    ->doSomething()
    ->doSomethingElse();

$someObject
    ->startSomething()
        ->someOtherFunc(23, 42)
    ->endSomething();

// Incorrect.
$someObject
        ->startSomething()->
            someOtherFunc(23, 42)
    ->endSomething();

Include/Require

Proposed standards:

No parentheses shall be used for include[_once] and require[_once] statements.
As include[_once] and require[_once] are language constructs, they do not need parentheses around the path.
There should be exactly one space between the include[_once] and require[_once] keyword and the start of the path.
It is strongly recommended to use require[_once] for unconditional includes.
When using include[_once] PHP will throw a warning when the file is not found, but will continue execution which will almost certainly lead to other errors/warnings/notices being thrown if your application depends on the file being available, potentially leading to security leaks. For that reason, require[_once] is generally the better choice as it will throw a Fatal Error if the file cannot be found.

This has already been a best practice for a while and will now be formalized.

Related open WPCS PR: https://github.com/WordPress/WordPress-Coding-Standards/pull/1862

Code example

// Correct.
require_once ABSPATH . 'filename.php';

// Incorrect.
include_once  ( ABSPATH . 'filename.php' );

Increment/decrement operators

Proposed standards:

There should be no space between an increment/decrement operator and the variable it applies to.
Pre-increment/decrement should be favoured over post-increment/decrement for stand-alone statements.
“Pre” will in/decrement and then return, “post” will return and then in/decrement.
Using the “pre” version is slightly more performant and can prevent future bugs when code gets moved around.

Related open WPCS issue: https://github.com/WordPress/WordPress-Coding-Standards/issues/1511

Code example

// Correct.
for ( $i = 0; $i < 10; $i++ ) {}

--$a;

// Incorrect.
for ( $i = 0; $i < 10; $i ++ ) {}

$a--;

Magic constants

Proposed standards:

The PHP native __...__ magic constants should be in uppercase when used.

Code example

// Correct.
add_action( 'action_name', array( __CLASS__, 'method_name' ) );

require_once __DIR__ . '/relative-path/file-name.php';

// Incorrect.
add_action( 'action_name', array( __class__, 'method_name' ) );

require_once __dIr__ . '/relative-path/file-name.php';

Shell commands

Proposed standards:

Use of the backtick operator is not allowed.

This has already been a best practice for a while and will now be formalized.

Complex control structure conditions

A control structure statement with multiple conditions can make for very long lines making code harder to read.

It is encouraged (but not enforced) that these long conditions are split into multiple lines.

When a long condition statement is split over multiple lines, the following (new) rules are proposed in addition to the existing rules for control structure formatting:

The first condition should be on the same line as the control structure keyword.
The closing parenthesis for the control structure should be on a new line, indented the same as the control structure keyword and followed by a space and the opening curly brace of the control structure.
When splitting the conditions into multiple lines, the boolean/logical operators separating the statements should always be placed at the start of the new line.
This makes for smaller change-sets and improves readability.

Note: even with conditions spread out over multiple lines, multiple conditions per line will still be allowed as long as the condition grouping makes sense.

Code example

// Single line is allowed.
if ( function_call( $a, $b, $c ) === false && ( isset( $d, $e, $f ) && function_call( $d, $e, $f ) === true ) && function_call( $g, $h, $i ) === false ) {
    // Do something.
}

// Correct formatting when using multi-line:
if ( function_call( $a, $b, $c ) === false
    && ( isset( $d, $e, $f ) && function_call( $d, $e, $f ) === true )
    && function_call( $g, $h, $i ) === false
) {
    // Do something.
}

// Incorrect formatting when using multi-line:
if (
    function_call( $a, $b, $c ) === false &&
    ( isset( $d, $e, $f ) && function_call( $d, $e, $f ) === true )
    && function_call( $g, $h, $i ) === false ) {
    // Do something.
}

Feedback

Feedback on the standards proposed here is welcome in the comments.

If there are other PHP constructs and language features for which you’d like to see coding standards defined, please open an issue in the WordPress Coding Standards GitHub repository.

Kind request: while I realize that the existing stance on disallowing short array syntax is a hot topic for some people, please do not pollute the discussion about the standards which are currently being proposed by re-opening that discussion in the comments.
Short array syntax will be revisited at a later time, but is not part of the current proposal. Thank you in advance for your understanding.

Previous posts on this subject:

https://make.wordpress.org/core/2019/07/12/php-coding-standards-changes/
https://make.wordpress.org/core/2019/03/26/coding-standards-updates-for-php-5-6/

Props: Graceful thanks go out to @dingo_d, @garyj, @netweb, @nielsdeblaauw, @pento, @schlessera, and @SergeyBiryukov for reviewing this post prior to publication.

#modernizewp, #codingstandards, #php, #wpcs

dingo-d 2:56 pm on March 20, 2020

+make.wordpress.org/themes
Niels de Blaauw 2:58 pm on March 20, 2020

Great step in the right direction! Standardizing modern constructs for WordPress helps the entire ecosystem.
Aaron Brazell 3:25 pm on March 20, 2020

Why are we still using class-, interface-, and trait- file naming conventions? Seems like this is a good opportunity to support this legacy mechanism (even for coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.), while opening up PSR-4 autoloading options for distributable plugins?
- Juliette Reinders Folmer 3:32 pm on March 20, 2020
  
  Plugins have the freedom to deviate from the above, if they so choose.
  
  As side-note: classmap based autoloading is much more performant than PSR-4 and the current proposal does not inhibit that at all.
  - Aaron Brazell 3:38 pm on March 20, 2020
    
    Sure but it’s not ideal for development as you have to regen the classmap every time you add a new class.
    - Juliette Reinders Folmer 3:39 pm on March 20, 2020
      
      Dev-convenience should not be a reason for bad choices for production.
      Regen of a classmap can be automated if needs be.
  - Jason Adams 4:51 pm on March 20, 2020
    
    That’s not entirely true. Autoloading has the ability to generate a classmap using composer dump-autoload --optimize-autoloader.
    - Juliette Reinders Folmer 4:53 pm on March 20, 2020
      
      Sorry, just checking – but what about my statement isn’t true ? Your example, to me, just seems to confirm and harden what I said.
- Jeremy Pry 4:40 pm on March 23, 2020
  
  Trait file names should be based on the trait name with trait- prepended and the underscores in the trait name replaced with hyphens.
  The same goes for interface file names where the name should be based on the interface name with interface- prepended and the underscores in the interface name replaced with hyphens.
  
  I think that this practice should be deprecated rather than reinforced.
  
  There isn’t any benefit to adding these prefixes to the file name, but it does add extra work. Many IDEs will automatically create a new file based on a class name, and requiring a prefix is an extra step every single time. Not only that, but it makes PSR-4 autoloading nearly impossible. How are you expected to code an autoloader that knows whether something that needs autoloaded is a class, trait, or interface before it’s loaded?
  
  As side-note: classmap based autoloading is much more performant than PSR-4 and the current proposal does not inhibit that at all.
  
  That’s true that classmaps are more performant (as far as I know), but classmaps and PSR-4 aren’t mutually-exclusive. There’s no reason we can’t use PSR-4 for development, and implement classmaps on the same PSR-4 structure for production. Making these prefixes required is not adding flexibility in future development, but rather limiting flexibility. A classmap will be required instead of encouraged.
  
  Plugins have the freedom to deviate from the above, if they so choose.
  
  Yes they do, but we’re hampering ourselves for the future of WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. if we keep this requirement. Eventually I (and probably many other core developers) would love to see the WordPress codebase make use of most (if not all) of the modern PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher features mentioned here. Instead of boxing ourselves in, let’s allow for more flexibility in the future.
KestutisIT 3:42 pm on March 20, 2020
PSR-4 Autoloaders is the most easiest to pickup, so I would ask to have:
/Models/Car/GreatCar.php – class
/Models/Car/CarTrait.php – Trait
/Models/Car/CarInferface.php – Interface
/Models/Car/AbstractCar.php – abstract class

Also do not forget to follow as much as possible of PSR-2.
And I DO NOT think that we must required spaces inside IF’s brackets, meaning, this should be valid:
```
if ($a)
{
 <...>
}
```
And this as well
```
add_action('action_name', array( __CLASS__, 'method_name'));
```
Those extra spaces SLOWS down the coding speed, and ARE NOT described in PSR-2 coding standard.
- KestutisIT 3:42 pm on March 20, 2020
  
  add_action(‘action_name’, array(__CLASS__, ‘method_name’));
  - Juliette Reinders Folmer 3:46 pm on March 20, 2020
    
    PSR2 has been superseded by PSR12, so PSR2 is not relevant anymore.
    
    A lot of the current proposals are in line with PSR12, but this proposal is not about changing existing standard (spaces inside parentheses), it is about adding to them and clarifying them where necessary.
- dingo-d 3:44 pm on March 20, 2020
  
  As Juliette mentioned, in the themes and plugins, you are free to use whatever you want. These are more WP coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. related standards that you can but don’t have to, follow in your themes/plugins.
  
  Oh and I recommend using PSR-12, it’s a superset of PSR-2 with more emphasis on modern coding practices 🙂
  - Aaron Brazell 3:46 pm on March 20, 2020
    
    However, through the entire article, there are recommendations and then coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. recommendations. So it seems their is confusion about this. If this is mainly core, why are there specific callouts for “Core usage”?
    - Juliette Reinders Folmer 3:51 pm on March 20, 2020
      
      These standards are for the whole WP community and will apply to WP CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. development.
      Plugins and themes have the freedom to choose to adopt them or not.
      
      As some of these standards involve PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher features which may not be available for use yet in WP Core, due to either ongoing architectural discussions or due to the minimum PHP version not being high enough, I’ve chosen to clarify when certain features can be used in WP Core.
      Again, plugins and themes can choose to use a different minimum PHP version, so those asides may not apply to them.
Joy 3:56 pm on March 20, 2020

The one about method chaining makes no sense. Is the example for correct code actually correct?
- Juliette Reinders Folmer 3:59 pm on March 20, 2020
  
  Yes. What do you think is wrong with it ?
  - Joy 4:01 pm on March 20, 2020
    
    three arrows but the middle one indented more than the others
    - Juliette Reinders Folmer 4:01 pm on March 20, 2020
      
      That’s under the new rules allowed, but not required.
  - pepe 4:02 pm on March 20, 2020
    
    The additional indentation in the middle is unexpected. There should probably be a second example without such extra indentation.
    - Juliette Reinders Folmer 4:05 pm on March 20, 2020
      
      Good point. I’ve added an extra example now.
  - Joy 4:03 pm on March 20, 2020
    
    It just doesn’t seem to match what the rule said. It seemed like the rule was saying that each chained method would be indented more. But that seems hard to read. And the way that correct code looks is hard to read.
    - Jeremy Pry 4:46 pm on March 23, 2020
      
      My interpretation (correct me if I’m wrong @jrf) is that the additional indentation is used when a different object is being acted upon.
      
      This is the example code:
      
      $someObject ->startSomething() ->someOtherFunc(23, 42) ->endSomething();
      
      Looking at this code, I expect that the startSomething() method returns a different object than $someObject. The someOtherFunc() method operates on second object. Then endSomething() returns the original object.
      
      The extra indentation indicates that the indented methods are operating on a different object than the rest of the methods in the chain.
Timothy Jacobs 4:02 pm on March 20, 2020

Using the array keyword in type declarations is strongly discouraged for now, as most often, it would be better to use iterable to allow for more flexibility in the implementation and that keyword is not yet available for use in WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. until the minimum requirements are upped to PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 7.1.

This seems off to me. I think in most arrays used in WordPress iterable wouldn’t be a sufficient type since you can’t arbitrarily retrieve a value by a key. So, for instance, wp_insert_post could never be typed as an iterable but could be typed as an array. It is also already being used by WordPress Core in things like populate_site_meta, Recovery Mode, the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings., the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/., etc…

I think we gain value by having an array typehint in those places, and we should continue adding it or even expanding our usage when possible.
- Juliette Reinders Folmer 5:05 pm on March 20, 2020
  
  If array type declarations would be introduced in those places, it would be a breaking function signature change if this would later be changed to iterable (or `ArrayAccess` etc) when the underlying structure would be changed to a Value Object, for instance, with the option remaining to pass in an array instead of the Value Object.
  
  As WP is notorious for avoiding breaking changes, introducing array type declarations would inhibit those type of refactors of underlying structures for the future, which IMO is detrimental to the project as a whole.
  - Timothy Jacobs 5:20 pm on March 20, 2020
    
    Let’s take a look at populate_site_meta for instance. Let’s say we wanted to add support to passing in an ArrayAccess instance. We’d simply remove the array type declaration. If the function currently had no type signature, then adding ArrayAccess as a signature would be a BC break because anyone who is passing an array would now have their code broken.
    
    Now, let’s say we change it to iterable. Well then there isn’t any BC break to the function signature since an array would be accepted there.
    
    However, the body of the function would require changes. For instance, we’d need to immediately convert the iterable to an array since we filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. that value. And any code that used that filter to `unset` an item of the list would break if it was passed a generator, for instance. ( not to mention the fact that you would have issues if more than one person iterated over that list, since you can’t rewind generators ).
    
    As WP is notorious for avoiding breaking changes, introducing array type declarations would inhibit those type of refactors of underlying structures for the future, which IMO is detrimental to the project as a whole.
    
    The only place where we’d have a BC issue in the signature ( going from array to iterable ) would be in an APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. where it was expected & supported for the user to override the method. ( Adding the type signature at all would be a BC break as well. ) But ignoring all that, just changing to support an iterable would be a BC break as well, even if you didn’t do any signature changes for the same reason I mentioned in the previous paragraph. If the code isn’t expecting an iterable, and only an array, than there are a myriad of different ways the code could break.
    
    The signature merely enforces the actual breakage that would be occurring.
  - Andrew Ozz 8:21 pm on March 20, 2020
    
    As WP is notorious for avoiding breaking changes, introducing array type declarations would inhibit those type of refactors of underlying structures for the future, which IMO is detrimental to the project as a whole.
    
    I see this “notoriousness” as a big plus for WordPress and a big win for all WordPress users. It’s probably one of the reason that led to 35% of all websites on the Internet using WordPress 🙂
    
    I’d be firmly against any changes to the PHP Coding Standards that even remotely suggest possible breakage of backwards compatibility.
    - Juliette Reinders Folmer 10:02 pm on March 20, 2020
      
      Glad you agree. My use of notorious meant exactly that and is why the use of array type declarations is being discouraged for the time being.
Milana Cap 4:02 pm on March 20, 2020

+make.wordpress.org/docs
Milana Cap 4:06 pm on March 20, 2020

Thank you @jrf for the work and for this detailed post. It’s nice to see all of these being standardised in WordPress <3
- Juliette Reinders Folmer 4:06 pm on March 20, 2020
  
  Thanks for your kind words!
Ipstenu (Mika Epstein) 4:15 pm on March 20, 2020

+make.wordpress.org/plugins/
Shakeeb Ahmed 4:55 pm on March 20, 2020

If we are going PSR4 why not split cores into packages just like GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ and we can only include packages we wnat.

And also with dependency injection pattern we can achieve much more
- Juliette Reinders Folmer 4:57 pm on March 20, 2020
  
  Please join the discussion about the future architecture of WordPress for that.
  
  This article is not about that.
  - Jeremy Pry 4:48 pm on March 23, 2020
    
    @jrf Could you please provide a link to where that discussion is taking place?
    - Juliette Reinders Folmer 5:10 pm on March 23, 2020
      
      I would if I could… I honestly don’t know what’s currently the central hub for those kind of discussions. The people in the SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. #coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.-php channel may know better.
Howdy_McGee 4:56 pm on March 20, 2020

On the note of PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher Standards, can we also disallow error suppressing `@` please? See #24780
- Juliette Reinders Folmer 4:58 pm on March 20, 2020
  
  That’s already disallowed: https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#error-control-operator
Andrew Ozz 7:09 pm on March 20, 2020

@jrf Wow, this is a -HUGE- post, thanks for putting it all together! Most of the changes look pretty good, but see several that would need more considerations/refining or more reasoning.

Thinking this is probably not the best format for a discussion. There are a lot of cases and descriptions making it pretty difficult to follow and comment on all of them.

As far as I see there are three groups of proposals for the WordPress PHP Coding Standards here:
1. Proposals for additions to the standards.
2. Proposals for changes of the current standards.
3. Suggestions for clarifications of some standards.

I’d think it would be quite better to make the proposals for additions and changes in separate posts so they can be discussed properly.

For example the proposals around formatting of namespace declarations and related additions would be much easier to discuss (and make a decision) if they were in a separate post. Same for the proposals for changes and additions to classes and class related code formatting.

The proposals for changes to the current standards would definitely be better discussed in another post. Ideally there will be reasons why the standard should change and examples of other popular standards.

The suggestions for clarifications of existing standards should also be considered carefully, ideally in a separate post.
- Juliette Reinders Folmer 9:49 pm on March 20, 2020
  
  @azaozz I understand your suggestion for splitting it in several posts and will keep it in mind for the future.
  The current proposals, however, are all additions to the current standards. A separate post will be published in the future with proposals for changing some of the existing standards.
  
  In the mean time, a number of the current proposals have their own WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016. issue, so if it would make you more comfortable discussing them one by one, commenting on those may be the way to go.
  - Andrew Ozz 5:50 pm on March 25, 2020
    
    In the mean time, a number of the current proposals have their own WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016. issue, so if it would make you more comfortable…
    
    Not sure this is a good idea. The WordPress Coding Standards GitHub repository is for implementing the codding standards, not for discussing them. There are still issues there that were opened for existing bugs, but the discussions were “hijacked” into commenting on the standards, or commenting on how WP works in general, instead of being about fixing the implementation. So the issues still remain unfixed. Don’t think this is productive 🙁
Andrew Ozz 7:54 pm on March 20, 2020

Another consideration should probably be the syncing (or overlapping) between the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher and JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. standards. There’s a recent post about changes to the JavaScript coding standards to facilitate adopting of Prettier (with some tweaks). I won’t be surprised to see the CSSCSS Cascading Style Sheets. coding standards adopting it too.

There is also a community effort to make a PHP plugin for Prettier which probably deserves a look 🙂
- Juliette Reinders Folmer 9:58 pm on March 20, 2020
  
  Interesting, but not all that applicable. Using JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. tooling for JS and PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher tooling for PHP makes a lot more sense to me.
  
  From what I can see, available rules are limited, though CSFixer integration is possible (not PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS. though).
  Either way I don’t think that tooling will be suitable, for the same reasons PHPCS is used over CS-Fixer: it doesn’t allow for any issues to be reported which are not auto-fixable and especially with the security checks build into WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016., it is necessary to be able to report issues without auto-fixing them.
  - Andrew Ozz 5:40 pm on March 25, 2020
    
    Interesting, but not all that applicable.
    
    You mean the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party for Prettier? Yeah, perhaps for now. Who knows how things go in few years 🙂
    
    My point from the above comment was that the JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. and PHP coding standards should not be mutually exclusive. Since ES6 there is quite a bit more crossover between the two.
taraschr 7:22 am on March 21, 2020

Why just not to apply PSR12 to WP CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.? Maybe in the past WordPress (community) needed own coding standards in due to absence global PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher community standards. But nowadays it is no longer necessary to support own Coding Standards because it is some kind of reinvention of the wheel that only slows down WordPress development.

In my opinion, WordPress need to migrate to common standards of PHP Community. There is no any problems backward compatibility. We can create compatibility layer for current class naming with class_alias() function. It is not a problem to write some automation script that do most part of renaming work.

WordPress are biggest platform in the Internet and WordPress should be the leader of the entire PHP-community, not the catch-up. I will repeat myself and there is no any big problem to create compatibility layer and write code with modern standards and approaches. This changes will open the way for many new developers from other platforms and frameworks.

Ideally, as said @meshakeeb, WordPress need to be splited to few packages by default which make development much easier. WordPress officially should be something bigger than simple CMS for blogging. In fact, it happened many years ago. But it is another topic for discussion.
Daniele Scasciafratte 2:51 pm on March 21, 2020

Amazing post!

Waiting to see all the errors reported on my usual coding with WPCSWordPress Community Support A public benefit corporation and a subsidiary of the WordPress Foundation, established in 2016. 😂
- Juliette Reinders Folmer 4:30 pm on March 21, 2020
  
  Glad you like it :joy:
cdbrosnan 6:19 pm on March 21, 2020

I’m so happy to see this being discussed. For a long time I have wanted to see better, more modern and stable coding standards in the WordPress ecosystem. It will be a lot of work to update everything that needs to be but it will be so worth it for the future of the software.
Andrew Ozz 6:04 pm on March 25, 2020

I understand your suggestion for splitting it in several posts and will keep it in mind for the future.

@jrf This post has 19 proposals with 94 rules and 40 examples. I still find it somewhat harder/less productive to try and review all of them at the same time. It’s just a lot of things all at once…

I’ll try to split them in separate groups/separate comments. That should make it a bit easier.
Andrew Ozz 6:57 pm on March 25, 2020
For the proposals:
- Namespace declarations (9 rules, 6 examples).
- Import `use` statements (17 rules, 3 examples, 4 additional notes).
- Fully qualified names in inline code (1 rule, 4 examples).
These seem okay however wondering why they must be in the WordPress standards. None of them can be used in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. for now (because technical limitations), and it seems they will never be used WordPress Core. It seems somewhat confusing to have standards for something that doesn’t apply to core.

Also, the three proposals miss background info on why the specific rules (and specific limitations) were chosen. Seems they roughly follow PSR12 https://www.php-fig.org/psr/psr-12/.

TBD: Should the WordPress Coding StandardsWordPress Coding Standards The Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook.
May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards. contain rules that do not apply to WordPress Core? If yes, how to prevent the confusion that may cause to new contributors.
Andrew Ozz 7:29 pm on March 25, 2020
For the proposal:
- Traits and interfaces (12 rules, 3 examples).
The proposal states that:

The word “Trait” is not required in a trait name, but won’t be forbidden either.
The word “Interface” is not required in an interface name, but won’t be forbidden either.

However it also states that `trait-` and `interface-` are required for the file names.

For the “Proposed standards for the formatting of trait use statements”, rule 5 requires (allows?) listing of multiple names on the same line separated by commas. Perhaps it would be better to require a line break after each comma. That improves readability and corresponds to similar listings separated by commas.
```
// Correct
    use FooTrait,
        BazingaTrait {
            BarTrait::method_name insteadof FooTrait;
            BazingaTrait::method_name as bazinga_method;
        }
// Incorrect
    use BarTrait;
    use FooTrait, BazingaTrait {
        BarTrait::method_name insteadof FooTrait;
        BazingaTrait::method_name as bazinga_method;
    }
```
TBD:
- It seems better to change the proposal to either require or encourage use of “Trait” and “Interface” to match the general class declarations and file names requirements.
- Line breaks after commas.
Andrew Ozz 8:15 pm on March 25, 2020
For the proposal:
- Type declarations (5 rules, 3 examples, 9 additional notes).
The rules and examples seem okay. However, as mentioned in the additional notes, most type declarations are not compatible with PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 5.6 and cannot be used in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. for now.

This proposal is somewhat similar to the first three proposals: may cause some confusion for new contributors.

I’m on the fence whether this should be added to the coding standards now or after the minimum supported PHP version allows the use of the described type declarations. It also doesn’t help using currently non-supported code in the examples.

In addition, it seems it will be good to include the warnings about using type declarations in existing code in core.

TBD: Perhaps clean-up/edit the following and include it:
Adding type declarations to existing WordPress Core functions should be done with extreme care.

The function signature of any function (method) which can be overloaded by plugins or themes should not be touched.
This includes all existing public and protected class methods and any conditionally declared (pluggable) functions in the global namespace.

This leaves, for now, only unconditionally declared functions in the global namespace, private class methods and code newly being introduced as candidates for adding type declarations.

For those, adding callable, class and interface name based parameter type declarations where the parameter type only expects one type and it would allow for simplification of existing/new code is allowed and tentatively encouraged.

Using the array keyword in type declarations is strongly discouraged for now, as most often, it would be better to use iterable to allow for more flexibility in the implementation and that keyword is not yet available for use in WordPress Core until the minimum requirements are upped to PHP 7.1.

Note:
- The scalar bool, int, float and string type declarations can not be used in WordPress Core until the minimum PHP version has been raised to PHP 7.0.
- Return type declarations can not be used until the minimum PHP version has been raised to PHP 7.0.
- Nullable type declarations can not be used until the minimum PHP version has been raised to PHP 7.1.
- The iterable, void and object type declarations can not be used until the minimum PHP version has been raised to PHP 7.1 and 7.2 respectively.
- Property type declarations can not be used until the minimum PHP version has been raised to PHP 7.4.
Andrew Ozz 10:48 pm on March 25, 2020
For the proposal:
- Declare statements / strict typing (9 rules, 4 examples).
Do not agree with:

1. There should be exactly one blank line above the declare statement and at least one blank line below.

This means inline comments cannot be added immediately above the declare() construct. As declare() seems rarely used (at least in WP context), a better idea seems to be to strongly encourage (require?) inline comment or a docblockdocblock (phpdoc, xref, inline docs) explaining the purpose of the statement and the expected results.

Also not sure the following rules are good idea:

3. There should be no space between the declare keyword and the open parenthesis.
4. There should be no space on the inside of the parentheses.
5. There should be no space on either side of the = operator used within declare

True, declare() is a construct, not a function, but that doesn’t mean it should have another set of parenthesis rules.

TBD:
- Modify rule 1.
- Remove rules 3, 4, and 5. The declare() construct should use the common parenthesis rules, just like other constructs, functions, arrays, classes, etc.
- Change/fix the examples to match.
- Add the (edited/refined) notes from the proposal to the coding standards:
Strict typing should not be used in WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. at this time.

It is a PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 7.0+ feature, but even when WordPress Core would get a PHP 7.0 minimum requirement, implementing strict typing will need careful consideration as a lot of WordPress Core relies on the loose type nature of PHP, so this is not something to be undertaken lightly and is not on the agenda for the foreseeable future.

The other declare statements, ticks and encoding, can be used in WordPress Core when appropriate.
Andrew Ozz 11:02 pm on March 25, 2020
For the proposal:
- Spread operator (3 rules, 4 examples).
This example seems somewhat unclear:
```
    bar(
        [...  $foo ],.../*comment*/array_values( $keyed_array )
    );
```
Seems to need a “Correct” and “Incorrect” versions.

TBD:
- Better example clearly showing a correct and incorrect versions of the same code.
- Add the (edited/refined) notes from the proposal:
The spread operator for packing arguments in function declarations and unpacking them in function calls has been introduced in WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. in WP 5.3 and can be freely used when appropriate.

If you want to learn more about the caveats of when the spread operator can/can not be used, reading the implementation notes in the associated TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. is highly recommended.

The spread operator can not be used to unpack arrays until the minimum PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher version has been raised to PHP 7.4.
Andrew Ozz 11:10 pm on March 25, 2020
For the proposal:
- Method chaining (2 rules, 3 examples).
For better readability the first rule should probably be to avoid chaining on multiple lines.

The second example seems incorrect (not sure if it is a typo or intentional):
```
$someObject
    ->startSomething()
        ->someOtherFunc(23, 42)
    ->endSomething();
```
TBD:
- Add a rule about avoiding chaining.
- Fix the second example.
- Philipp Stracker 5:01 pm on April 3, 2020
  The second example matches the suggested rule:
  
  … and have no more than one tab indent difference between the indentation of the current line and indentation of the previous line
  
  I think this is a great consideration. When chaining functions, we often want to indent chained function calls that way, e.g.
```
$section->add_group()
    ->set_title('Demo Group')
    ->add_field('text')
        ->set_name('field1')
        ->set_label('Your name')
        ->done()
    ->add_field('checkbox')
        ->set_name('check1')
        ->set_label('Check me')
        ->done()
    ->output();
```
Andrew Ozz 11:55 pm on March 25, 2020
For the proposal:
- Complex control structure conditions (3 rules, 3 examples).
Don’t think the first additional rule is good:

1. (When multi-line conditions) The first condition should be on the same line as the control structure keyword.

It “breaks” indentation and reduces readability a bit. Also is a departure from both current use in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and PSR12: https://www.php-fig.org/psr/psr-12/#51-if-elseif-else.

Rule 3 is also a departure from the current “best practices” in WP core. The logical operators are after the conditions, not before.

Don’t see a compelling reason for these changes.

Also perhaps the note there should be part of the rules:

Note: even with conditions spread out over multiple lines, multiple conditions per line will still be allowed as long as the condition grouping makes sense.

TBD:
- Change rule 1: “When the conditions are on multiple lines, the first condition should be on the next line under the control structure keyword, appropriately indented”.
- Change rule 3 to: “When the conditions are on multiple lines, the boolean/logical operators between the statements should always be placed at the end of the line”.
- Add rule 4: “When the conditions are on multiple lines, several conditions may be on the same line when they form a logical group, usually when in parenthesis”.
- Change/fix the examples:
```
// Single line is preferred.
if ( function_call( $a, $b, $c ) === false && ( isset( $d ) && $d === $var_name ) ) {
    // Do something.
}
 
// Correct formatting when using multi-line:
if (
    function_call( $a, $b, $c ) === false &&
    ( isset( $d, $e, $f ) && function_call( $d, $e, $f ) === true ) &&
    'something' === $var_name
) {
    // Do something.
}

// Incorrect formatting when using multi-line:
if ( function_call( $a, $b, $c ) === false
    && ( isset( $d, $e, $f ) && function_call( $d, $e, $f ) === true )
    && function_call( $g, $h, $i ) === false
) {
    // Do something.
}

// Incorrect
if ( function_call( $a, $b, $c ) === false && 'something' === $var_name
    && ( isset( $d, $e, $f ) && function_call( $d, $e, $f ) === true ) ) {
    // Do something.
}
```
- Philipp Stracker 4:51 pm on April 3, 2020
  
  Yes, totally agree with @azaozz here; we should keep this in sync with the style of multi-line function calls.
Henry Wright 9:54 pm on March 30, 2020

Is this a good time to take a leap? The PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher Standards Recommendations feel right to me
PSDtoWPService.com 4:41 pm on March 31, 2020

Great time to take such great steps!
Philipp Stracker 5:08 pm on April 3, 2020
@jrf what about those cases – do you consider both correct? I can see no suggested rule on which to prefer:
```
// Case 1: Multi-line chaining; initial object name in own line.
$my_object
    ->start_chaining()
    ->something_else()
    ->all_done();

// Case 2: Multi-line chaining; first function in same line as initial object name.
$my_object->start_chaining()
    ->something_else()
    ->all_done();
```
- Mike Selander 10:05 pm on April 6, 2020
  
  These are great changes @jrf 👏 I would personally love to see these adopted into WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and see these patterns established ahead of WP catching up to modern PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher patterns.