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 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 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.

Continue reading

#modernizewp, #codingstandards, #php, #wpcs

PHP Native JSON Extension Now Required

The PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 native JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. extension has been bundled and compiled with PHP by default since 5.2.0 (2006). However, a significant number of PHP installs did not include it. In order to ensure a consistent experience for JSON related functionality in all supported versions of PHP, WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. has historically included a large number of workarounds, functions, and polyfills.

In 2011 (WordPress 3.2), an attempt was made to remove JSON related compatibility code. However, it was discovered that a fair number of distributions were still missing the PHP JSON extension by default, and the removed code was restored to ensure compatibility.

In WordPress 5.2, the minimum version of PHP supported was raised from 5.2.6 to 5.6.20. In the 8 year period since the last attempt was made to encourage use of the PHP native JSON extension, the number of distributions with this extension disabled has significantly decreased.

Because of this, the PHP native JSON extension is now required to run WordPress 5.3 and higher.

To prevent compatibility issues, a sitesite (versus network, blog) that does not have the PHP native JSON extension enabled will see an error message when attempting to upgrade to WordPress 5.3. The update will be cancelled and the site will remain on the current version (see [46455]). This is to prevent potential compatibility issues on servers running custom PHP configurations.

Here’s a summary of what has changed.

Deprecated

The following functions and classes will remain in the code base, but will trigger a deprecated warning when used (see [46205]):

  • The Services_JSON and Services_JSON_Error classes and all methods
  • The wp-includes/class-json.php file
  • The (private) _wp_json_prepare_data() function

Removed

The following functions, and classes have been removed entirely from the code base (see the [46208] changeset):

  • json_encode() function polyfill
  • json_decode() function polyfill
  • _json_decode_object_helper() function polyfill
  • json_last_error_msg() polyfill
  • JsonSerializable interface polyfill
  • $wp_json global variable
  • JSON_PRETTY_PRINT constant polyfill
  • JSON_ERROR_NONE constant polyfill

Unchanged

The wp_json_encode() function will remain with no intention to deprecate it at this time. This function includes an extra sanity check for JSON encoding data and should still be used as the preferred way to encode data into JSON.

For more information about these changes, check out #47699 on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. and the relevant changesets ([46205], [46206], [46208], [46377], and [46455]).

Props @jrf & @jorbin for peer review.

#5-3, #dev-notes, #php

WP 5.3: Introducing the spread operator

In WordPress 5.3, the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 5.6 spread operator has been introduced to WordPress in a number of places.

Using the spread operator allowed for simplifying the code and improves performance – both in speed as well as memory use -, especially as it has been introduced in a number of functions which are used a multitude of times during every single pageload, such as current_user_can() and add_query_arg().

For full details, see Trac ticket #47678.

Impact on plugins/themes

Most plugins and themes should see no impact of these patches, other than the improved performance.

However, if your 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/theme is one of the limited number of plugins and themes which extends one of the below listed classes and overloads any of the listed methods, you will need to take action.

What to do if your plugin/theme is affected

In nearly all cases, WP 5.3 has added a new parameter to the function signature using the spread operator. This allows for an easy transition as you can adjust the function signature of the method overloading it to do the same.
You may also want to adjust the code within the overloaded method to get the same performance benefits as the parent method.

See the relevant patches linked below for the full details of the change to each method and for inspiration.

Adding the extra argument will allow your plugin/theme to be compatible with both WP 5.3 and older WP versions, though it does raise the minimum PHP requirement for your plugin/theme to PHP 5.6.
Makemake A collection of P2 blogs at make.wordpress.org, which are the home to a number of contributor groups, including core development (make/core, formerly "wpdevel"), the UI working group (make/ui), translators (make/polyglots), the theme reviewers (make/themes), resources for plugin authors (make/plugins), and the accessibility working group (make/accessibility). sure you annotate this in the readme.txt!

In only one case – wpdb::prepare() -, WP 5.3 has changed an existing parameter.
In the exceptional situation that you would be overloading that method, you will need to make a choice whether you want to continue supporting older WP versions or to set the minimum WP version to WP 5.3.
If you set the minimum WP version to WP 5.3, you need to change the function signature of the overloading method to match the new function signature in WP 5.3 and you may also want to simplify some code in your method too.
If you want to continue to support older WP versions, you will need two versions of the class overload and an if/else toggle to load the correct one depending on the WP version being used.
Note: this really only applies to overloaded wpdb::prepare() methods. There is no need to do this if you overload any of the other affected methods.

What will break if I don’t make the change to my plugin/theme

Nothing. The world will keep turning as it did before.

You may get some complaints from end-users that they are seeing PHP warnings about a mismatched function signature in their PHP error logs, but other than that, all should still work as before.

This is not to say that you shouldn’t update your plugins/themes… You should.
It is just that if you don’t have time to do it right away, you don’t need to worry that your plugin/theme will be bringing sites down.

List of affected classes:

List of affected test classes:

#fortheloveofcode, #modernizewp, #5-3, #dev-notes, #php

PHP Coding Standards Changes

This is a follow-up to several changes proposed a few months ago.

While reading these changes, it’s important to keep in mind that they only apply to WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.: you can (and should) choose practices that best suits your development style for your own plugins and themes. The coding standards are intentionally opinionated, and will always lean towards readability and accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) over being able to use every possible language feature.

Closures (Anonymous Functions)

There was quite a lot of discussion around this proposal, particularly with regards to allowing closures as hook callbacks. Thank you everyone for your input, and for keeping disagreements respectful. 🙂

We do need a decision, however, and there were several key points that led to this:

  • It’s currently difficult to remove closures as hook callbacks. #46635 has several interesting proposals to address this in an entirely backward compatible manner.
  • While WordPress Core should strive to allow any callback to be unhooked, plugins have no such restriction.
  • The WordPress 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/. Coding Standards allow for closures to be used, we should be aiming to bring the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 standards in line with that.
  • The broader PHP world has embraced closures for many years, and have found ways to use them responsibly. We shouldn’t ignore PHP usage outside of WordPress.

With these points in mind, a conservative, but practical step is to allow closures as function callbacks, but not as hook callbacks in Core. Ultimately, we should be able to allow any sort of complex callback to be attached to hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., but the Core APIs aren’t quite ready for it yet.

Coding Standards Change

Where appropriate, closures may be used as an alternative to creating new functions to pass as callbacks.

Closures must not be passed as 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. or action callbacks, as they cannot be removed by remove_action() / remove_filter() (see #46635 for a proposal to address this).

Short Array Syntax

A little less controversial, but still with varying opinions, was the proposal to require short array syntax ( [ 1, 2, 3 ] ) instead of long array syntax ( array( 1, 2, 3 ) ) for declaring arrays.

While I’m personally partial to short array syntax, there were two particularly convincing arguments for using long array syntax:

  • It’s easier to distinguish from other forms of braces, particularly for those with vision difficulties.
  • It’s much more descriptive for beginners.

So, this change to the coding standards is the opposite of what was originally proposed, but is ultimately the more inclusive option.

Coding Standards Change

Arrays must be declared using long array syntax in WordPress Core.

Short Ternary Operator

The original proposal was to allow the short ternary operator, but this change reverses that. There’s a good argument that it looks too much like the null coalesce operator, especially as they perform different functions.

Take the following example from Core:

$height = isset( $data['height'] ) ? $data['height'] : 0;

It’s not possible to reduce this line with the short ternary operator, but it can be trivially reduced with the null coalesce operator:

$height = $data['height'] ?? 0;

The vast majority of other ternary operators in Core (which don’t have an isset() test) look something like this:

$class = $thumb ? ' class="has-media-icon"' : '';

This also can’t be reduced using the short ternary operator.

As the null coalesce operator is a useful addition (which we’ll be able to use once the minimum PHP version bumps to 7+), whereas the short ternary operator can only be used in a handful of cases in Core, it’s better to avoid the potential confusion, and not use the short ternary operator.

Coding Standards Change

The short ternary operator must not be used.

Assignments Within Conditionals

Particularly when there are multiple conditions, it can be quite difficult to spot assignments occurring in a conditional. This arguably falls under the Clever Code guidelines, but hasn’t been formalised.

I got a little ahead of myself with this one, and have already removed all assignments in conditionals from Core. Adding this change to the standard formalises the practice.

Coding Standards Change

Assignments within conditionals must not be used.

#php, #wpcs

Coding Standards Updates for PHP 5.6

With the minimum PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 version increasing to 5.6 as of WordPress 5.2, now’s a good time to be reviewing the WordPress Coding Standards.

Here is a set of changes that I’d like to propose.

Anonymous Functions (Closures)

Anonymous functions are a useful way to keep short logic blocks inline with a related function call. For example, this preg_replace_callback() call could be written like so:

$caption = preg_replace_callback(
	'/<[a-zA-Z0-9]+(?: [^<>]+>)*/',
	function ( $matches ) {
		return preg_replace( '/[\r\n\t]+/', ' ', $matches[0] );
	},
	$caption
);

This improves the readability of the codebase, as the developer doesn’t need to jump around the file to see what’s happening.

Coding Standards Proposal

Where the developer feels is appropriate, anonymous functions may be used as an alternative to creating new functions to pass as callbacks.

Anonymous functions must not be passed as 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. or action callbacks in WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., as they cannot be removed by remove_action() / remove_filter() (see #46635 for a proposal to address this). Outside of Core, developers may pass anonymous functions as filter or action callbacks at their own discretion.

Namespaces

Namespaces are a neat way to encapsulate functionality, and are a common feature in modern PHP development practices. As we’ve discovered in the past, however, introducing namespaces to the WordPress codebase is a difficult problem, which will require careful architecture and implementation.

Side note: there’s currently no timeline for introducing namespaces to WordPress Core, expressions of interest are welcome. 🙂

Coding Standards Proposal

At this time, namespaces must not be used in WordPress Core.

Short Array Syntax

Rather than declaring arrays using the array( 1, 2, 3 ) syntax, they can now be shortened to [ 1, 2, 3 ]. This matches how arrays are declared in the WordPress 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/. Coding Standards.

To allow for plugins and themes that support older versions of WordPress, I’d like to propose that WordPress Core switches to short array syntax immediately, but plugins and themes may choose which they use. A future iteration would makemake A collection of P2 blogs at make.wordpress.org, which are the home to a number of contributor groups, including core development (make/core, formerly "wpdevel"), the UI working group (make/ui), translators (make/polyglots), the theme reviewers (make/themes), resources for plugin authors (make/plugins), and the accessibility working group (make/accessibility). short array syntax a requirement.

Coding Standards Proposal

Arrays must be declared using short array syntax in WordPress Core. Arrays may be declared using short array syntax outside of Core.

Short Ternary Syntax

A fairly common pattern when setting a variable’s value looks something like this:

$a = $b ? $b : $c;

The short ternary syntax allows this to be shortened, like so:

$a = $b ?: $c;

It’s important to note that this is different to the null coalesce operator, which was added in PHP 7. If $b is undefined, the short ternary syntax will emit a notice.

Coding Standards Proposal

Short ternary syntax may be used where appropriate.

Assignments within conditionals

While this isn’t directly related to the PHP version bump, I’d like to propose disallowing assignments within conditionals. Particularly when there are multiple conditions, it can be quite difficult to spot assignments occurring in a conditional. This arguably falls under the Clever Code guidelines, but hasn’t been formalised.

For example, this if statement would be written like so:

$sticky_posts = get_option( 'sticky_posts' );
if ( 'post' === $post_type && $sticky_posts ) {
	// ...
}

Coding Standards Proposal

Assignments within conditionals are not allowed.

Other New Features

Any other new features available in PHP 5.6 can be used, though we should continue to carefully consider their value and (in the case of newer PHP modules) availability on all hosts.


How do you feel about these changes? Are there other changes related to PHP 5.6 that you’d like to suggest?

#php, #wpcs

PHP Meeting Recap – December 17th

This recap is a summary of our previous PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 meeting. It highlights the ideas and decisions which came up during that meeting, both as a means of documenting and to provide a quick overview for those who were unable to attend.

You can find this meeting’s chat log here.

Chat Summary

  • The meeting focused on the individual pieces that are left to complete so that the most essential Servehappy parts can become part of the WordPress 5.1 releaseRelease A release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software. (planned schedule has first BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. set at January 10th).
  • For the fatal error recovery mechanism (see #44458 or GitHub PR for development) the following steps are needed:
    • Add support for recovering errors by the theme by pausing it. It was determined before that the adminadmin (and super admin) can work without an active theme, so implementation of this should be straightforward based on the existing code that already handles this for plugins.
    • In addition to displaying a note in the frontend when an error occurs (customizable via a php-error.php drop in), an email with the same message should be sent to the admin email address.
    • @schlessera will take care of implementing these two remaining tasks.
    • The multisitemultisite Used to describe a WordPress installation with a network of multiple blogs, grouped by sites. This installation type has shared users tables, and creates separate database tables for each blog (wp_posts becomes wp_0_posts). See also network, blog, site team will furthermore have an additional look at the existing implementation of multisite support.
  • A few updates are required for the Update PHP page:
    • Instead of having the content coming from the editor, it should be hardcoded and displayed via a template so that translationtranslation The process (or result) of changing text, words, and display formatting to support another language. Also see localization, internationalization. of the content is more streamlined and can happen via GlotPress. Furthermore it makes it a quicker process to add visual assets to the page later. @flixos90 is taking care of this.
    • The page slug needs to be changed from upgrade-php to update-php, as previously discussed, including a redirect. @sergeybiryukov has already completed this work.
  • For the actual notice in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. itself, a few tweaks need to be added.
    • The version numbers need to be updated for WordPress 5.1.
    • The link URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org to the page needs to be updated to account for the slug change.
    • The link URL needs to be customizable via both an environment variable (to be set by hosting providers) and a 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. (for later adjustments in the codebase).
    • @flixos90 is working on these updates as part of #45686.
  • In the Servehappy 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. endpoint, the recommended PHP version should be set to 7.3, and the lowest acceptable version should be set to 5.6 to account for the future version bump. On any version below that, WordPress users will see a warning. Furthermore the information on official PHP version support needs to be updated as both PHP 5.6 and 7.0 are no longer support (or will be in very few days). This update has as of now been committed already as well.
  • During the work on the MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. changes in the aftermath of the meeting, it came up that adjusting version numbers exposed by wordpress.org should become a more straightforward process that can happen in a central location. This part is not crucial to have prior to WordPress 5.1, but is a minor tweak to makemake A collection of P2 blogs at make.wordpress.org, which are the home to a number of contributor groups, including core development (make/core, formerly "wpdevel"), the UI working group (make/ui), translators (make/polyglots), the theme reviewers (make/themes), resources for plugin authors (make/plugins), and the accessibility working group (make/accessibility). maintenance simpler in the future.
  • Still left is enhancing the page content with visual assets. It was agreed that these should not contain any language-dependent text. Among the suggestions were:
    • a diagram of how the server hardware, PHP, and WordPress relate to each other
    • a timeline of PHP version history
  • None of the attendees felt capable or had availability to work on such visual assets. If you can help with this over the next couple weeks, please let us know in the comments or the #core-php channel on 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/..
  • Due to the holidays in many parts of the world, the meetings in the next two weeks are cancelled. Finishing the features for WordPress 5.1 is a high priority though, and communication should continue asynchronously as needed. The next official meeting will take place only a few days before the intended 5.1 Beta release, so at that point everything should preferably be good to be merged.

Next week’s meeting

  • Next meeting will take place on Monday, January 7th, 2019 at 16:00 UTC in #core-php.
  • Agenda: Finalize remaining WordPress 5.1 work in order to be ready in time for the first Beta (Janurary 10th).
  • If you have suggestions about this but cannot make the meeting, please leave a comment on this post so that we can take them into account.

#php, #servehappy, #summary

PHP Meeting Recap – December 3rd

This recap is a summary of our previous PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 meeting. It highlights the ideas and decisions which came up during that meeting, both as a means of documenting and to provide a quick overview for those who were unable to attend.

You can find this meeting’s chat log here.

Chat Summary