Developer Documentation

Upgrading to v6

If you are migrating from WordPress to Altis, check out the migrating guide here first.

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

In addition you will need to change the config.platform.php property to 7.2.34 (if present).

{
	"require": {
		"altis/altis": "^6.0.0"
	},
	"require-dev": {
		"altis/local-chassis": "^6.0.0",
		"altis/local-server": "^6.0.0"
	},
	"config": {
		"platform": {
			"php": "7.2.34"
		}
	}
}

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.

Database Updates

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

There is also a Cavalcade database update to improve performance:

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

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

Breaking Changes

jQuery Updated to 3.5.1

If you find issues relating to jQuery in the JavaScript console you can try installing the jQuery Migrate plugin as a short term solution. It is advisable to make sure all of your dependencies are up to date and that any custom code is compatible with jQuery v3 if used.

Block Editor

The Resuable Blocks API has been moved from the @wordpress/editor package to its own package under @wordpress/reusable-blocks.

There are editor styling changes, notably block style font sizes now use relative units (em) for sizing so you may see some inconsistent styling in custom block UIs.

The <Toolbar/> component should no longer be nested to group sets of controls. In addition there are new <ToolbarItem/> and <ToolbarButton/> components that should be used as the only direct children of the <Toolbar/> or <BlockControls/> components.

PHP Version

In the lead up to Altis v7 PHP will be upgraded to PHP 7.4. Local Server and Local Chassis now offer the ability to opt-in to using PHP 7.4 to allow you to test and prepare your application for this upgrade.

To opt-in to using PHP 7.4 on either local environment you can use the following configuration:

{
	"extra": {
		"altis": {
			"modules": {
				"local-server": {
					"php": "7.4"
				},
				"local-chassis": {
					"php": "7.4"
				}
			}
		}
	}
}

The full list of breaking changes in PHP 7.4 can be found here.

Headline Features

Altis Privacy Module

The brand new Altis Privacy Module is the new home for all core functionality related to protecting your users' privacy.

The key highlights are:

  • A robust and highly extensible Cookie Consent API
  • Built in cookie consent banner
  • Out of the box integration with Altis Analytics and Google Tag Manager

WordPress 5.6 "Simone"

The latest CMS module includes WordPress 5.6. Some of the highlights of this release are:

  • Application Passwords make it easy to create tokens that can be used to make authenticated API requests using HTTP Basic Auth. The tokens cannot be used to log in to WordPress so provide a more secure way to interact with the API.
  • Block API v2 makes blocks more self contained by allowing for custom block wrapper components along with many other improvements.
  • The REST API Batch Framework makes it possible to combine the results from multiple API endpoints into a single request.

You can find the full WordPress 5.6 release notes here, and the developer field guide here. Some internal APIs and compatibility may have changed, especially in block editor APIs, so ensure you consult the field guide for a full list of changes.

Note that in line with our development and user experience philosophies, some changes in the CMS module may differ from WordPress changes. Notably one of the major features in WordPress 5.6 is in the autoupdate system, which is disabled in Altis.

Experience Block Analytics

Experience Blocks now support setting conversion goals allowing you to see how well your personalized content is performing. Out of the box the following conversion goals are supported:

  • Impressions, the percentage of page views a block appears on where the block was visible in the browser viewport
  • Clicking any link in the Experience Block's content
  • Submitting a form

Custom conversion goals can also be registered in PHP or JavaScript.

Other Features and APIs

Analytics Data Export

A new REST API endpoint has been added to enable downloading analytics in JSON or CSV format. This works well in conjunction with the new Application Passwords feature.

Composer v2 Support

Altis is now fully compatible with Composer version 2.

Development Environments

Xdebug for Local Server is now on version 3.

Media

A migration command for getting legacy image file names to work with Tachyon and later versions of WordPress has been added called wp media migrate-files.

Other Changes

Altis v6 includes many other small changes, consult the changelog for full details of all the changes shipped in this release.