Craft 3

Sprout SEO installation and update instructions for Craft 3.

# Requirements

  • Craft CMS 3.0.0 or a more recent version of Craft

# Installation via Plugin Store

  1. Find the plugin in the Plugin Store in your Craft Control Panel
  2. Go to Settings → Plugins and select “Install”

# Installation via Composer

  1. Open your terminal and go to your Craft project:
    cd /path/to/project
  2. Then tell Composer to load the plugin:
    composer require barrelstrength/sprout-seo
  3. In the Control Panel, go to Settings → Plugins and select “Install”

# Upgrading to Sprout SEO 4

Upgrading to Sprout SEO 4 requires upgrading to Craft 3.


Make sure you have updated to the latest version of Sprout SEO 3.x before updating to Sprout SEO 4.x for Craft 3. The update from Sprout SEO 2 to 3 on Craft 2 was a larger update than the update from Sprout SEO 3 to 4 when migrating from Craft 2 to Craft 3. See the Sprout SEO 3 upgrade documentation for more details.

# Breaking changes


Sprout SEO 4 removes Section Metadata as it was largely not necessary and can be easily created within an existing site architecture using Singles, Channels, and the provided Metadata field. Any Section Metadata will need to be manually moved to an appropriate section and Element Metadata field.

# Upgrading to Sprout SEO 4.4

Sprout SEO 4.4 updates how metadata is normalized and processed. For most users, these changes will not be noticed as metadata is generated and output in the same way. For users with custom implementations, please read below.

# Breaking changes

Metadata Model

Retrieving metadata from the Metadata model is no longer done directly on the model. Metadata is now stored in Meta Type classes on the Metadata Model's $metaTypes attribute. Values on the model represent the raw data necessary to calculate the final values. The raw data can be retrieved by calling the getRawData() method. The calculated values can be retrieved by calling the getMetaTagData() method.

$metadata = new barrelstrength\sproutseo\models\Metadata();

// Get all the static values stored that will be used to calculate the final metadata

// Get a multi-dimensional array metadata by Meta Type with key value arrays of all calculated metadata

Previously you could access meta attributes directly on the model. Using the updated Metadata model you will need to retrieve the calculated value by getting the metadata by type and calling the getter for the value you want to retrieve. See all Meta Types in the sprout-seo/src/meta folder of the plugin.


$searchMetaType = $prioritizedMetadataModel->getMetaTypes('search');

Custom Schema

Several values in Custom Schema are often determined by grabbing those metadata values from the Globals or Metadata models. As the Globals and Metadata models have changed, you will want to revisit any Custom Schema and ensure your data is being retrieved and processed properly.

Optimized metadata values should now be retrieved using their getters:

$metadata = $this->prioritizedMetadataModel;

$title = $metadata->optimizedTitle;
$description = $metadata->optimizedDescription;
$image = $metadata->optimizedImage;
$keywords = $metadata->optimizedKeywords;

$title = $metadata->getOptimizedTitle();
$description = $metadata->getOptimizedDescription();
$image = $metadata->getOptimizedImage();
$keywords = $metadata->getOptimizedKeywords();

Previously image IDs were stored as arrays. They are now stored as the image ID as a string.

$schema = $this->globals['identity'];

$imageId = $schema['image'][0] ?? null;

$imageId = $schema['image'] ?? null;

Globals meta column

The sproutseo_globals.meta column has been removed and Global Metadata is now calculated at the time it is needed. If you referenced the Globals::$meta column in any custom implementations, you can now just call the getter for the metadata you want from the final Metadata model.

Last Updated: 11/23/2023, 10:32:53 PM