feat!: migrate pre-1.0 installs to opt-in use_slug

The pre-1.0 plugin always used the assigned page's slug as the CPT
URL base. As of 1.0.0 it's opt-in via the per-CPT use_slug option.
Without a migration, existing sites would silently switch from
/<page-slug>/<post> to /<cpt-default>/<post> on upgrade — breaking
every published URL.

Adds a Migrator that runs once on plugins_loaded (via Plugin::init):
walks the page-for-CPT mapping and enables use_slug for every CPT
that doesn't already have an explicit value. Tracked through a
pfcpt_db_version option so it short-circuits on subsequent loads.
Cleaned up by uninstall.php.

Author: nlemoine

release-please-config.json

@@ -10,6 +10,10 @@
 				{
 					"type": "generic",
 					"path": "plugin.php"
+				},
+				{
+					"type": "generic",
+					"path": "src/Lifecycle/Migrator.php"
 				}
 			]
 		}

src/Container.php

@@ -15,6 +15,7 @@
 use n5s\PageForCustomPostType\Integration\WordPressSeo;
 use n5s\PageForCustomPostType\Integration\Wpml;
 use n5s\PageForCustomPostType\Lifecycle\LifecycleManager;
+use n5s\PageForCustomPostType\Lifecycle\Migrator;
 use n5s\PageForCustomPostType\PostType\PostType;
 use WP_Query;
 use wpdb;
@@ -59,6 +60,8 @@ public function __construct()
 
             SettingsValidator::class => static fn (): SettingsValidator => new SettingsValidator(),
 
+            Migrator::class => static fn (): Migrator => new Migrator(),
+
             Handler::class => fn (): Handler => new Handler(
                 $this->get(Api::class)
             ),

src/Lifecycle/Migrator.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace n5s\PageForCustomPostType\Lifecycle;
+
+use n5s\PageForCustomPostType\Core\Api;
+
+/**
+ * Runs one-shot data migrations on plugin upgrade.
+ *
+ * The current schema version is stored in the `pfcpt_db_version` option.
+ * Migrations short-circuit once that option is at or above the target.
+ */
+final class Migrator
+{
+    private const DB_VERSION_OPTION = 'pfcpt_db_version';
+    private const CURRENT_VERSION = '1.0.0'; // x-release-please-version
+
+    public function migrate(): void
+    {
+        $installed = get_option(self::DB_VERSION_OPTION, '');
+        $installed = \is_string($installed) ? $installed : '';
+
+        if (version_compare($installed, self::CURRENT_VERSION, '>=')) {
+            return;
+        }
+
+        if ($installed === '') {
+            $this->migrateToOptInUseSlug();
+        }
+
+        update_option(self::DB_VERSION_OPTION, self::CURRENT_VERSION);
+    }
+
+    /**
+     * Pre-0.6.0 always used the assigned page's slug as the CPT URL base.
+     * From 0.6.0 it's opt-in via the per-CPT use_slug option. Preserve the
+     * old URLs for upgrading sites by enabling use_slug on every assigned
+     * CPT that doesn't already have an explicit value.
+     */
+    private function migrateToOptInUseSlug(): void
+    {
+        $mapping = get_option(Api::OPTION_PAGE_IDS, []);
+        if (!\is_array($mapping)) {
+            return;
+        }
+
+        foreach (array_keys($mapping) as $postType) {
+            if (!\is_string($postType) || $postType === '') {
+                continue;
+            }
+
+            $optionName = Api::OPTION_PREFIX . $postType . Api::OPTION_SUFFIX_USE_SLUG;
+            if (get_option($optionName) === false) {
+                update_option($optionName, '1');
+            }
+        }
+    }
+}

src/Plugin.php

@@ -15,6 +15,7 @@
 use n5s\PageForCustomPostType\Integration\WordPressSeo;
 use n5s\PageForCustomPostType\Integration\Wpml;
 use n5s\PageForCustomPostType\Lifecycle\LifecycleManager;
+use n5s\PageForCustomPostType\Lifecycle\Migrator;
 use n5s\PageForCustomPostType\PostType\PostType;
 
 /**
@@ -67,6 +68,7 @@ public function init(): self
             return $this;
         }
 
+        $this->container->get(Migrator::class)->migrate();
         $this->registerHooks();
         $this->initialized = true;
 

tests/Integration/MigratorTest.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace n5s\PageForCustomPostType\Tests\Integration;
+
+use n5s\PageForCustomPostType\Lifecycle\Migrator;
+use n5s\PageForCustomPostType\Tests\Fixtures\TestCase;
+
+class MigratorTest extends TestCase
+{
+    private Migrator $migrator;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->migrator = new Migrator();
+    }
+
+    public function testFreshInstallSetsDbVersionWithoutTouchingUseSlug(): void
+    {
+        delete_option('pfcpt_db_version');
+        delete_option('pages_for_custom_post_type');
+        delete_option('page_for_book_use_slug');
+
+        $this->migrator->migrate();
+
+        $this->assertNotEmpty(get_option('pfcpt_db_version'));
+        $this->assertFalse(get_option('page_for_book_use_slug'));
+    }
+
+    public function testUpgradeFromPreUseSlugEnablesUseSlugForAssignedCPTs(): void
+    {
+        $this->createFixtures();
+        delete_option('pfcpt_db_version');
+        delete_option('page_for_' . self::BOOK_POST_TYPE . '_use_slug');
+        delete_option('page_for_' . self::BIKE_POST_TYPE . '_use_slug');
+
+        $this->migrator->migrate();
+
+        $this->assertEquals('1', get_option('page_for_' . self::BOOK_POST_TYPE . '_use_slug'));
+        $this->assertEquals('1', get_option('page_for_' . self::BIKE_POST_TYPE . '_use_slug'));
+        $this->assertNotEmpty(get_option('pfcpt_db_version'));
+    }
+
+    public function testMigrationDoesNotOverwriteExplicitlySetUseSlug(): void
+    {
+        $this->createFixtures();
+        delete_option('pfcpt_db_version');
+        update_option('page_for_' . self::BOOK_POST_TYPE . '_use_slug', '0');
+
+        $this->migrator->migrate();
+
+        $this->assertEquals('0', get_option('page_for_' . self::BOOK_POST_TYPE . '_use_slug'));
+    }
+
+    public function testMigrationIsIdempotent(): void
+    {
+        $this->createFixtures();
+        update_option('pfcpt_db_version', '0.6.0');
+        delete_option('page_for_' . self::BOOK_POST_TYPE . '_use_slug');
+
+        $this->migrator->migrate();
+
+        $this->assertFalse(get_option('page_for_' . self::BOOK_POST_TYPE . '_use_slug'));
+    }
+}

uninstall.php

@@ -28,6 +28,7 @@
 unset($pfcptMapping, $pfcptPostType);
 
 delete_option('pages_for_custom_post_type');
+delete_option('pfcpt_db_version');
 
 // Catch any orphaned rows in wp_options for CPTs no longer present in the
 // aggregated mapping (e.g. a CPT was unregistered without cleanup).