Developer Documentation

Warning: This version of Altis is no longer supported

Upgrading to v4

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

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

{
	"require": {
		"altis/altis": "^4.0.0"
	},
	"require-dev": {
		"altis/local-chassis": "^4.0.0",
		"altis/local-server": "^4.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

Analytics

To accomodate Experience Blocks, some data in the analytics store has changed.

Arbitrary query string parameters are now available as qv_... attributes. In line with this, the special utm_campaign, utm_source, and utm_medium attributes have been removed, and the qv_ prefixed equivalents should be used instead.

Block Editor

The updated Block Editor in Altis v4 includes many changes, including deprecations to certain APIs. These changes may require updates to components such as sidebars or custom blocks, and these should be tested thoroughly. The field guide for WordPress 5.4 covers some of these changes.

The Block Editor also includes changes to markup generated by the block editor. These changes will likely require updates to theme CSS to accomodate the new DOM structure, and may require changes to both JavaScript and PHP code that interacts with the structure of any relevant blocks.

Under the hood, we've made significant improvements to Altis' support for searching multilingual content. Changes to stemming and stopwords across all of the languages we support, as well as changes to the search schema, necessitate changes to your Elasticsearch index to improve the text analysis.

We recommend reindexing as soon as possible to take advantage of the new language analyzers. You can reindex by running:

wp --url=... elasticpress index --setup --network-wide

(Some sites with large posts or large metadata sizes may encounter errors while reindexing which reference the payload size. Try passing --posts-per-page 200 and other smaller numbers to decrease the chunk size, or contact the Altis Cloud team for advice.)

Headline Features

Experience Blocks

Altis v4 includes Experience Blocks, allowing content creators to seamlessly create personalised experiences.

Experience Blocks is built on top of, and requires, the Native Analytics feature in the Analytics module. As Native Analytics gathers analytical data about end users, care should be taken to ensure you are meeting appropriate privacy and consent laws around personal data. Provided Native Analytics is enabled, no further work is required to enable or integrate Experience Blocks.

Alongside Experience Blocks, some analytics data has changed to improve the user experience. Underlying support for analytics data has been enhanced to support multiple values for each field in metrics and attributes.

Out of the box, the Audiences builder includes many useful fields from events, allowing users to build their audiences using live data. Additional data can be added to this UI using the new register_field() function, ensuring that the most relevant fields are displayed to your users.

WordPress 5.4 "Adderley"

The latest CMS module brings with it WordPress version 5.4. Some of the highlights are:

You can find the full WordPress 5.4 release notes here, and the developer field guide here.

Note that in line with our development and user experience philosophies, some changes in the CMS module may differ from WordPress changes. Notably in Altis v4, the fullscreen editor mode is not enabled by default.

Other Developer Features and APIs

Environment Indicators and Developer Tools Improvements

The current environment you are on (local, development, or staging) is now displayed in the top right corner of the admin screen alongside the Altis logo. This indicator is only displayed on non-production environments.

Additionally, you can now jump directly to the Altis Dashboard page for your current environment, easing the experience of viewing logs, deploying, and debugging requests. A new Open Support Ticket allows you to quickly open tickets for your current environment as well.

The developer tools now display your active Altis configuration, as well as information about Elasticsearch and ElasticPress queries used while rendering the page.

Search Configurability

The Search module has had significant improvements to its configurability, making it more useful in more cases.

A new search mode configuration option allows changing between simple and advanced search modes, with the latter offering the ability to use boolean operators. Additionally, a new strict flag allows constraining results to only those which include all terms, which is often a better experience when sorting by date or other fields rather than by relevance score.

New options for the under-the-hood configuration also allow boosting fields, as well as configuring ElasticPress options such as faceting and WooCommerce integration.

Support for multilingual search has been improved, with vastly improved support for non-Latin languages such as Chinese and Japanese, as well as improved stemming and stop words in many other languages. In v5, we'll be building off this functionality to provide user-defined dictionaries; let us know if you're interested!

Local Environment Improvements

Local Chassis now includes additional commands and aliases to improve usability, including ssh, restart, and destroy.

Likewise, Local Server's command has shortened from local-server to server, and additional aliases have been added to ensure both development environments act similarly.

Local Server also now has a db subcommand to query the MySQL database directly, plus db info to display information and db sequel to instantly connect to the database in Sequel Pro.

Security Improvements

The Security module now includes the ability to set up Basic authentication to limit access to a site. This allows limiting access to a staging or development environment without affecting your user roles, and allows for testing unauthenticated access to a site while keeping the site protected.

Users are now limited to 4 attempts at logging in before being locked out for 12 hours. Failed attempts can be set to notify the site administrators, ensuring your site remains secure against brute force attacks while keeping you informed. This feature is fully configurable, and can be easily disabled if not desired.

Internal APIs and helpers

Altis now provides the ability to register Extended Custom Post Types, which provide sensible defaults for custom post types and taxonomies, while adding additional functionality. (This is powered by the Extended CPTs library behind the scenes.)

A new clean_html() sanitizing function has been added to allow escaping strings for output while allowing certain tags through. For example, this can be used to escape translated strings which contain links while preventing arbitrary HTML from being inserted.

Edit this page on GitHub