Upgrading to v5

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

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

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

As Altis v5 requires infrastructure changes, contact the Cloud team via the Dashboard support when deploying v5 to an environment for the first time.

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 (the command will automatically prepend wp) 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

SEO

AMP & Facebook Instant Articles

The AMP and Facebook Instant Articles plugins have been unbundled from Altis. This allows you to specify the versions of each directly in your Composer requirements. While these are no longer included with Altis, we plan to maintain compatibility with AMP in new features as necessary.

If you're using AMP in your project, after updating your Altis requirements, you will need to additionally require the AMP plugin. This requires first adding WordPress Packagist as a repository, then requiring the plugin from wpackagist:

composer require wpackagist-plugin/amp@1

Note that while Altis v4 bundles version 1 of the AMP plugin, version 2 is now available with many major changes, so consider updating at the same time.

If you're using Facebook Instant Articles, you will need to require the FBIA plugin. This requires first adding WordPress Packagist as a repository, then requiring the plugin from wpackagist:

composer require wpackagist-plugin/fb-instant-articles

Sitemaps

The MSM Sitemaps plugin previously used to provide the XML Sitemaps feature has been superseded by the new core support for Sitemaps introduced in WordPress 5.5. These core sitemaps were developed in collaboration between WordPress, Google and Human Made.

The update may require you to re-submit your sitemap index file in Google Search Console as it has been relocated from /sitemap.xml to /wp-sitemap.xml. The new index sitemap URL is automatically added to the robots.txt file.

The filters provided by MSM Sitemaps that were previously documented are no longer available. Please refer to updated Sitemaps documentation to learn how to achieve the same results.

Headline Features

ElasticPress v3

Enhanced Search now includes version 3 of ElasticPress, which includes several major changes.

The most significant of the changes is the introduction of Indexables, which now allow other types of data to be indexed in Elasticsearch. The Post Indexable (which matches previous functionality), Term Indexable, and User Indexable are included by default. Custom Indexables can be built to allow searching other types of data.

ElasticPress v3.4 includes many other new changes, including some internal changes, so consult the EP changelog for details.

Altis v5 retains compatibility with existing code and indexes, but we recommend reading the EP release notes to see if you can use new features or adjust for minor changes. Note that minor adjustments have been made to default behaviour in ElasticPress, so consult the Enhanced Search module documentation for further details on specifics.

Reindexing is not required for existing post content, however the new Indexables will require an initial index. Reindexing can be performed at your discretion.

Altis 5 now includes the ability to specify custom user dictionaries used during the Elasticsearch indexing process. This allows setting custom synonyms and stopwords in the index. Crucially, this improves search indexing capabilities in languages without space-delimited words, such as Japanese. Dictionaries can be specified at the network or site level, allowing for detailed customization and configuration.

Fuzzy search can now be configured. This allows tuning the allowed edit distance, prefix length, expansions and transpositions at a granular level to match desired behaviour.

Other changes included in the update to ElasticPress 3.4 also include the ability for users to adjust individual search queries, allowing results to be manually tuned or overridden, as well as better WooCommerce integration out of the box.

Reindexing is not required for changes to fuzzy matching but is required when user dictionaries are changed, unless using Elasticsearch version 7.8 or higher.

Elasticsearch 7.8+ support is currently experimental, please contact support if you wish to try upgrading.

Suggestions when searching

Search suggestions can now be retrieved from Elasticsearch using autosuggest mode. Autosuggest mode matches partial words rather than whole words, which improves relevance while typing.

Autosuggest mode also matches against a subset of post fields rather than all fields, and defaults to true when the current request is an admin-ajax.php request (i.e. DOING_AJAX === true).

Consult the search query integration documentation for further details on how to use and control this functionality.

This feature does require reindexing as it makes changes to the field mapping. Reindexing can be performed at your discretion.

WordPress 5.5 "Eckstine"

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

You can find the full WordPress 5.5 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 many of the major features in WordPress 5.5 are in the auto-update system, which is disabled in Altis.

X-Ray

The Altis Dashboard now has X-Ray analytics functionality built in, providing application performance management (APM) features, empowering you to dig into your performance over time. This allows you to examine up to 24 hours of data over any period from the past 30 days, and break down performance information at an aggregate level.

X-Ray now has improved documentation to allow you to better use, understand, and build atop the X-Ray functionality.

Additionally, data reported to X-Ray has been improved to remove noise and provide more accurate data. Internal health check requests sent by Altis Cloud infrastructure are no longer reported in X-Ray, and database queries now use the final query sent to the database.

Other Features and APIs

Post Cloning

The CMS module now includes the ability to clone posts, including their full post data and post metadata. This behaviour can be modified via the provided actions and filters.

Post GUIDs

In order to set the groundwork for future import/export and migration tooling, GUIDs for post objects in Altis now use UUID URNs ( e.g. urn:uuid:d72fdc38-1305-4568-9821-463120b250f3). This replaces the former URL-style GUIDs used for posts ( e.g. http://altis.local/?p=42).

Due to legacy use of the GUID field, some older code may attempt to use the GUID for image media source URLs. This code must be updated to use wp_get_attachment_url() instead, which will also ensure that Tachyon and the Altis CDN are correctly used.

New code should only use the GUID field to uniquely identify posts, and never as a URL.

Minimum version of the AWS SDK

The minimum version of the AWS SDK included with Altis has been bumped to 3.150.0. We recommend keeping the SDK up-to-date via Dependabot.

Multisite

The sites list in the Network Admin now displays a more user-friendly view of sites, using site names rather than domains. Additionally, some irrelevant options (such as the mark-as-spam ability) are now de-emphasised in the UI.

Development Environments

Compatibility issues with using Xdebug in Local Server on a Linux host have been fixed. The remote host configuration option is now set automatically for you internally in order to correctly route connections. Consult the Xdebug documentation for more information on how to use it in your editor.

Other Changes

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