From ec7836300d23be35968a9e5f5ff8366ceda783cb Mon Sep 17 00:00:00 2001
From: Michal Kleiner <michal@innocraft.com>
Date: Tue, 9 Sep 2025 17:34:24 +0200
Subject: [PATCH 1/3] Allow annotations migration to work with both option and
 annotations tables

---
 Migrations/AnnotationsMigration.php | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/Migrations/AnnotationsMigration.php b/Migrations/AnnotationsMigration.php
index 728bc6f..c6a081f 100644
--- a/Migrations/AnnotationsMigration.php
+++ b/Migrations/AnnotationsMigration.php
@@ -15,13 +15,32 @@
 
 class AnnotationsMigration extends BaseMigration
 {
+    /**
+     * @param TargetDb $targetDb
+     * @return array
+     */
     public function validateStructure(TargetDb $targetDb)
     {
-        return array();
+        // since Matomo 5.5.0, annotations are stored in their own table
+        // and the AnnotationList class had been removed
+        if (!class_exists(AnnotationList::class)) {
+            return $this->checkTablesHaveSameStructure($targetDb, 'annotations');
+        }
+
+        return [];
     }
 
     public function migrate(Request $request, TargetDb $targetDb)
     {
+        // since Matomo 5.5.0, annotations are stored in their own table
+        // and the AnnotationList class had been removed
+        if (!class_exists(AnnotationList::class)) {
+            $this->migrateEntities($request, $targetDb, 'annotations', 'annotations', 'id');
+
+            return;
+        }
+
+        // before Matomo 5.5.0, annotations were stored in the options table
         $sourceName = AnnotationList::getAnnotationCollectionOptionName($request->sourceIdSite);
         $targetName = AnnotationList::getAnnotationCollectionOptionName($request->targetIdSite);
 

From 3bd30f656b5d36cd237be1311a09d9e0adf07e86 Mon Sep 17 00:00:00 2001
From: Michal Kleiner <michal@innocraft.com>
Date: Wed, 10 Sep 2025 14:34:54 +0200
Subject: [PATCH 2/3] Adjust annotations migration to report number of
 annotations to migrate

---
 Migrations/AnnotationsMigration.php   | 9 ++++++++-
 tests/System/Commands/MigrateTest.php | 2 +-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/Migrations/AnnotationsMigration.php b/Migrations/AnnotationsMigration.php
index c6a081f..dcff4c8 100644
--- a/Migrations/AnnotationsMigration.php
+++ b/Migrations/AnnotationsMigration.php
@@ -9,6 +9,7 @@
 
 namespace Piwik\Plugins\Migration\Migrations;
 
+use Piwik\Common;
 use Piwik\Option;
 use Piwik\Plugins\Annotations\AnnotationList;
 use Piwik\Plugins\Migration\TargetDb;
@@ -30,6 +31,11 @@ public function validateStructure(TargetDb $targetDb)
         return [];
     }
 
+    /**
+     * @param Request $request
+     * @param TargetDb $targetDb
+     * @return void
+     */
     public function migrate(Request $request, TargetDb $targetDb)
     {
         // since Matomo 5.5.0, annotations are stored in their own table
@@ -46,7 +52,8 @@ public function migrate(Request $request, TargetDb $targetDb)
 
         $annotations = Option::get($sourceName);
         if ($annotations) {
-            $this->log('Found annotations');
+            $annotationItems = Common::safe_unserialize($annotations) ?: [];
+            $this->log(sprintf('Found %d annotations', count($annotationItems)));
 
             $targetDb->insert('option', array(
                 'option_name' => $targetName,
diff --git a/tests/System/Commands/MigrateTest.php b/tests/System/Commands/MigrateTest.php
index 5a04eff..1507117 100644
--- a/tests/System/Commands/MigrateTest.php
+++ b/tests/System/Commands/MigrateTest.php
@@ -56,7 +56,7 @@ public function test_runMigration()
 Found 2 segments at 2019-01-10 02:48:01
 Processed SegmentsMigration at 2019-01-10 02:48:01
 Processing AnnotationsMigration at 2019-01-10 02:48:01
-Found annotations at 2019-01-10 02:48:01
+Found 1 annotations at 2019-01-10 02:48:01
 Processed AnnotationsMigration at 2019-01-10 02:48:01
 Processing CustomDimensionMigration at 2019-01-10 02:48:01
 Found 3 custom dimensions at 2019-01-10 02:48:01

From a1f91fc9010bb194b74a5b87c9a37effc1111b20 Mon Sep 17 00:00:00 2001
From: Michal Kleiner <michal@innocraft.com>
Date: Wed, 10 Sep 2025 14:45:24 +0200
Subject: [PATCH 3/3] Test the number of migrated annotations if separate table
 exists

---
 tests/System/Commands/MigrateTest.php | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tests/System/Commands/MigrateTest.php b/tests/System/Commands/MigrateTest.php
index 1507117..cb8e5f6 100644
--- a/tests/System/Commands/MigrateTest.php
+++ b/tests/System/Commands/MigrateTest.php
@@ -138,6 +138,14 @@ public function test_runMigration_actuallyCopiesValues()
         $archives = $targetDb->fetchAll('SELECT * FROM ' . self::$fixture->targetDb->prefixTable('archive_blob_2013_01'));
         $this->assertGreaterThanOrEqual(195, count($archives));
         $this->assertLessThanOrEqual(600, count($archives));
+
+        if (!class_exists('Piwik\Plugins\Annotations\AnnotationList')) {
+            $annotationsTable = self::$fixture->targetDb->prefixTable('annotations');
+            $this->assertContains($annotationsTable, $targetDb->listTables(), 'annotations table does not exist');
+
+            $annotationItems = $targetDb->fetchAll('SELECT * FROM ' . $annotationsTable);
+            $this->assertCount(1, $annotationItems);
+        }
     }
 
     /**