Upgrading to v3

If you are migrating an existing install to Altis check out the migrating guide here first.

To upgrade to Altis v3, edit your composer.json and change the version constraint for altis/altis and any local environment modules to ^3.0.0:

{
	"require": {
		"altis/altis": "^3.0.0"
	},
	"require-dev": {
		"altis/local-chassis": "^3.0.0",
		"altis/local-server": "^3.0.0"
	}
}

Next remove the vendor directory by running rm -rf vendor or on Windows rmdir vendor. You could also delete the directory using your code editor, finder or explorer.

Note: due to an issue in how Composer handles installation of composer-plugin packages the above step is required to ensure the new version of the required packages are used to manage the process.

Next run composer update to complete the upgrade. You should commit the updated composer.json and composer.lock files.

Before deploying to Altis environments, you will need to clear the build cache using the "Clear build cache" button. This button is located under the "Advanced actions" toggle on the Release tab of your dashboard.

Lastly you will need to update your database tables using the CLI:

On Altis Dashboard find the stack you have deployed to and run core update-db --network (wp is automatically prepended) in the WP CLI tab
For Local Chassis run composer chassis exec -- wp core update-db --network
For Local Server run composer local-server cli -- core update-db --network

If you use Local Chassis you will need to also update Chassis and its extensions by running composer chassis upgrade.

Breaking Changes

Media

Files for intermediate image sizes are no longer created but handled entirely by Tachyon if modules.media.smart-media is enabled in your config, which is the default. This is only a breaking change if you have code that relies on fetching those files (not the original or full size image) directly by their path.

Block Editor

The updated Block Editor in WordPress 5.3 has many updates to the bundled JavaScript packages such as React, as well as features in the @wordpress/data package. If you make use of helpers like wp.data.withDispatch you should test this update thoroughly.

Local Chassis

The config.local.yaml file generated by Local Chassis is now fully managed by Altis. Any manual changes made to it will be lost when running composer chassis provision. Modifications to config.local.yaml can now be defined in your composer.json config.

The version of ElasticSearch in use by Local Chassis has been changed from 5.6 to 6.3 to match the production environment. In most cases this should not present any problems and may only require you to reindex by running composer chassis exec -- wp elasticpress index --setup --network-wide --url=<project>.local if you do encounter any problems.

Headline Features

WordPress 5.3 "Kirk"

The latest CMS Module brings with it WordPress version 5.3. Some of the highlights are:

For super-large images, image resizing now uses a scaled-down version of the original image, significantly improving frontend performance
The Block Editor has many accessibility improvements and enhanced layout features

You can find the full WordPress 5.3 release notes here.

Zero Configuration PHPUnit Testing

Writing and runnning PHPUnit tests for your application is now a simple process. Add your test classes to a directory called tests in your project root directory and run composer dev-tools phpunit.

Tests are run in your local environment, and provide full integration testing capabilities to match production, including S3, ElasticSearch, caching and Tachyon.

This feature provides flexibility for more complex use cases, check out the unit testing documentation and examples here.

Browser Security

Good security is a growing concern online, and the new browser security feature set provides a configurable solution for securing static assets and cross origin behaviour. Supported features include:

Automatic Subresource Integrity for first-party assets, and a framework for third-party assets
Automatic X-XSS-Protection and X-Frame-Options headers by default
Content Security Policy support, with smart defaults and highly configurable

Other Developer Features and APIs

Module Loading (Core Module)

Modules were previously loaded via Composer's autoload functionality, however this approach was limiting, as the entrypoint files contained side-effects and required a function_exists() check at the start of the file to prevent non-Altis CLI commands from breaking.

Modules now add an extra.altis section to their composer.json to be included a generated file called vendor/modules.php. This file is included from wp-config.php.

The advice for writing custom modules has now been updated to reflect this but any existing custom modules will remain backwards compatible.

Developer Tools Additions (Developer Tools module)

Query Monitor integration is now vastly improved with clickable traces for both PHP function calls and database queries that open in your editor.

In addition X-Ray data and the flamegraph are now available as panels in Query Monitor.

A default Travis CI config will be created if one does not already exist that will run the zero config PHPUnit tests.

Local Environment improvements (Local Chassis & Local Server modules)

Both Local Server and Local Chassis now support an exec command for running arbitrary commands in the development environment. composer chassis exec runs a command inside the virtual machine, while composer local-server exec runs a command inside the PHP Docker container.

You can now extend the default chassis configuration from your composer.json like so:

{
	"extra": {
		"altis": {
			"modules": {
				"local-chassis": {
					"hosts": [
						"altis.local",
						"subsite.altis.local"
					],
					"extensions": [
						"xdebug"
					]
				}
			}
		}
	}
}

If you make any changes to your Local Chassis config in composer.json run composer chassis provision to apply them, and if you ever want to fetch the latest version of Chassis you can run composer chassis upgrade.

As with the Local Chassis module there is now a composer local-server exec command for running arbitrary commands on the PHP docker container.

For convenience, Local Server supports XDebug with a feature flag. Run composer local-server start --xdebug to start the server with XDebug enabled. Documentation for using XDebug with popular editors can be found here.

Security improvements (Security module)

Passwords are now encrypted using BCrypt for enhanced security. In addition XML-RPC can now be switched off via configuration.

The Require Login feature now respects the "public" setting on each site. If a site is not public, users must be logged in to access it.

Cloud improvements (Cloud module)

Page caching is now made more performant by ignoring common query string parameters and caching redirects. It is also highly configurable and supports the Cloudfront-Viewer-Country header out of the box.

Check the page caching documentation for more information.

The Altis Dashboard has many enhancements including better performance and the ability to pin apps.

Media improvements (Media module)

The Tachyon service now has enhanced PNG compression support and deals with large image files much more quickly. In addition it is now isolated to each stack rather for a whole region to limit the impact of service issues.

Responsive images maintain their aspect ratio and use Tachyon's zoom parameter to automatically fetch resized images optimised for quality according to their display size. The image zoom factors are configurable via composer.json.

Images in Gutenberg and the REST API now have Tachyon support.

SVG images can now be uploaded safely & securely with XSS sanitisation.