From 491b311cb4454bf15741e88e76fb1c0b54c3fef1 Mon Sep 17 00:00:00 2001
From: Mark Story <mark@mark-story.com>
Date: Tue, 17 Sep 2024 23:37:56 -0400
Subject: [PATCH 1/2] Start to add Migrations versions of base interfaces

These are important interfaces for userland code. All of the current
migrations extend from phinx base classes. I'd like to try updating
migrations internals by doing the following changes

- [ ] Add SeedInterface and MigrationInterface.
- [ ] Add decorator that adapts between phinx and migrations. Manager::getSeeds(), getMigrations()
- [ ] Move phinx shims into adapter/decorator
- [ ] Update the internals to use migrations interfaces.
- [ ] Introduce a new base class that is all migrations
- [ ] Provide upgrade tool to update migration classes.

If all goes well, we'll have an opt-in path for applications to upgrade
to the new namespaces and code before a breaking change where phinx
compatibility is removed.
---
 src/MigrationsInterface.php | 319 ++++++++++++++++++++++++++++++++++++
 src/SeedInterface.php       | 190 +++++++++++++++++++++
 2 files changed, 509 insertions(+)
 create mode 100644 src/MigrationsInterface.php
 create mode 100644 src/SeedInterface.php

diff --git a/src/MigrationsInterface.php b/src/MigrationsInterface.php
new file mode 100644
index 00000000..046a54db
--- /dev/null
+++ b/src/MigrationsInterface.php
@@ -0,0 +1,319 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * MIT License
+ * For full license information, please view the LICENSE file that was distributed with this source code.
+ */
+
+namespace Migrations;
+
+use Cake\Database\Query;
+use Cake\Database\Query\DeleteQuery;
+use Cake\Database\Query\InsertQuery;
+use Cake\Database\Query\SelectQuery;
+use Cake\Database\Query\UpdateQuery;
+use Migrations\Db\Adapter\AdapterInterface;
+use Migrations\Db\Table;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * Migration interface.
+ *
+ * Implements the same methods as phinx but with Migrations classes.
+ */
+interface MigrationInterface
+{
+    /**
+     * @var string
+     */
+    public const CHANGE = 'change';
+
+    /**
+     * @var string
+     */
+    public const UP = 'up';
+
+    /**
+     * @var string
+     */
+    public const DOWN = 'down';
+
+    /**
+     * @var string
+     */
+    public const INIT = 'init';
+
+    /**
+     * Sets the database adapter.
+     *
+     * @param \Migrations\Db\Adapter\AdapterInterface $adapter Database Adapter
+     * @return $this
+     */
+    public function setAdapter(AdapterInterface $adapter);
+
+    /**
+     * Gets the database adapter.
+     *
+     * @return \Migrations\Db\Adapter\AdapterInterface|null
+     */
+    public function getAdapter(): ?AdapterInterface;
+
+    /**
+     * Sets the input object to be used in migration object
+     *
+     * @param \Symfony\Component\Console\Input\InputInterface $input Input
+     * @return $this
+     */
+    public function setInput(InputInterface $input);
+
+    /**
+     * Gets the input object to be used in migration object
+     *
+     * @return \Symfony\Component\Console\Input\InputInterface|null
+     */
+    public function getInput(): ?InputInterface;
+
+    /**
+     * Sets the output object to be used in migration object
+     *
+     * @param \Symfony\Component\Console\Output\OutputInterface $output Output
+     * @return $this
+     */
+    public function setOutput(OutputInterface $output);
+
+    /**
+     * Gets the output object to be used in migration object
+     *
+     * @return \Symfony\Component\Console\Output\OutputInterface|null
+     */
+    public function getOutput(): ?OutputInterface;
+
+    /**
+     * Gets the name.
+     *
+     * @return string
+     */
+    public function getName(): string;
+
+    /**
+     * Gets the detected environment
+     *
+     * @return string
+     */
+    public function getEnvironment(): string;
+
+    /**
+     * Sets the migration version number.
+     *
+     * @param int $version Version
+     * @return $this
+     */
+    public function setVersion(int $version);
+
+    /**
+     * Gets the migration version number.
+     *
+     * @return int
+     */
+    public function getVersion(): int;
+
+    /**
+     * Sets whether this migration is being applied or reverted
+     *
+     * @param bool $isMigratingUp True if the migration is being applied
+     * @return $this
+     */
+    public function setMigratingUp(bool $isMigratingUp);
+
+    /**
+     * Gets whether this migration is being applied or reverted.
+     * True means that the migration is being applied.
+     *
+     * @return bool
+     */
+    public function isMigratingUp(): bool;
+
+    /**
+     * Executes a SQL statement and returns the number of affected rows.
+     *
+     * @param string $sql SQL
+     * @param array $params parameters to use for prepared query
+     * @return int
+     */
+    public function execute(string $sql, array $params = []): int;
+
+    /**
+     * Executes a SQL statement.
+     *
+     * The return type depends on the underlying adapter being used. To improve
+     * IDE auto-completion possibility, you can overwrite the query method
+     * phpDoc in your (typically custom abstract parent) migration class, where
+     * you can set the return type by the adapter in your current use.
+     *
+     * @param string $sql SQL
+     * @param array $params parameters to use for prepared query
+     * @return mixed
+     */
+    public function query(string $sql, array $params = []): mixed;
+
+    /**
+     * Returns a new Query object that can be used to build complex SELECT, UPDATE, INSERT or DELETE
+     * queries and execute them against the current database.
+     *
+     * Queries executed through the query builder are always sent to the database, regardless of the
+     * the dry-run settings.
+     *
+     * @see https://api.cakephp.org/3.6/class-Cake.Database.Query.html
+     * @param string $type Query
+     * @return \Cake\Database\Query
+     */
+    public function getQueryBuilder(string $type): Query;
+
+    /**
+     * Returns a new SelectQuery object that can be used to build complex
+     * SELECT queries and execute them against the current database.
+     *
+     * Queries executed through the query builder are always sent to the database, regardless of the
+     * the dry-run settings.
+     *
+     * @return \Cake\Database\Query\SelectQuery
+     */
+    public function getSelectBuilder(): SelectQuery;
+
+    /**
+     * Returns a new InsertQuery object that can be used to build complex
+     * INSERT queries and execute them against the current database.
+     *
+     * Queries executed through the query builder are always sent to the database, regardless of the
+     * the dry-run settings.
+     *
+     * @return \Cake\Database\Query\InsertQuery
+     */
+    public function getInsertBuilder(): InsertQuery;
+
+    /**
+     * Returns a new UpdateQuery object that can be used to build complex
+     * UPDATE queries and execute them against the current database.
+     *
+     * Queries executed through the query builder are always sent to the database, regardless of the
+     * the dry-run settings.
+     *
+     * @return \Cake\Database\Query\UpdateQuery
+     */
+    public function getUpdateBuilder(): UpdateQuery;
+
+    /**
+     * Returns a new DeleteQuery object that can be used to build complex
+     * DELETE queries and execute them against the current database.
+     *
+     * Queries executed through the query builder are always sent to the database, regardless of the
+     * the dry-run settings.
+     *
+     * @return \Cake\Database\Query\DeleteQuery
+     */
+    public function getDeleteBuilder(): DeleteQuery;
+
+    /**
+     * Executes a query and returns only one row as an array.
+     *
+     * @param string $sql SQL
+     * @return array|false
+     */
+    public function fetchRow(string $sql): array|false;
+
+    /**
+     * Executes a query and returns an array of rows.
+     *
+     * @param string $sql SQL
+     * @return array
+     */
+    public function fetchAll(string $sql): array;
+
+    /**
+     * Create a new database.
+     *
+     * @param string $name Database Name
+     * @param array<string, mixed> $options Options
+     * @return void
+     */
+    public function createDatabase(string $name, array $options): void;
+
+    /**
+     * Drop a database.
+     *
+     * @param string $name Database Name
+     * @return void
+     */
+    public function dropDatabase(string $name): void;
+
+    /**
+     * Creates schema.
+     *
+     * This will thrown an error for adapters that do not support schemas.
+     *
+     * @param string $name Schema name
+     * @return void
+     * @throws \BadMethodCallException
+     */
+    public function createSchema(string $name): void;
+
+    /**
+     * Drops schema.
+     *
+     * This will thrown an error for adapters that do not support schemas.
+     *
+     * @param string $name Schema name
+     * @return void
+     * @throws \BadMethodCallException
+     */
+    public function dropSchema(string $name): void;
+
+    /**
+     * Checks to see if a table exists.
+     *
+     * @param string $tableName Table name
+     * @return bool
+     */
+    public function hasTable(string $tableName): bool;
+
+    /**
+     * Returns an instance of the <code>\Table</code> class.
+     *
+     * You can use this class to create and manipulate tables.
+     *
+     * @param string $tableName Table name
+     * @param array<string, mixed> $options Options
+     * @return \Migrations\Db\Table
+     */
+    public function table(string $tableName, array $options): Table;
+
+    /**
+     * Perform checks on the migration, printing a warning
+     * if there are potential problems.
+     *
+     * @return void
+     */
+    public function preFlightCheck(): void;
+
+    /**
+     * Perform checks on the migration after completion
+     *
+     * Right now, the only check is whether all changes were committed
+     *
+     * @return void
+     */
+    public function postFlightCheck(): void;
+
+    /**
+     * Checks to see if the migration should be executed.
+     *
+     * Returns true by default.
+     *
+     * You can use this to prevent a migration from executing.
+     *
+     * @return bool
+     */
+    public function shouldExecute(): bool;
+}
diff --git a/src/SeedInterface.php b/src/SeedInterface.php
new file mode 100644
index 00000000..f4bb8d1c
--- /dev/null
+++ b/src/SeedInterface.php
@@ -0,0 +1,190 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * MIT License
+ * For full license information, please view the LICENSE file that was distributed with this source code.
+ */
+
+namespace Migrations;
+
+use Migrations\Db\Adapter\AdapterInterface;
+use Migrations\Db\Table;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * Seed interface
+ *
+ * Implements the same API as Phinx's SeedInterface does but with migrations classes.
+ */
+interface SeedInterface
+{
+    /**
+     * @var string
+     */
+    public const RUN = 'run';
+
+    /**
+     * @var string
+     */
+    public const INIT = 'init';
+
+    /**
+     * Run the seeder.
+     *
+     * @return void
+     */
+    public function run(): void;
+
+    /**
+     * Return seeds dependencies.
+     *
+     * @return array
+     */
+    public function getDependencies(): array;
+
+    /**
+     * Sets the environment.
+     *
+     * @return $this
+     */
+    public function setEnvironment(string $environment);
+
+    /**
+     * Gets the environment.
+     *
+     * @return string
+     */
+    public function getEnvironment(): string;
+
+    /**
+     * Sets the database adapter.
+     *
+     * @param \Migrations\Db\Adapter\AdapterInterface $adapter Database Adapter
+     * @return $this
+     */
+    public function setAdapter(AdapterInterface $adapter);
+
+    /**
+     * Gets the database adapter.
+     *
+     * @return \Migrations\Db\Adapter\AdapterInterface
+     */
+    public function getAdapter(): AdapterInterface;
+
+    /**
+     * Sets the input object to be used in migration object
+     *
+     * @param \Symfony\Component\Console\Input\InputInterface $input Input
+     * @return $this
+     */
+    public function setInput(InputInterface $input);
+
+    /**
+     * Gets the input object to be used in migration object
+     *
+     * @return \Symfony\Component\Console\Input\InputInterface
+     */
+    public function getInput(): InputInterface;
+
+    /**
+     * Sets the output object to be used in migration object
+     *
+     * @param \Symfony\Component\Console\Output\OutputInterface $output Output
+     * @return $this
+     */
+    public function setOutput(OutputInterface $output);
+
+    /**
+     * Gets the output object to be used in migration object
+     *
+     * @return \Symfony\Component\Console\Output\OutputInterface
+     */
+    public function getOutput(): OutputInterface;
+
+    /**
+     * Gets the name.
+     *
+     * @return string
+     */
+    public function getName(): string;
+
+    /**
+     * Executes a SQL statement and returns the number of affected rows.
+     *
+     * @param string $sql SQL
+     * @param array $params parameters to use for prepared query
+     * @return int
+     */
+    public function execute(string $sql, array $params = []): int;
+
+    /**
+     * Executes a SQL statement.
+     *
+     * The return type depends on the underlying adapter being used. To improve
+     * IDE auto-completion possibility, you can overwrite the query method
+     * phpDoc in your (typically custom abstract parent) seed class, where
+     * you can set the return type by the adapter in your current use.
+     *
+     * @param string $sql SQL
+     * @param array $params parameters to use for prepared query
+     * @return mixed
+     */
+    public function query(string $sql, array $params = []): mixed;
+
+    /**
+     * Executes a query and returns only one row as an array.
+     *
+     * @param string $sql SQL
+     * @return array|false
+     */
+    public function fetchRow(string $sql): array|false;
+
+    /**
+     * Executes a query and returns an array of rows.
+     *
+     * @param string $sql SQL
+     * @return array
+     */
+    public function fetchAll(string $sql): array;
+
+    /**
+     * Insert data into a table.
+     *
+     * @param string $tableName Table name
+     * @param array $data Data
+     * @return void
+     */
+    public function insert(string $tableName, array $data): void;
+
+    /**
+     * Checks to see if a table exists.
+     *
+     * @param string $tableName Table name
+     * @return bool
+     */
+    public function hasTable(string $tableName): bool;
+
+    /**
+     * Returns an instance of the <code>\Table</code> class.
+     *
+     * You can use this class to create and manipulate tables.
+     *
+     * @param string $tableName Table name
+     * @param array<string, mixed> $options Options
+     * @return \Migrations\Db\Table
+     */
+    public function table(string $tableName, array $options): Table;
+
+    /**
+     * Checks to see if the seed should be executed.
+     *
+     * Returns true by default.
+     *
+     * You can use this to prevent a seed from executing.
+     *
+     * @return bool
+     */
+    public function shouldExecute(): bool;
+}

From fe677f45082118690b698ae574a22cad2d067ab2 Mon Sep 17 00:00:00 2001
From: Mark Story <mark@mark-story.com>
Date: Wed, 18 Sep 2024 10:08:13 -0400
Subject: [PATCH 2/2] Fix file name

---
 src/{MigrationsInterface.php => MigrationInterface.php} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename src/{MigrationsInterface.php => MigrationInterface.php} (100%)

diff --git a/src/MigrationsInterface.php b/src/MigrationInterface.php
similarity index 100%
rename from src/MigrationsInterface.php
rename to src/MigrationInterface.php