Creates SMF\Db\Schema and descendents

Signed-off-by: Jon Stovell <[email protected]>

.gitignore

@@ -5,6 +5,7 @@
 !/Languages/en_US/
 /Languages/en_US/agreement.txt
 Settings.php
+!Sources/Db/Schema/*/Settings.php
 Settings_bak.php
 Settings_org.php
 db_last_error.php

Sources/Db/Schema/Column.php

@@ -0,0 +1,202 @@
+<?php
+
+/**
+ * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines https://www.simplemachines.org
+ * @copyright 2023 Simple Machines and individual contributors
+ * @license https://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 3.0 Alpha 1
+ */
+
+declare(strict_types=1);
+
+namespace SMF\Db\Schema;
+
+use SMF\Db\DatabaseApi as Db;
+
+/**
+ * Represents a column in a database table.
+ */
+class Column
+{
+	/*******************
+	 * Public properties
+	 *******************/
+
+	/**
+	 * @var string
+	 *
+	 * Name of the column.
+	 */
+	public string $name;
+
+	/**
+	 * @var string
+	 *
+	 * Data type of the column.
+	 */
+	public string $type;
+
+	/**
+	 * @var ?int
+	 *
+	 * Size of the column.
+	 * Only applicable to some data types.
+	 */
+	public ?int $size;
+
+	/**
+	 * @var ?bool
+	 *
+	 * Whether the column uses unsigned numerical values.
+	 * Only applicable in MySQL.
+	 */
+	public ?bool $unsigned;
+
+	/**
+	 * @var ?bool
+	 *
+	 * Whether the column disallows null values.
+	 */
+	public ?bool $not_null;
+
+	/**
+	 * @var mixed
+	 *
+	 * Default value of the column.
+	 */
+	public mixed $default;
+
+	/**
+	 * @var ?bool
+	 *
+	 * Whether this is an automatically incrementing column.
+	 * Only applicable to integer columns.
+	 */
+	public ?bool $auto;
+
+	/**
+	 * @var ?string
+	 *
+	 * The character set for string data.
+	 * Only applicable to string types.
+	 */
+	public ?string $charset;
+
+	/**
+	 * @var ?bool
+	 *
+	 * Set this to true to drop the default during an ALTER TABLE operation.
+	 *
+	 * This is not set by __construct(). It can be set afterward.
+	 */
+	public bool $drop_default = false;
+
+	/****************
+	 * Public methods
+	 ****************/
+
+	/**
+	 * Constructor.
+	 *
+	 * @param string $name Name of the column.
+	 * @param string $type Data type of the column.
+	 * @param ?int $size Size of the column.
+	 *    Only applicable to some data types.
+	 * @param ?bool $unsigned Whether the column uses unsigned numerical values.
+	 *    Only used by MySQL.
+	 * @param ?bool $not_null Whether the column disallows null values.
+	 * @param mixed $default Default value of the column. If null, no default
+	 *    will be set. To set an explicit null default, use the string 'NULL'.
+	 * @param ?bool $auto Whether this is an automatically incrementing column.
+	 *    Only applicable to integer columns.
+	 * @param ?string $charset The character set for string data.
+	 *    Only applicable to string types. If null, will be set automatically.
+	 */
+	public function __construct(
+		string $name,
+		string $type,
+		?int $size = null,
+		?bool $unsigned = null,
+		?bool $not_null = null,
+		mixed $default = null,
+		?bool $auto = null,
+		?string $charset = null,
+	) {
+		$this->name = strtolower($name);
+		$this->type = strtolower($type);
+
+		if (isset($default)) {
+			$this->default = $default === 'NULL' ? null : $default;
+		}
+
+		foreach (['auto', 'size', 'unsigned', 'not_null'] as $var) {
+			if (isset($var)) {
+				$this->{$var} = ${$var};
+			}
+		}
+
+		if (isset($charset)) {
+			$this->charset = strtolower($charset);
+		}
+	}
+
+	/**
+	 * Adds this column to the specified table.
+	 *
+	 * @see SMF\Db\DatabaseApi::add_column
+	 *
+	 * @param string $table_name The name of the table to add the column to.
+	 * @param string $if_exists What to do if the column exists.
+	 *    If 'update', column is updated.
+	 * @return bool Whether or not the operation was successful.
+	 */
+	public function add(string $table_name, string $if_exists = 'update'): bool
+	{
+		return Db::$db->add_column(
+			$table_name,
+			get_object_vars($this),
+			[],
+			$if_exists,
+		);
+	}
+
+	/**
+	 * Updates the column in the database to match the definition given by this
+	 * object's properties.
+	 *
+	 * @see SMF\Db\DatabaseApi::change_column
+	 *
+	 * @param string $table_name Name of the table that contains this column.
+	 * @return bool Whether or not the operation was successful.
+	 */
+	public function alter(string $table_name): bool
+	{
+		return Db::$db->change_column(
+			$table_name,
+			$this->name,
+			get_object_vars($this),
+		);
+	}
+
+	/**
+	 * Drops this column from the specified table.
+	 *
+	 * @see SMF\Db\DatabaseApi::remove_column
+	 *
+	 * @param string $table_name The name of the table to drop the column from.
+	 * @return bool Whether or not the operation was successful.
+	 */
+	public function drop(string $table_name): bool
+	{
+		return Db::$db->remove_column(
+			$table_name,
+			$this->name,
+		);
+	}
+}
+
+?>

Sources/Db/Schema/Index.php

@@ -0,0 +1,134 @@
+<?php
+
+/**
+ * Simple Machines Forum (SMF)
+ *
+ * @package SMF
+ * @author Simple Machines https://www.simplemachines.org
+ * @copyright 2023 Simple Machines and individual contributors
+ * @license https://www.simplemachines.org/about/smf/license.php BSD
+ *
+ * @version 3.0 Alpha 1
+ */
+
+declare(strict_types=1);
+
+namespace SMF\Db\Schema;
+
+use SMF\Db\DatabaseApi as Db;
+
+/**
+ * Represents an index in a database table.
+ */
+class Index
+{
+	/*******************
+	 * Public properties
+	 *******************/
+
+	/**
+	 * @var array
+	 *
+	 * Columns to include in the index.
+	 *
+	 * Values should be the names of columns, optionally with an index length
+	 * appended in parentheses.
+	 *
+	 * Example: ['id_msg', 'member_groups(48)']
+	 */
+	public array $columns = [];
+
+	/**
+	 * @var bool
+	 *
+	 * Allowed values: 'primary', 'unique', or null for a normal index.
+	 */
+	public ?string $type;
+
+	/**
+	 * @var ?string
+	 *
+	 * The name of the index.
+	 */
+	public ?string $name;
+
+	/****************
+	 * Public methods
+	 ****************/
+
+	/**
+	 * Constructor.
+	 *
+	 * @param array $columns Columns to include in the index.
+	 * @param ?string $type The type of index. Either 'primary' for the PRIMARY
+	 *    KEY index, 'unique' for a UNIQUE index, or null for a normal index.
+	 * @param ?string $name The name of the index. If this is left null, a name
+	 *    will be generated automatically.
+	 */
+	public function __construct(
+		array $columns,
+		?string $type = null,
+		?string $name = null,
+	) {
+		$this->columns = array_map('strtolower', $columns);
+
+		$this->type = isset($type) ? strtolower((string) $type) : null;
+
+		if (($this->type ?? null) !== 'primary') {
+			$this->name = $name ?? 'idx_' . trim(implode('_', preg_replace(['/\s*/', '/\(\d+\)/'], ['', ''], $this->columns)));
+		}
+	}
+
+	/**
+	 * Adds this index to the specified table.
+	 *
+	 * @see SMF\Db\DatabaseApi::add_index
+	 *
+	 * @param string $table_name The name of the table to add the index to.
+	 * @param string $if_exists What to do if the index exists.
+	 *    If 'update', index is updated.
+	 * @return bool Whether or not the operation was successful.
+	 */
+	public function add(string $table_name, string $if_exists = 'update'): bool
+	{
+		return Db::$db->add_index(
+			$table_name,
+			get_object_vars($this),
+			[],
+			$if_exists,
+		);
+	}
+
+	/**
+	 * Updates the index in the database to match the definition given by this
+	 * object's properties.
+	 *
+	 * @param string $table_name Name of the table that contains this index.
+	 * @return bool Whether or not the operation was successful.
+	 */
+	public function alter(string $table_name): bool
+	{
+		// This method is really just a convenient way to replace an existing index.
+		$this->drop($table_name);
+
+		return $this->add($table_name);
+	}
+
+	/**
+	 * Drops this column from the specified table.
+	 *
+	 * @see SMF\Db\DatabaseApi::remove_column
+	 *
+	 * @param string $table_name The name of the table to drop the column from.
+	 * @return bool Whether or not the operation was successful.
+	 */
+	public function drop(string $table_name): bool
+	{
+		return Db::$db->remove_index(
+			$table_name,
+			$this->name,
+		);
+	}
+}
+
+?>