double-opt-in / src / Migration / MigrationInterface.php

MigrationInterface.php in Double Opt-In for Contact Form 7 – Secure, GDPR-Compliant Email Verification 5.5.0, at src/Migration/MigrationInterface.php

73 lines 2.0 KB

Raw Download Zip

1	<?php
2	/**
3	* Migration Interface
4	*
5	* @package Forge12\DoubleOptIn\Migration
6	* @since 4.3.0
7	*/
8
9	namespace Forge12\DoubleOptIn\Migration;
10
11	if ( ! defined( 'ABSPATH' ) ) {
12	exit;
13	}
14
15	/**
16	* Interface MigrationInterface
17	*
18	* @api
19	*
20	* A migration is a one-shot, immutable schema change. Once a migration
21	* has shipped in a released version it MUST NEVER be edited; new changes
22	* are new migrations. The registry records applied migration IDs in the
23	* `f12_doi_applied_migrations` option so each migration runs exactly once
24	* per site.
25	*
26	* Rollback is intentionally not supported: if a migration needs to be
27	* reversed, ship a new forward-only migration that undoes it. This is
28	* operationally safer than a rollback-capable system because there is
29	* only ever one code path — forward.
30	*/
31	interface MigrationInterface {
32
33	/**
34	* Stable unique identifier for the migration.
35	*
36	* Convention: `{owner}_{yyyymmdd}_{short_slug}`. Example:
37	* - `core_20260501_add_reminder_column`
38	* - `addon_analytics_20260515_create_stats_cache`
39	*
40	* The ID becomes the primary key in the applied-migrations option. It
41	* MUST be unique across the whole core+addon ecosystem and MUST NOT
42	* change once released.
43	*
44	* @return string
45	*/
46	public function getId(): string;
47
48	/**
49	* Short human-readable description, used in admin notices and logs.
50	*
51	* @return string
52	*/
53	public function getDescription(): string;
54
55	/**
56	* Apply the migration.
57	*
58	* Called exactly once per site. Must be idempotent at the level of
59	* individual DDL statements (e.g. use `ADD COLUMN IF NOT EXISTS`
60	* where supported, or guard with a column-exists check) so that an
61	* accidental re-run does not crash.
62	*
63	* Throwing from `up()` aborts the migration without marking it as
64	* applied, so the registry will attempt it again on the next
65	* bootstrap. Use this behaviour deliberately — swallow-and-continue
66	* should be explicit.
67	*
68	* @param \wpdb $wpdb The WordPress database abstraction.
69	* @return void
70	*/
71	public function up( \wpdb $wpdb ): void;
72	}
73