Skip to main content

Upgrade from 1.x

v1.x was a focused module covering hreflang + canonicals + meta_robots. v2.x adds a meta template engine, JSON-LD, OG/Twitter, GraphQL, AI, audits, and an OOS rules engine — but it stays fully backward-compatible with everything 1.x shipped.

What hasn't changed​

  • All v1 features still work exactly as before — the underlying classes (HtmlHeadHreflang, HtmlHeadCanonical, UrlRelationshipRepository, Model/EntityTypeId/*) keep the same public API
  • byte8_seosuite_url table schema is unchanged
  • The meta_robots EAV attribute on categories and the meta_robots / hreflang_identifier columns on cms_page are unchanged
  • All v1 GraphQL fields (CategoryInterface.meta_robots, CmsPage.meta_robots, CmsPageItem.meta_robots) keep their resolvers
  • All v1 CLI commands (seosuite:category:generate, seosuite:product:generate, seosuite:delete) are untouched

What's new​

AreaSince
Meta title/description templatesv2.1
JSON-LD structured datav2.1
OG + Twitterv2.1
Per-store robots.txtv2.1
GraphQL seo: SeoMetadatav2.2
AI Meta Generator (CLI + queue + in-context button + cron)v2.3, v2.4
Hreflang validator + auto-matcher (CLI + grid)v2.4, v2.5
Index Budget Audit (5 auditors + grid + auto-fix + AI generate)v2.6, v2.7
Dashboard widget + nightly cron auditsv2.7
Layered-nav SEO controls + OOS Rules Engine + gridv2.8

What might surprise you​

1. Meta-title observer can override your existing values​

When you enable the meta template engine (byte8_seosuite/meta_templates/is_active = 1), the observer fires on every product / category / CMS page and writes a templated title into the page config — but only when the entity's native meta_title field is empty.

If you've previously relied on the catalog block's default fallback (product name with no template), enabling templates will replace it. Set per-product meta_title if you need the old behaviour for specific SKUs.

2. JSON-LD Product schema includes aggregateRating​

If magento/module-review is installed and any product has reviews, the Product JSON-LD will include the calculated aggregateRating. Google may pick this up and start showing star ratings in SERPs — desirable in most cases, but worth knowing if you need to coordinate with marketing.

3. Layered nav now noindex'd by default when enabled​

Layered Navigation SEO → Mode = noindex_any is the safest setting and is what installs default to when the feature is enabled. The feature itself is off by default, so this only bites when you explicitly turn it on. If your strategy is to keep some filter URLs indexable, switch Mode to noindex_unlisted and add those attribute codes to the allow-list before turning the feature on.

4. Hreflang scan output now lives in the database​

Pre-v2.5 the validator had no admin UI — output was CLI-only. Since v2.5, every scan replaces the previous results in byte8_seosuite_hreflang_issue. If you've been parsing CLI output in CI, the --format json flag still produces the same shape; the database table is purely additive.

Upgrade steps​

# Pin to the latest 2.x in composer.json:
"byte8io/magento-seosuite": "^2.8"

composer update byte8io/magento-seosuite
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
bin/magento setup:static-content:deploy -f   # production mode only

The setup:upgrade will create the four new tables (byte8_seosuite_meta_suggestion, byte8_seosuite_hreflang_issue, byte8_seosuite_index_issue, byte8_seosuite_oos_tracking) without touching anything from v1.

Rollback safety​

If you need to roll back to v1 after upgrading:

composer require byte8io/magento-seosuite:^1.2
bin/magento setup:upgrade

The four new tables will remain in the database (orphaned but harmless). You can drop them manually:

DROP TABLE byte8_seosuite_meta_suggestion;
DROP TABLE byte8_seosuite_hreflang_issue;
DROP TABLE byte8_seosuite_index_issue;
DROP TABLE byte8_seosuite_oos_tracking;

Existing v1 data in byte8_seosuite_url is preserved across the upgrade and rollback.