Changes to the WordPress Core PHP Test Suite

Why were changes needed?

Dev Wapuu
Image credits: @marktimemedia

The WordPress test suite uses the industry standard PHPUnit tool to run the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher unit tests.

Over the years, PHPUnit has seen a number of changes, new assertions being introduced, different annotations and more, but most notably, as of PHPUnit 8.0, a void return type was added to the typical fixture setUp() and tearDown() methods.

This void return type is problematic in the context of WordPress, as return types in general were only introduced in PHP 7.0 and the void return type wasn’t introduced until PHP 7.1.
While WordPress still has a minimum PHP version of PHP 5.6, the void return type can not be introduced in the test suite as it would inhibit the tests from being run on PHP 5.6 and 7.0.

At the same time, having to run the tests on older PHPUnit versions (PHPUnit < 8.0) made it increasingly difficult to get the test suite to run on new PHP versions, like PHP 8.0 and the upcoming PHP 8.1 (expected end of November) as these older PHPUnit versions are no longer supported and are not being made compatible with newer PHP versions anymore.

Over the past few years, a number of different solution directions were explored and rejected, largely due to the large maintenance burden these would add to the small team of WordPress contributors maintaining the test framework.

With the upcoming release of PHP 8.1 as a driver, we took another look at this problem and the available tooling in the wider PHP field and a solution has now been implemented which should future-proof the test suite for, at least, a number of years.

The solution

The implemented solution is based on the external PHPUnit Polyfills library, which “allows for creating PHPUnit cross-version compatible tests by offering a number of polyfills for functionality which was introduced, split up or renamed in PHPUnit”.

The PHPUnit Polyfills also solves the void conundrum via a tailored TestCase using snake_case methods.

In effect, this means that the WP CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. test suite can now run on all PHPUnit versions between PHPUnit 5.7.21 up to the latest release (at the time of writing: PHPUnit 9.5.10), which allows for running the test suite against all supported PHP versions using the most appropriate PHPUnit version for that PHP version.

It also means that, as of mid August, the tests are being run against PHP 8.1 and fixes for PHP 8.1 compatibility are currently being made.

With the PHPUnit Polyfills in place, tests can now be written using the feature set of the highest supported version of PHPUnit.
The Polyfills library will fill in the gaps and ensure the tests can still run on lower versions of PHPUnit without problems.

What has changed?

  1. The Composer lock file has been removed.
    The version constraints in the composer.json file have been made stricter to ensure the developer experience is not negatively impacted by this with regards to coding standards checks.
  2. The PHPUnit Polyfills library at version ^1.0.1 has been added as a Composer dev dependency.
  3. All WordPress Core tests now use PHPUnit 9.x assertions and expectations.
  4. All WordPress Core tests now use snake_case fixture methods, i.e. set_up() instead of setUp() and tear_down() instead of tearDown().
  5. The minimum supported PHPUnit version has been raised to PHPUnit 5.7.21 (was 5.4.0).
  6. The WordPress Core test bootstrap file will no longer throw an error when the tests are being run with PHPUnit 8.x or 9.x.
  7. The WordPress Core test bootstrap file will throw an error when the PHPUnit Polyfills are not available or do not comply with the minimum version requirements.
  8. All WP Core native assertions now have an extra, optional $message parameter, just like all PHPUnit native assertions.
    Please use this parameter in all tests which contain more than one assertion to make debugging tests easier.
  9. The WP_UnitTestCase_Base::setExpectedException() method is deprecated and should no longer be used.
  10. The WP_UnitTestCase_Base::checkRequirements() method is deprecated and no longer functional, and in reality hasn’t been for a long time for anyone using it in combination with PHPUnit 7.0+.
  11. The copies of the PHPUnit SpeedTrapListener classes have been removed as they were never actively used in Core.
    Anyone who still wants to use the SpeedTrapListener can install it separately.
  12. The copies of the PHPUnit 9.x MockObject classes which were introduced in the WP Core test suite in WP 5.6 have been removed, as they are no longer needed when the tests are run on the appropriate PHPUnit version for the PHP version used.

While the above changes have been made in WordPress 5.9, a minimal selection of these changes has been backported to WordPress 5.2 – 5.8:

  1. The PHPUnit Polyfills at version ^1.0.1 is now a requirement for the test suites in WP 5.2 – 5.8 and this requirement will be enforced via the test bootstrap.
  2. … which makes all the polyfills for PHPUnit 9.x assertions and expectations available when running tests against WP 5.2 – 5.8.
  3. Additionally, snake_case wrapper methods have been added for the camelCase fixture method names, meaning that for WP 5.2 – 5.8, the snake_case fixture method names will work without needing further work-arounds, both for fixture declarations as well as for calling the parent::set_up() and the likes.

    There is one caveat to this: the backported implementation presumes a fixed order for calling the parent (camelCase) methods versus the child (snake_case) methods: for set_up*() methods: parent first, child second; for tear_down*() methods: child first, parent second.
    This is the standard order, but if you have a fixture method which diverges from this or doesn’t call the parent, you may get unexpected results.

These backports allow for backporting future (security) fixes for WordPress itself without having to make the accompanying tests compatible with older PHPUnit versions.

These backports will also make it more straightforward for extenders to continue to test their 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 against multiple WordPress versions.

For full details about all the changes, please have a read through Trac ticket 46149.

Changes under the hood which should not be noticeable:

A new PHPUnit_Adapter_TestCase class has been added. This class is nested in-between the WP_UnitTestCase_Base class and the PHPUnit TestCase class and provides the PHPUnit cross-version adapter layer.

All PHPUnit assertion polyfill methods which previously existed in WP Core have been removed as they are no longer necessary now this functionality is provided via the PHPUnit Polyfills library.
All polyfills for assertions/expectations which were previously in WP are still available, they are now just provided via the Polyfills package.

As for the Docker set up: the PHPUnit container is no longer needed and has been removed from the docker-compose config.

What hasn’t changed:

  • The PHPUnit class aliases (for support of PHPUnit 5), which WP provided are still available, though shouldn’t be needed anymore.
  • You can still extend the WP_UnitTestCase class for your tests and will receive access to everything which was available before + more (i.e. a complete set of polyfills).

Future changes

There is a ticket open to rename some of the WordPress native test helper methods to handle the “doing it wrong” and WP native deprecation notices, as the current method names (too) closely resemble a PHPUnit native method name, which can easily lead to confusion and use of the wrong methods in tests.

When that ticketticket Created for both bug reports and feature development on the bug tracker. is actioned, this dev-note will be updated with the relevant information.

What does this mean for contributors to WordPress Core?

In general:

If you use Composer locally, please run composer update --with-all-dependencies (or composer update -W for short) from the root of your WordPress clone now to make sure your install is updated and to get the most appropriate versions of the dependencies for the PHP version you are running on.

Go on, do that now. This dev-note will wait patiently for you to come back.

You will need to run this command semi-regularly in the future (whenever the composer.json file has been updated).

For WP 5.9 and higher, please don’t use composer install anymore.

If, for example for backports, you need to install the dependencies for WP 5.8 or lower, in that case, you still need to run composer install.

🎓 Why?

The first time you run composer install locally, it creates a composer.lock file and when you run Composer again, it will look at your composer.lock file to install the “locked” versions again.

Previously, with the committed composer.lock file, the lock file was managed and updated centrally. However, that also meant that you often would be running the dev tools at a version which wasn’t the most appropriate one for the PHP version you are working under. This was getting more and more problematic for running the tests, which is why the file was removed.

Now the composer.lock file is no longer committed, you have to update it yourself to make sure you receive the latest version of the dev dependencies appropriate for your PHP version and within the version constraints set in the composer.json file.

For running the Core tests:

If you usually run the Core tests via Docker using the npm run test:php command, you can continue to do so and all should still work as expected.

If you usually run the Core tests via a Composer installed version of PHPUnit, again, you can continue to do so and all should still work as expected as long as you followed the above instructions to run composer update -W first.

If you usually run the Core tests via a PHAR file, you either have to run composer update -W once in a while or you have to set up a clone of the PHPUnit Polyfills repo. For more information about this last option, please see the set up information in the handbook.
If you are running locally on PHP 7.2 or higher, you may want to download a more recent PHPUnit PHAR file (PHPUnit 8 or 9) to benefit from the advances which have been made in PHPUnit.

If you are running the tests locally on PHP 7.2 or higher, you may notice the test runs being faster and the output being enhanced as the tests will now run on a more recent PHPUnit version.

💡 Pro-tip:

Now might also be a good time to verify that your local wp-tests-config.php file is still in sync with the wp-tests-config-sample.php file.

Similarly, if you use a local phpunit.xml overload configuration file, it is strongly recommended to verify that any changes made in the phpunit.xml.dist (and multisite.xml) file are synced into your local configuration.

For writing tests for Core:

You can now use the full range of assertions as available in PHPUnit 9.5 in your tests. Please use the most appropriate assertion available.

Test fixture methods MUST use snake_case method names from now on as per the below table.

Old nameNew name
setUpBeforeClass()set_up_before_class()
setUp()set_up()
assertPreConditions()assert_pre_conditions()
assertPostConditions()assert_post_conditions()
tearDown()tear_down()
tearDownAfterClass()tear_down_after_class()

The Make Core handbook page about writing tests has been updated with this information.
The page has also been enhanced with more handy tips and tricks, so please have a read through!

What does this mean for plugins/themes running integration tests based on the WP Core test suite?

It is a known fact that there are a lot of plugins/themes which use the WordPress Core test framework as a basis for their integration tests.

If your plugin/theme is one of them, these changes will impact you as well.

Step-by-step: how to make your test setup compatible with these changes and with higher PHPUnit versions:

  1. Run your tests against PHP 7.4 with PHPUnit 7.x and WP 5.8.1 and make sure there are no pre-existing errors/failures.
  2. Add PHPUnit Polyfills as a Composer require-dev dependency (or inherit it from WP).
  3. If you add the Polyfills as a requirement and only support WP 5.9 and higher, remove the requirement for PHPUnit in favour of letting the Polyfills handle it. This will prevent potential future version constraint conflicts.
    • If you still need/want to run your tests against older WP versions, keep the PHPUnit requirement and make sure it is set to ^5.7.21 || ^6.5 || ^7.5 and let CI (continuous integration script) handle removing that requirement for WP 5.9.
    • Or do it in reverse and remove the requirement for dev and add it back in CI for older WP versions.
  4. Make sure the Polyfills autoloader is wired in to your test bootstrap.
    • If you’ve chosen to “inherit the Polyfills from WP”, in this context that means that you use a full clone of WordPress and will install the Composer dependencies for WordPress before running the tests. In that case, you should be all set.
    • If you use only a partial clone of WordPress, like when your tests have been set up using the WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ scaffold command, or if you don’t run WordPress’ Composer setup, please make sure you load the Polyfills autoloader in your test bootstrap before running the WP native test bootstrap.
      • If you include your Composer vendor/autoload.php file as your test bootstrap before you run the WP native test bootstrap, you’re all set already, the Polyfills autoloader will be included automatically.
      • Alternatively, you can add a require_once 'path/to/vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php'; in your test bootstrap before including the WP native test bootstrap.
      • As a last alternative, you can declare a WP_TESTS_PHPUNIT_POLYFILLS_PATH constant containing the absolute path to the root directory of the PHPUnit Polyfills installation in your plugin/theme’s own test bootstrap file.
        Again, this constant must be declared prior to running the WP native test bootstrap file.
  5. Search your codebase for declarations of the fixture methods, as well as calls to (parent) fixture methods, and replace camelCase with snake_case in the method names.
    Example:
    // Old:
    public function setUp() {
         parent::setUp();
         // Do something.
    }
    
    // New:
    public function set_up() {
        parent::set_up();
        // Do something.
    }
  6. Verify your tests run without errors after the changes by running them against PHP 7.4 on PHPUnit 7.x with WP 5.8 .
  7. Verify your tests run without errors after the changes by running them against PHP 7.4 on PHPUnit 7.x with WP trunk (= WP 5.9).
  8. While using WP trunk/5.9, switch to PHPUnit 8.x – look out for deprecation notices PHPUnit throws and just literally do what they tell you to do.
  9. While still using WP trunk/5.9, switch to PHPUnit 9.x – look out for deprecation notices PHPUnit throws and just literally do what they tell you to do.

Once you’ve run through these steps, your tests should be cross-version compatible with PHPUnit 5.7.21 – 9.5, able to run against the WordPress 5.2 to 5.9 branches and able to run on PHP 5.6 – 8.1.

Next, you may want to run your tests against PHP 8.0 and 8.1 using PHPUnit 9.x with WP 5.9 to see if your plugin/theme is compatible with these more recent PHP versions.

🚨 Pro-tip:

If you want your CI build to fail when PHPUnit encounters PHP native deprecation notices, make sure to add convertDeprecationsToExceptions="true" to your PHPUnit configuration file as the default value for this setting has been changed to false in PHPUnit 9.5.10/8.5.21.

Enabling this setting is strongly recommended for testing your plugin/theme against PHP 8.1, as PHP 8.1 introduces a lot of new deprecations.

What to do when running tests in CI against multiple WP/PHP combinations?

If you are running your plugin/theme integration tests against multiple WordPress and PHP combinations, you will most likely need to make some adjustments to your Continuous Integration (CI) script(s).

Which exact changes you need to make depends entirely on your specific setup. There is no “one size fits all” solution.

As a general rule of thumb:

  • WP 5.2 – 5.5 is able to run tests against PHP 5.6 – 7.4 with PHPUnit 5.x (PHP 5.6 and 7.0) – 7.x (PHP 7.1 and higher).
  • WP 5.6 – 5.8 is able to run tests against PHP 5.6 – 8.0 with PHPUnit 5.x (PHP 5.6 and 7.0) – 7.x (PHP 7.1 and higher).
  • WP 5.9 and higher is able to run tests against PHP 5.6 – 8.1 with PHPUnit 5.x – 9.x (use the most appropriate PHPUnit version for each PHP version).

Also see the PHP Compatibility and WordPress Versions and PHPUnit Compatibility and WordPress Versions pages in the Make Core handbook.

Other typical things to take into account and to work around when needed:

  • Is there a config - platform - php setting in your composer.json which fixes the PHP version to a specific version – typically PHP 5.6 – for installing dependencies ?
    If so, you may need to either selectively remove this setting or run Composer with --ignore-platform-reqs for certain WP/PHP combinations in your test matrix.
  • Has the composer.lock file been committed ?
    In that case, you may need to either selectively remove that file in CI before running composer install; or run composer update -W for certain WP/PHP combinations in your test matrix.
  • Do you use a complete clone of WP ?
    For WP 5.2 – 5.8, you’ll need to install the WP dependencies by using composer install.
    For WP 5.9 and higher, you’ll need to install the WP dependencies by using composer update -W.

To make sure you run the test against the right PHPUnit version, you may need to run (a variation on):

composer remove --dev phpunit/phpunit
composer update --dev yoast/phpunit-polyfills --with-dependencies --ignore-platform-reqs

💡 Did you know ?

If you use GitHubGitHub GitHub is a website that offers online implementation of git repositories that can can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ Actions to run your tests for continuous integration and PHPUnit and the PHPUnit Polyfills are your only external test dependencies, as of Setup-PHP 2.15.0 (expected soon), you can use the tools key in the shivammathur/setup-php action to install these:

- name: Setup PHP with tools
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.0'
    tools: phpunit-polyfills

For more information about the tools key for setup-php, see the action documentation.

For more information on how to wire in the PHPUnit Polyfills when installed via setup-php, see the FAQ section of the Polyfills documentation.

Anticipating some frequently asked questions

I’m a plugin/theme maintainer, but don’t use Composer, can I still run my integration tests?

Yes, but you do need to make sure that either the Polyfills are available via a Composer global or local installLocal Install A local install of WordPress is a way to create a staging environment by installing a LAMP or LEMP stack on your local computer. or via some other manner, like a clone of the repo.

If you haven’t looked at Composer before, now might be a good time to take a look at it.

I’m running my tests via another tool stack (like BrainMonkey, WP Mock, PHP Mock, WP Browser, PestPHP), how do the changes made to the WordPress test suite affect me?

Short answer: They don’t.

Long answer: if you want to run your tests against multiple PHP and PHPUnit combinations, you may still find the PHPUnit Polyfills library helpful to you.

If you’ve not heard of the above mentioned tools before and want to read up on them, here are some links:

I used the WP-CLI scaffold command to set up my integration tests. How do the changes made to the WordPress test suite affect me?

There is no automated way right now to adapt existing tests for which the initial was created via the WP-CLI scaffold command, to make use of the new setup.

The current recommendation is to go through the steps in “What does this mean for plugins/themes running integration tests based on the WP Core test suite?“, which might be more or less involved depending on what version of the scaffolded test setup you are currently using.

A future version of the WP-CLI scaffold plugin-tests command will provide an upgrade mechanism to automatically upgrade an existing test setup to the new requirements. This will include adding a fully Composer-based testing setup as a replacement for the current bootstrap logic, making a composer update possible in the future to keep up with further test setup changes.

If you’re interested in learning more about these plans for the future, please subscribe to the issue on GitHub to stay informed.

I’m using WP Test Utils for my unit and integration tests. How do the changes made to the WordPress test suite affect me?

WP Test Utils is a library offering utilities for both unit testing and integration testing for WordPress plugins and themes. WP Test Utils already includes the PHPUnit Polyfills.

For the unit testing part, which is based on BrainMonkey, you are not affected by the changes.

If you use the integration testing utilities, you will need to make the change from camelCase to snake_case for the fixture methods in your test suite and you can now potentially widen the PHPUnit version requirements for your integration tests (also see the information about this in step 3 of the “Step by step” guide and the information about adjusting CI scripts).

Presuming you were already using the PHPUnit Polyfills provided by the Test Utils to use modern assertions, that’s it. You’re done.

WP Test Utils will continue to handle the integration test bootstrapping, which allows for running the tests against multiple WordPress and PHP versions.

The first version of WP Test Utils which has full support for the test framework changes made in WP 5.9, is WP Test Utils 1.0.0.

WP Test Utils 1.0.0 also includes improved support for integration tests which were created using the WP-CLI scaffold command and support for running tests against WP versions which don’t include the backports, like WP 5.2 – 5.8 point releases released before today, as well as WP < 5.2.


Props to @hellofromtonya, @johnbillion, @dingo_d, @netweb, @sergeybiryukov, @swissspidy, @schlessera for reviewing ahead of publication.

#5-9, #build-test-tools, #dev-notes, #phpunit, #unit-tests

Gallery Block Refactor Dev Note

The problem

If you have ever added a custom link to an image 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. and then tried to do the same on a Gallery image, you will understand the frustration and confusion of not having consistency between different types of image blocks. This inconsistency is because the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Gallery block stores the details of the included images as nested <img> elements within the block content. Therefore, the images within a gallery look and behave different from images within an individual image block. There are some long-standing open issues related to this:

The only way to fix this with the Gallery block in its current state is to try and replicate the additional functionality that the Image block has in the Gallery block, and vice versa. While this would be possible, it would lead to an additional maintenance overhead to keep the UIUI User interface and underlying code in sync between the two blocks.

Changes made

To make the behavior of images consistent between the Image Block and Gallery, while avoiding code duplication, the core Gallery block has been refactored to save the individual images as nested core Image blocks using the standard core innerBlocks APIs. To make this work with the innerBlocks 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., the gallery structure also had to change from an ordered list to a collection of figure elements within a figure. This structure change also brings the core Gallery block into line with the W3C WAI guidelines on the grouping of images.

The structure change means that Gallery images now have the ability to add custom links, or custom styles, for each image. An example of the flexible Gallery layouts this opens up can be seen below.

Gallery images will also automatically inherit new functionality that is added to the Image block, including those added by plugins. Below is an example of a Gallery block making us of the Image wave style and vintage 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. option added by the CoBlocks 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.

Other benefits include being able to use the standard move, drag and drop, copy, duplicate, and remove block functionalities. Keyboard navigation also benefits from the adoption of the standard block model by the Gallery block.

Accessing the new Gallery Block

To access the new Gallery block you will need to download the latest version of the 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/ plugin. At the time of writing the change is still under an experimental flag, so once the plugin is installed check for an experimental setting ‘Enable the refactored gallery block’ and enable it if it is present:

If this flag is not present it means that the changes have been taken out of the experimental phase.

Currently, only new gallery blocks added after the experimental flag is turned on will be in the new format, all existing galleries will be editable and viewable in the current format. You can manually transform an old format gallery to the new format by clicking the ‘Update’ button that will appear in the block toolbar.

What theme and plugin authors need to do before 5.9

To support the new Gallery block format, plugin and theme authors should aim to do the following before the December release of this change in WordPress 5.9.

  • Add additional selectors to target the new nested image block in both the editor and front end (existing selectors must remain to support the existing gallery block content). The new structure can be seen below.
<figure class="wp-block-gallery blocks-gallery-grid has-nested-images columns-default is-cropped">
	<figure class="wp-block-image size-large">
		<img
			src="http://localhost/image1"
			alt="Image gallery image"
			class="wp-image-71"
		/>
	</figure>
	<figure class="wp-block-image size-large">
		<img
			src="http://localhost/image2"
			alt="Image gallery image"
			class="wp-image-70"
		/>
	</figure>
</figure>

Example CSSCSS Cascading Style Sheets. with selectors for old and new gallery formats:

.wp-block-gallery .blocks-gallery-item img,
.wp-block-gallery .wp-block-image img {

.wp-block-gallery .blocks-gallery-item figcaption,
.wp-block-gallery.has-nested-images .wp-block-image figcaption {

Test block transformations. Temporary transformation filters have been added to handle the transformation of 3rd party blocks to and from the new core gallery block format. However, block plugins with gallery transforms should still be tested with the Gutenberg plugin to ensure these transformations work correctly.

In the future, the temporary transformation filters may be deprecated, and plugin authors will then need to update their transformations to handle the new Gallery format. Notice will be given ahead of this change being made.

Additional context and considerations

Other existing solutions

Third-party block developers are currently solving some of the problems caused by the limitations of the core Gallery block by implementing their custom Gallery blocks. These include some of the missing functionality, like the ability to add custom links to individual images. This can be problematic for site owners and content editors due to a large number of Gallery blocks that offer very similar functionality, but none of which appear to provide a close match to the functionality available with individual core Image blocks.

There do not appear to be any examples of plugins that already solve this problem in a way that utilizes Image blocks as inner blocks.

Backwards compatibility considerations

This is a breaking change due to the fundamental change in the underlying Gallery structure. Due to the large number of Gallery blocks already in use, along with themes and plugins that may rely on the existing structure, the following steps have been taken to mitigate the impact of this change on theme and plugin developers as much as possible:

  • For the initial release in the Gutenberg plugin, there will be no automatic migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. of existing gallery content. This means that all existing gallery content will behave the same in the editor and front end as it does now, so will be compatible with existing plugins and themes. Only new gallery blocks added after this change will have the new structure in the editor and the front-end.  The plan is to add automatic migration of existing gallery content when loaded in the editor to the 5.9 WordPress release.
  • Two temporary transformation filters have been added that will handle the transformation of 3rd party blocks to and from the new core gallery block format.

Possible edge cases

The refactored Gallery format has been tested against the following sample block libraries that have existing transforms to and from the core Gallery block:

The following themes have also been tested to make sure that both the existing gallery content and the new format galleries display correctly:

  • TwentyNineteen
  • TwentyTwenty
  • TwentyTwentyOne
  • Astra
  • Arbutus

While the refactored gallery works effectively with these plugins and themes, there may be edge cases in other plugins and themes that have not been accounted for. Themes that heavily modify the gallery CSS based on the existing <ul><li></li></ul> will definitely need to be updated if the same style changes need to be applied to the new gallery format.  Therefore, it is recommended that theme and plugin authors test the changed gallery block well in advance of the 5.9 release.

Additional details about this change 

Previous discussions about this change can be found on the main pull request or call for testing.


Updated Oct 18 with additional information on Transformation, and CSS selectors.
Updated Oct 25 with instructions on how to access the new Gallery block while experimental

#5-9, #core-editor, #dev-notes, #gallery, #gutenberg

Miscellaneous block editor API additions in WordPress 5.8

WordPress 5.8 brings several additions and tweaks to the 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. editor 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..

Contextual patterns for easier creation and block transformations

We’ve all been there. Staring at a blank page sometimes with an idea of what you want to create; often with a mind as blank as the page. To make the creation process easier, there is now a way to suggest patterns based on the block being used. This is now implemented for the Query block and includes some coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. patterns to start with.

In addition, there is an API to suggest pattern transformations that are contextual to the currently selected blocks. So how this is different to the patterns current behaviour? Previously, patterns insert demo content that must be updated after insertion. With this feature, it’s possible to use some patterns and retain existing attributes or content.

So it’s for existing blocks!

An important thing to note here is that a pattern transform can result to adding more blocks than the ones currently selected. You can see this with an example like the below where we have a Quote block but the pattern consist of more blocks:

This is the first iteration of the feature that covers most simple blocks (without innerBlocks). A new experimental API has been created where we can mark what block attributes count as content attributes. You can see more details in the PR.

In the long run as this work continues and spreads to more blocks, it will be easier to create content and get inspired without leaving the editor.

Pattern Registration API

if you’re creating your own custom block patterns, there’s a new blockTypes property that will allow your patterns to show up in other contexts like the transform menu. blockTypes property is an array containing the block names.

/register_block_pattern(
     'heading-example',
     array(
         'title'         => __( 'Black heading' ),
         'categories'    => array( 'text' ),
         'blockTypes'    => array( 'core/heading' ),
         'viewportWidth' => 500,
         'content'       => ' <!-- wp:heading {"level":3,"backgroundColor":"black","textColor":"white"} -->
    <h3 class="has-white-color has-black-background-color has-text-color has-background">Demo heading</h3>
<!-- /wp:heading -->',
     )
 );

To learn more about block patterns, see this WordPress News article: So you want to make block patterns.

BlockControls group prop

In WordPress 5.8, core blocks toolbars have been updated and made more consistent across blocks by splitting them into 4 areas like shown in the following screenshot.

To do so a new group prop has been added to the wp.blockEditor.BlockControls component. Third-party block authors are encourage to use this prop in their block code to follow the core blocks design pattern.

<BlockControls group="block">
    <ToolbarButton onClick={ doSomething }>{ __( 'My button' ) }</ToolbarButton>
</BlockControls>

#5-8, #core-editor, #dev-notes

Block-styles loading enhancements in WordPress 5.8

WordPress 5.8 improves the way we load 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.-styles by introducing 2 new features:

  • Load styles only for rendered blocks in a page
  • Inline small styles

Only load styles for used blocks

This is an opt-in, non-breaking change. Using the should_load_separate_core_block_assets 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., developers can opt-in to this feature:

add_filter( 'should_load_separate_core_block_assets', '__return_true' );

Prior to WordPress 5.8, styles for all blocks were included in a style.css file that gets loaded on every page. By opting-in to separate styles loading, the following will happen:

  • The wp-block-library stylesheet changes: Instead of loading the wp-includes/css/dist/block-library/style.css file which contains all styles for all blocks, this handle will now load the (much smaller) wp-includes/css/dist/block-library/common.css file, which contains generic styles like the default colors definitions, basic styles for text alignments, and styles for the .screen-reader-text class.
  • Styles for blocks will only get enqueued when the block gets rendered on a page.

The above changes will only apply to the frontend of a site, so all editor styles will continue to work as they did before.

The difference between block themes and classic themes

Block themes

In a block theme, blocks get parsed before the <head> so we always know which blocks will be present prior to rendering a page. This makes it possible to add the block styles to the <head> of our document.

Classic themes

In a classic, php-based theme, when a page starts to render, WordPress is not aware which blocks exist on a page and which don’t. Blocks gets parsed on render, and what that means is that block-styles don’t get added in the <head> of the page. Instead, they are added to the footer, when print_late_styles() runs.

If you have an existing theme and you want to opt-in to this improvement, you will need to test your theme for style priorities. Opting-in to separate styles loading in a classic theme means that the loading order of styles changes. Block styles that used to be in the head will move to the footer, so you will need to check your theme’s styles and make sure any opinionated styles you add to blocks have a higher priority than coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. styles.

Taking advantage of separate styles loading to add 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 styles to blocks

It is possible to use this new feature to attach styles to existing block-styles, by inlining them.

If your theme adds styles to blocks, instead of loading a single file containing all styles for all blocks, you can split styles and have a single file per-block. This will allow you to only load your theme’s (or plugin’s) block styles only when a block exists on a page.

The function below is an example implementation of how to do that, with some additional tweaks:

  • It works both in WordPress 5.8 and previous versions
  • It has a fallback in case the should_load_separate_core_block_assets filter is disabled
  • It adds styles both in the editor and frontend
  • Checks for specific editor block styles.

Feel free to use this as an example, tweaking it to suit your needs and implementation.

/**
 * Attach extra styles to multiple blocks.
 */
function my_theme_enqueue_block_styles() {
	// An array of blocks.
	$styled_blocks = [ 'paragraph', 'code', 'cover', 'group' ];

	foreach ( $styled_blocks as $block_name ) {
		// Get the stylesheet handle. This is backwards-compatible and checks the
		// availability of the `wp_should_load_separate_core_block_assets` function,
		// and whether we want to load separate styles per-block or not.
		$handle = (
			function_exists( 'wp_should_load_separate_core_block_assets' ) &&
			wp_should_load_separate_core_block_assets()
		) ? "wp-block-$block_name" : 'wp-block-library';

		// Get the styles.
		$styles = file_get_contents( get_theme_file_path( "styles/blocks/$block_name.min.css" ) );

		// Add frontend styles.
		wp_add_inline_style( $handle, $styles );

		// Add editor styles.
		add_editor_style( "styles/blocks/$block_name.min.css" );
		if ( file_exists( get_theme_file_path( "styles/blocks/$block_name-editor.min.css" ) ) ) {
			add_editor_style( "styles/blocks/$block_name-editor.min.css" );
		}
	}
}
// Add frontend styles.
add_action( 'wp_enqueue_scripts', 'my_theme_enqueue_block_styles' );
// Add editor styles.
add_action( 'admin_init', 'my_theme_enqueue_block_styles' );

Inlining small assets

In some cases small stylesheets get loaded on WordPress sites. These stylesheets require the browser to make an additional request to get an asset, and while they benefit from caching, their small size doesn’t justify that extra request, and performance would improve if they were inlined.

To that end, an inlining mechanism was implemented. This is an opt-in feature, and can be handled on a per-stylesheet basis. Internally, only assets that have data for path defined get processed, so to opt-in, a stylesheet can add something like this:

wp_style_add_data( $style_handle, 'path', $file_path );

When a page gets rendered, stylesheets that have opted-in to get inlined get added to an array. Their size is retrieved using a filesize call (which is why the path data is necessary), and the array is then ordered by ascending size (smaller to larger stylesheet). We then start inlining these assets by going from smallest to largest, until a 20kb limit is reached.

A filter is available to change that limit to another value, and can also be used to completely disable inlining.

To completely disable small styles inlining:

add_filter( 'styles_inline_size_limit', '__return_zero' );

To change the total inlined styles limit to 50kb:

add_filter( 'styles_inline_size_limit', function() {
	return 50000; // Size in bytes.
});

Inlining these styles happens by changing the src of the style to false, and then adding its contents as inline data. This way we avoid backwards-compatibility issues in themes and any additional styles attached to these stylesheets using wp_add_inline_style will still be printed.

Please note that if a stylesheet opts-in to get inlined, that is no guarantee that it will get inlined.

If for example on a page there are 30 stylesheets that are 1kb each, and they all opt-in to be inlined, then only 20 of them will be converted from <link rel="stylesheet"/> to <style> elements. When the 20th stylesheet gets inlined the 20kb limit is reached and the inlining process stops. The remaining 10 stylesheets will continue functioning like before and remain <link> elements.

If your theme opts-in to the separate block-styles, core block styles by default have path defined so they can all be inlined.

Props @sergeybiryukov for proofreading this dev-note.

#5-8, #dev-notes

Blocks in an iframed (template) editor

The new template editor is loaded in an iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser. to isolate it from the rest of the adminadmin (and super admin) screen. This has the following benefits:

  • Admin styles no longer affect the editor content, so there’s no need to reset any of these rules.
  • Content styles no longer affect the admin screen, so 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. and theme CSSCSS Cascading Style Sheets. rules no longer need to be prefixed.
  • Viewport relative CSS units will work correctly. The dimensions of the editor content is usually not the same as the dimensions of the admin page, so without an iframe units like vw will be relative to the admin page.
  • Media queries will also work natively, without needing to fake them, as we did before, which is fragile.
  • In general, it makes the lives of block and theme authors easier because styles from the front-end can be dropped in with very little, if nothing, to adjust. This also applies to lighter blocks, where the editor DOM structure matches the front-end, which we highly recommend when possible.
  • With a separate window for the editor content, it’s possible for the selection in the editor to remain visible while also having a (collapsed) selection in the editor UIUI User interface, for example an input field for a URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org.

We currently only iframe new editors. While the new template editor has been iframed, the post editor remains unchanged. We do this to gradually test how existing blocks from plugins work within an iframed editor, since there are cases where a block could look broken or (less likely) error. We hereby urge 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 authors to test their blocks with the new template editor and contact us if they need help to adjust blocks to work in the iframe.

Document and window

The iframe will have a different document and window than the admin page, which is now the parent window. Editor scripts are loaded in the admin page, so accessing the document or window to do something with the content will no longer work.

Most blocks written in ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. should continue to work properly, except if you rely on document or window. To fix, you need to create ref to access the relative document (ownerDocument) or window (defaultView). Regardless of the iframe, it is good practice to do this and avoid the use of globals.

const ref = useRef();
useEffect( () => {
  const { ownerDocument } = ref.current;
  const { defaultView } = ownerDocument;
  // Set ownerDocument.title for example.
}, [] );
const props = useBlockProps( { ref } );

If you attach event handlers, remember that the useEffect callback will not be called if the ref changes, so it is good practice to use the new useRefEffect 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., which will call the given callback if the ref change in addition to any dependencies passed.

const ref = useRefEffect( ( element ) => {
  const { ownerDocument } = element;
  const { defaultView } = ownerDocument;
  defaultView.addEventListener( ... );
  return () => {
	defaultView.removeEventListener( ... );
  };
}, [] );
const props = useBlockProps( { ref } );

Other frameworks and libraries

For the editor, scripts such as jQuery are loaded in the parent window (admin page), which is fine. When using these to interact with a block in the iframe, you should pass the element reference.

const ref = useRefEffect( ( element ) => {
  jQuery( element ).masonry( … );
  return () => {
    defaultView.jQuery( element ).masonry( 'destroy' );
  }
}, [] );
const props = useBlockProps( { ref } )

But what if the library is using the global window or document and it’s out of your control?

Submit an issue or PR for the library to use ownerDocument and defaultView instead of the globals. Ideally, any library should allow initialisation with an element in an iframe as the target. It’s never impossible. Feel free to contact us to mention the issue.

In the meantime, you can use the script that is loaded inside the iframe. We’ve loaded all front-end scripts in the iframe to fix these cases, but note that ideally you shouldn’t use scripts loaded in the iframe at all. You can use defaultView to access the script.

const ref = useRefEffect( ( element ) => {
  const { ownerDocument } = element;
  const { defaultView } = ownerDocument;

  // Use the script loaded in the iframe.
  // Script are loaded asynchronously, so check is the script is loaded.
  // After the dependencies have loaded, the block will re-render.
  if ( ! defaultView.jQuery ) {
    return;
  }

  defaultView.jQuery( element ).masonry( … );
  return () => {
    defaultView.jQuery( element ).masonry( 'destroy' );
  }
} );
const props = useBlockProps( { ref } );

And that’s it! In summary, any problem that a block might have in the iframe is caused by using the document or window global at the root of it, either in the block’s code or a third party library. Ideally, all code uses the ownerDocument and defaultView relative properties.

#5-8, #dev-notes, #gutenberg

On layout and content width in WordPress 5.8

WordPress 5.8 introduces Global Settings and Global Styles. They allow theme authors to control and style the available features in the editor and the different blocks using a theme.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..

By using a theme.json file, in addition to the Global styles and settings capabilities, theme authors opt-in into the layout feature for 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. containers.

Layout config

Historically, themes had the responsibility to provide CSSCSS Cascading Style Sheets. styles in order to support aligning content (left, right). With the introduction of the block editor in WordPress 5.0, new alignments has been added to the mix (wide, full). In addition to that, the block editor allowed users to use container blocks (group, columns blocks) which potentially can change how their inner blocks are positioned and aligned. Taking all these variations into consideration has become a very difficult task for theme authors. To address these issues, WordPress 5.8 introduces the layout feature and config.

How do I migrate my theme

Themes that have a centered content area, need to define a layout setting in their `theme.json` file:

{
   "settings": {
       "layout": {
           "contentSize": "800px",
           "wideSize": "1000px"
       }
   }
}  

The block-editor will automatically read this config and provide the corresponding styles in the editor. It will allow all alignments to work properly without requiring the `add_theme_support( ‘align-wide’ )` call.

Themes are still required to provide the corresponding styles in the frontend of their sites, something like:

.entry-content > * {
    max-width: 800px;
    margin-left: auto !important;
    margin-right: auto !important;
}

.entry-content > .alignwide {
    max-width: 1000px;
}

.entry-content > .alignfull {
    max-width: none;
}

.entry-content > .alignleft {
    float: left;
	margin-right: 2em;
}

.entry-content > .alignright {
    float: right;
	margin-right: 2em;
}

Note:

It’s not possible for WordPress to generate these styles automatically for all themes because the entry-content className in the example above is not mandatory and may not exist. In the future, with the introduction of the upcoming block themes, these styles won’t be needed anymore.

Nested Blocks

For themes with the layout config enabled, container blocks (like group blocks) do not automatically inherit the layout config. Meaning the blocks added inside the containers will by default take all the available space and not have any wide/full alignments options unless the user defines the wide and content sizes for that particular container block or “inherits” the config from the default layout.

This also means that themers can drop any alignment specific CSS that was added specifically to support nested blocks.

#5-8, #dev-notes, #gutenberg

Introducing “Update URI” plugin header in WordPress 5.8

WordPress 5.8 introduces a new headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. available for 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 authors. This allows third-party plugins to avoid accidentally being overwritten with an update of a plugin of a similar name from the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ Plugin Directory.

Previously, any custom plugin which used the same slug than a plugin hosted on WordPress.org was taking a significant risk of being overwritten by an update of the latter.

WordPress 5.8 introduces a new Update URI plugin header field. If the value of this new field matches any URI other than https://wordpress.org/plugins/{$slug}/ or w.org/plugin/{$slug}, WordPress will not attempt to update it.

If set, the Update URI header field should be a valid URI and have a unique hostname.

Please note that authors of plugins hosted by WordPress.org don’t need to use this new header.

Some examples include:

  • Update URI: https://wordpress.org/plugins/example-plugin/
  • Update URI: https://example.com/my-plugin/
  • Update URI: my-custom-plugin-name

Update URI: false also works, and unless there is some code handling the false hostname (see the hook introduced below), the plugin will not be updated.

If the header is used on a w.org hosted plugin, the WordPress.org 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. will only return updates for the plugin if it matches the following format:

  • https://wordpress.org/plugins/{$slug}/
  • w.org/plugin/{$slug}

If the header has any other value, the API will not return any result. It will ignore the plugin for update purposes.

Additionally, WordPress 5.8 introduce the update_plugins_{$hostname} 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., which third-party plugins can use to offer updates for a given hostname.

This new hook filters the update response for a given plugin hostname. The dynamic portion of the hook name, $hostname, refers to the hostname of the URI specified in the Update URI header field.

The hook has four arguments:

  • $update: The plugin update data with the latest details. Default false.
  • $plugin_data: The list of headers provided by the plugin.
  • $plugin_file: The plugin filename.
  • $locales: Installed locales to look translations for.

They can be used to filter the update response in multiple use cases.

For reference, see tickets #32101, #23318, and changelog [50921].

Thanks @milana_cap for proofreading.

#5-8, #dev-notes

Various Block Editor API removals in WordPress 5.8

Removed APIs

Keeping deprecated 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/. APIs around has a cost on performance and bundle size. This means at some point we need to consider removing some of the very old deprecated APIs, especially the ones with very low usage. WordPress 5.8 does remove two APIs that were deprecated on WordPress 5.2.

  • EditorGlobalKeyboardShortcuts component, this was a component used to define some keyboard shortcuts of the 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. editor, it was not really meant to be used by third-party developers. We verified that it’s not used by any 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 in the repository but if you rely on this component, it should be safe to just replace with VisualEditorGlobalKeyboardShortcuts.
  • The hasUploadPermissions selector from the core store. We contacted all the three plugins in the repository that were still using this 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.. If you’re still relying on this selector on a private site/plugin, it can be safely replaced with select( 'core' ).canUser( 'create', 'media' )

Removed blocks

Before WordPress 5.0 and in the very early days of the 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/ plugin, we used to have a block called Subheading, this block has never been included in WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. as stable, it was hidden and deprecated very early. We expect its usage to be very small. WordPress 5.8 removes the code of this block meaning that if you open content relying on that block in the editor, it will ask you to fallback to the HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. block instead. We don’t expect this to have a noticeable impact on the frontend of your site.

#5-8, #block-editor, #dev-notes

REST API Changes in WordPress 5.8

The following is a snapshot of some of the changes to 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/. in WordPress 5.8. For more details, see the full list of closed tickets.

Widgets

WordPress 5.8 sees the introduction of a new 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.-based widgets editor and with it the creation of several REST API endpoints dedicated to widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. management. Before diving in to how the new endpoints operate, I’d like to provide some background about how widgets work that should make the following sections more clear.

Instance Widgets

The predominant way to create widgets is to subclass the WP_Widget base class and register the widget with register_widget. These are referred to as “multi” widgets. These widgets have multiple instances that are identified by their number, an incrementing integer for each widget type.

Each instance has its own setting values. These are stored and fetched by WP_Widget which allows for the REST API to include these values. However, since a widget’s instance can contain arbitrary data, for example a DateTime object, the REST API cannot always serialize a widget to 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.. As such, a widget’s data is always serialized using the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher serialize function and then base64 encoded. This data is also exposed with a hash value which is a wp_hash signature of this value to prevent clients from sending arbitrary data to be deserialized with unserialize.

For widgets that can be safely accept and expose their instance data as JSON, pass the show_instance_in_rest flag in the $widget_options parameter.

class ExampleWidget extends WP_Widget {
    ...
    /**
     * Sets up the widget
     */
    public function __construct() {
        $widget_ops = array(
            // ...other options here
            'show_instance_in_rest' => true,
            // ...other options here
        );
        parent::__construct( 'example_widget', 'ExampleWidget', $widget_ops );
    }
    ...
}

Reference Widgets

Far less common, but still supported, are widgets that are registered using wp_register_sidebar_widget and wp_register_widget_control directly. These are referred to as “reference”, “function-based”, or “non-multi” widgets. These widgets can store their data in an arbitrary location. As such, their instance values are never included in the REST API.

Widget Types

Accessible via /wp/v2/widget-types, the widget types endpoint describes the different widget types that are registered on the server. The endpoint is accessible to users who have permission to edit_theme_options. By default, this is limited to Administrator users.

Response Format

{
  "id": "pages",
  "name": "Pages",
  "description": "A list of your site’s Pages.",
  "is_multi": true,
  "classname": "widget_pages",
  "_links": {
    "collection": [
      {
        "href": "https://trunk.test/wp-json/wp/v2/widget-types"
      }
    ],
    "self": [
      {
        "href": "https://trunk.test/wp-json/wp/v2/widget-types/pages"
      }
    ]
  }
}

Encode Endpoint

Multi widgets have access to the /wp/v2/widget-types/<widget>/encode endpoint. This endpoint is used to convert htmlHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. form data for the widget to the next instance for the widget, render the widget form, and render the widget preview.

For example, let’s say we want to interact with 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. widget. First, we’ll want to request the widget form from the server.

POST /wp/v2/widget-types/meta/encode
{
  "instance": {},
  "number": 1
}

For now, let’s assume we’re working with a new widget. The instance is empty because this is a new widget, so we’ll be rendering an empty form. The number argument can be omitted, but including one is recommended to provide stable input ids. You’ll receive a response similar to this. The widget preview has been snipped for brevity.

{
  "form": "<p><label for=\"widget-meta-1-title\">Title:</label><input class=\"widefat\" id=\"widget-meta-1-title\" name=\"widget-meta[1][title]\" type=\"text\" value=\"\" /></p>",
  "preview": "<div class=\"widget widget_meta\">...</div>",
  "instance": {
    "encoded": "YToxOntzOjU6InRpdGxlIjtzOjA6IiI7fQ==",
    "hash": "77e9f20acb54fa4f77de5a865333c0e6",
    "raw": {
      "title": ""
    }
  }
}

The provided form can then be rendered and edited by the user. When you want to render a new preview or are ready to begin saving, call the encode endpoint again with the url encoded form data and the instance value returned from the first response.

POST /wp/v2/widget-types/meta/encode
{
  "instance": {
    "encoded": "YToxOntzOjU6InRpdGxlIjtzOjA6IiI7fQ==",
    "hash": "77e9f20acb54fa4f77de5a865333c0e6",
    "raw": {
      "title": ""
    }
  },
  "number": 1,
  "form_data": "widget-meta%5B1%5D%5Btitle%5D=Site+Info"
}

The REST API will call the widget’s update function to calculate the new instance based on the provided form data. The instance object can then be used to save a widget via the widgets endpoint.

{
  "form": "<p><label for=\"widget-meta-1-title\">Title:</label><input class=\"widefat\" id=\"widget-meta-1-title\" name=\"widget-meta[1][title]\" type=\"text\" value=\"Site Info\" /></p>",
  "preview": "<div class=\"widget widget_meta\">...</div>",
  "instance": {
    "encoded": "YToxOntzOjU6InRpdGxlIjtzOjk6IlNpdGUgSW5mbyI7fQ==",
    "hash": "0e9a5bff2d28cba322c8cd27cd4e77af",
    "raw": {
      "title": "Site Info"
    }
  }
}

Widgets Endpoint

The widgets endpoint is used for performing CRUDCRUD Create, read, update and delete, the four basic functions of storing data. (More on Wikipedia.) operations on the saved widgets. Like the widget types endpoint, the widgets endpoints required the edit_theme_options capability to access.

To retrieve widgets, make a GET request to the /wp/v2/widgets endpoint. The sidebar parameter can be used to limit the response to widgets belonging to the requested sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme..

To create a widget, for instance the widget from our previous example, make a POST request to the /wp/v2/widgets endpoint. The instance is the same value returned from the encode endpoint. The id_base is the unique identifier for the widget type and sidebar is the id of the sidebar to assign the widget to. Both are required.

POST /wp/v2/widgets
{
	"instance": {
		"encoded": "YToxOntzOjU6InRpdGxlIjtzOjk6IlNpdGUgSW5mbyI7fQ==",
		"hash": "0e9a5bff2d28cba322c8cd27cd4e77af",
		"raw": {
			"title": "Site Info"
		}
	},
	"sidebar": "sidebar-1",
	"id_base": "meta"
}

The endpoint will return information about the newly created widget.

{
  "id": "meta-1",
  "id_base": "meta",
  "sidebar": "sidebar-1",
  "rendered": "<div class=\"widget widget_meta\">...</div>",
  "rendered_form": "<p><label for=\"widget-meta-1-title\">Title:</label><input class=\"widefat\" id=\"widget-meta-1-title\" name=\"widget-meta[1][title]\" type=\"text\" value=\"Site Info\" /></p>",
  "instance": {
    "encoded": "YToxOntzOjU6InRpdGxlIjtzOjk6IlNpdGUgTWV0YSI7fQ==",
    "hash": "dac44c3ebfa0428fed61829fa151e4e8",
    "raw": {
      "title": "Site Info"
    }
  },
  "_links": {
    "self": [
      {
        "href": "https://trunk.test/wp-json/wp/v2/widgets/meta-1"
      }
    ],
    "collection": [
      {
        "href": "https://trunk.test/wp-json/wp/v2/widgets"
      }
    ],
    "about": [
      {
        "embeddable": true,
        "href": "https://trunk.test/wp-json/wp/v2/widget-types/meta"
      }
    ],
    "wp:sidebar": [
      {
        "href": "https://trunk.test/wp-json/wp/v2/sidebars/sidebar-1/"
      }
    ],
    "curies": [
      {
        "name": "wp",
        "href": "https://api.w.org/{rel}",
        "templated": true
      }
    ]
  }
}

Since the meta widget (and all other built-in widgets) is registered with show_instance_in_rest enabled you could bypass the encode endpoint and use instance.raw instead. For example, if we wanted to update the widget to have a new title, we could make the following PUT request to /wp/v2/widgets/meta-1.

PUT /wp/v2/widgets/meta-1
{
	"instance": {
		"raw": {
			"title": "Site Meta"
		}
	}
}

A PUT request can also be made to update the sidebar assigned to a widget by passing a new sidebar id in the request.

To delete a widget, send a DELETE request to the individual widget route. By default, deleting a widget will move a widget to the Inactive Widgets area. To permanently delete a widget, use the force parameter. For example: DELETE /wp/v2/widgets/meta-1?force=true.

Sidebars Endpoints

Found under /wp/v2/sidebars, the sidebars endpoint is used to manage a site’s registered sidebars (widget areas) and their assigned widgets. For example, the following is the response for the first footer area in the Twenty Twenty theme.

{
  "id": "sidebar-1",
  "name": "Footer #1",
  "description": "Widgets in this area will be displayed in the first column in the footer.",
  "class": "",
  "before_widget": "<div class=\"widget %2$s\"><div class=\"widget-content\">",
  "after_widget": "</div></div>",
  "before_title": "<h2 class=\"widget-title subheading heading-size-3\">",
  "after_title": "</h2>",
  "status": "active",
  "widgets": [
    "recent-posts-2",
    "recent-comments-2",
    "meta-1"
  ],
  "_links": {
    "collection": [
      {
        "href": "https://trunk.test/wp-json/wp/v2/sidebars"
      }
    ],
    "self": [
      {
        "href": "https://trunk.test/wp-json/wp/v2/sidebars/sidebar-1"
      }
    ],
    "wp:widget": [
      {
        "embeddable": true,
        "href": "https://trunk.test/wp-json/wp/v2/widgets?sidebar=sidebar-1"
      }
    ],
    "curies": [
      {
        "name": "wp",
        "href": "https://api.w.org/{rel}",
        "templated": true
      }
    ]
  }
}

The widgets property contains an ordered list of widget ids. While all other properties are readonly, the widgets property can be used to reorder a sidebar’s assigned widgets. Any widget ids omitted when updating the sidebar will be assigned to the Inactive Widgets sidebar area.

For example, making a PUT request to /wp/v2/sidebars/sidebar-1 with the following body will remove the Recent Comments widget, and move the Meta widget to the top of the sidebar.

PUT /wp/v2/sidebars/sidebar-1
{
  "widgets": [
    "meta-1",
    "recent-posts-2"
  ]
}

For more information about the changes to widgets in 5.8, check out the Block-based Widgets Editor dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase..

Additional Changes

Posts Collection Tax Query Accepts operator

By default, a post must contain at least one of the requested terms to be included in the response. As of [51026], the REST API accepts a new operator property that can be set to AND to require a post to contain all of the requested terms.

For example, /wp/v2/posts?tags[terms]=1,2,3&tags[operator]=AND will return posts that have tags with the ids of 1, 2, and 3.

See #41287 for more details.

Props to @noisysocks for reviewing.

#5-8, #dev-notes, #rest-api

Block-based Widgets Editor in WordPress 5.8

WordPress 5.8 introduces a new 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.-based widgets editor to the Widgets screen (Appearance → Widgets) and 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. (Appearance → Customize → Widgets). The new editor allows users to add blocks to their widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. areas using the familiar block editor interface introduced in WordPress 5.0. This gives users powerful new ways to customise their sites using the rich library of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and third party blocks. Existing widgets and third party widgets will continue to work and can be used alongside blocks.

Opting out of the block-based widgets editor

The block-based widgets editor is enabled in WordPress 5.8 by default. There are several ways to restore the classic editor:

  • A theme author may include remove_theme_support( 'widgets-block-editor' ). Learn more.
  • A site administrator may use the new use_widgets_block_editor 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.. Learn more.
  • A user may install and activate the Classic Widgets plugin.

New Widgets screen

The widgets.php adminadmin (and super admin) screen (Appearance → Widgets) now loads a block-based widgets editor which exists in the @wordpress/edit-widgets package.

The editor is built using ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. and is similar to the editor used for posts and pages (@wordpress/edit-post) and uses many of the same subsystems: @wordpress/interface and @wordpress/components for UIUI User interface, @wordpress/block-editor for block editing, @wordpress/data and @wordpress/core-data for persisting changes, and so on.

A new filterable function, wp_use_widgets_block_editor(), is used by widgets.php to determine whether to load the new block-based editor or the classic editor.

The Widgets screen is extendable via block editor APIs such as registerPlugin, registerBlockType, registerBlockVariation, and so on.

The Widgets screen uses new 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/. endpoints which are detailed in a seperate dev note.

New Customizer control

The Widgets section in the Customizer (Appearance → Customize → Widgets) now loads a new control (WP_Sidebar_Block_Editor_Control) which contains an embedded block-based widgets editor that exists in the @wordpress/customize-widgets package.

The editor is built using React and uses @wordpress/block-editor and @wordpress/components to implement its block editing interface. It does not use @wordpress/data or @wordpress/core-data to persist changes. Instead, the existing Customizer JavaScript API is used.

A new filterable function, wp_use_widgets_block_editor(), is used by WP_Customize_Manager to determine whether or not to log the new block-based editor control or the classic editor control.

The block-based widgets editor in the Customizer is extendable via block editor APIs such as registerBlockType, registerBlockVariation, and so on.

New block: Legacy Widget

Existing widgets and third party widgets can be edited in the block-based widgets editor via the new Legacy Widget block. This block has an identifier of core/legacy-widget and exists in the @wordpress/widgets package. The Legacy Widget block is compatible with most third party widgets.

Broadly speaking, the Legacy Widget block has three states:

  1. Select. When first inserted, the block displays a list of widgets available to choose from. The list can be customised using the widget_types_to_hide_from_legacy_widget_block filter.
  2. Edit. When selected, the block displays the widget’s control form fields. This is determined by the widget’s WP_Widget::form() implementation.
  3. Preview. When not selected, the block displays a preview of how the widget will look once saved. This is determined by the widget’s WP_Widget::widget() implementation. A “No preview available.” message is automatically shown when widget() does not output any meaningful HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers.. Learn more.

The Legacy Widget block is not available in other block editors including the post editor, though this can be enabled for advanced use cases.

New widget: Block

Blocks added to widget areas are persisted using the same widget storage mechanism added in WordPress 2.8. Under the hood, each block is serialised into HTML and stored in a block widget. This is represented by a new WP_Widget_Block subclass that extends WP_Widget. A block widget is a specialised case of the HTML widget and works very similarly.

If blocks are added to a widget area, and then the block-based widgets editor is disabled, the blocks will remain visible on the frontend and in the classic widgets screen.

Tips to prepare for the new block-based widgets editor

Use the widget-added event to bind event handlers

The Legacy Widget block will display a widget’s control form in a way that is very similar to the Customizer and is therefore compatible with most third party widgets. Care must be taken, however, to always initialise event handlers when the widget-added jQuery event is triggered on document.

( function ( $ ) {
    $( document ).on( 'widget-added', function ( $control ) {
        $control.find( '.change-password' ).on( 'change', function () {
            var isChecked = $( this ).prop( 'checked' );
            $control.find( '.password' ).toggleClass( 'hidden', ! isChecked );
        } );
    } );
} )( jQuery );

Use block_categories_all instead of block_categories

The block_categories filter has been deprecated and will only be called in the post and page block editor. 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 developers that wish to support the widgets block editor should use the new block_categories_all filter which is called in all editors. See #52920 for more details.

Allow migrating from widgets to blocks

Many core and third party widgets have a functionally equivalent block. For example, core’s Recent Posts widget is analogous to core’s Latest Posts block.

In order to avoid duplicate functionality, is is recommended that plugin authors provide a way for users to convert their existing widgets to any equivalent block. WordPress 5.8 provides a mechanism for doing this using block transforms:

  1. Configure your widget to display its instance in the REST API by setting show_instance_in_rest to true in $widget_options.
  2. Add a block transform to your block from the core/legacy-widget block.
  3. Hide your widget from the Legacy Widget block using the widget_types_to_hide_from_legacy_widget_block filter.

There is a guide containing more detailed instructions in the Block Editor Handbook.

Don’t use @wordpress/editor

Many legacy widgets call the wp.editor.initialize() 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/. function to instantiate a TinyMCE editor. If a plugin or block uses the @wordpress/editor package and enqueues wp-editor as a script dependency, this will re-define the wp.editor global, often resulting in a wp.editor.initialize is undefined error.

Don’t use functions like is_admin() that won’t work in a REST API request

Because the Legacy Widget block makes REST API requests in order to render widgets, admin-only functions like is_admin() and is_plugin_available() are not available.


Written by @andraganescu and @noisysocks.
Thanks to @talldanwp, @isabel_brison, @kevin940726, and @get_dave for reviewing.

#5-8 #dev-notes #feature-widgets-block-editor #widgets #block-editor