README

用于创建和修改 SQL 数据库表的扩展。

本插件为 PHP Fat-Free Framework 提供了一个 SQL 表架构构建器。它可能对安装脚本、动态应用程序或 CMS 环境有用。

目前支持并已完全测试的驱动程序包括 MySQL、SQLite、PostgreSQL 和 SQL Server。Sybase、Oracle 和 DB2 驱动程序的支持已经包含在内，但处于实验阶段。请谨慎使用并测试您的应用程序。没有任何保证。

此插件是为 F3 版本 3.x 制作的，需要 PHP 5.4+

安装

只需将 schema.php 复制到 F3 的 lib/db/sql 文件夹中。完成。

如果您使用 composer，可以通过运行 composer require ikkez/f3-schema-builder:dev-master 来添加此包

快速入门

要使用 Schema 构建器，您需要一个有效的 SQL 连接。创建一个如下所示的连接

$db = new \DB\SQL('mysql:host=localhost;port=3306;dbname='.$DBname, $user, $pass);

现在创建一个 Schema 对象来工作。将其 DB 对象注入到其构造函数中

$schema = new \DB\SQL\Schema( $db );

创建表

创建新表非常简单。让我们看看这个例子

$table = $schema->createTable('products');
$table->addColumn('title')->type($schema::DT_VARCHAR128);
$table->addColumn('description')->type($schema::DT_TEXT);
$table->build();

createTable() 方法返回一个新的表对象（TableCreator 实例），用于创建目的。您可以使用它添加新的列、索引并更改主键。新表将始终包含一个自动递增的主键字段，名称为 id，这对于进一步使用 SQL\Mapper 是必需的。所有影响表对象架构的操作都将首先收集起来，并需要额外的 build() 命令才能在数据库中生效。如果您不确定结果，可以使用 build 方法的模拟并查看 Schema Builder 将执行的生成查询，如下所示调用

$generated_queries = $table->build(false);
print_r($generated_queries);

添加列

使用 $table->addColumn() 方法将创建一个新的 Column 对象并将其添加到表对象中。我们可以使用流畅的调用来配置这些列。

$column = $table->addColumn('deleted');
$column->type($schema::DT_BOOL);
$column->nullable(false);
$column->defaults(0);
$column->after('id');

// or in a fluent way:
$table->addColumn('deleted')->type($schema::DT_BOOL)->nullable(false)->defaults(0)->after('id');

以下是一些可能的配置方法

$column->type( $datatype [ bool $force = FALSE])

设置此列的数据类型。通常是一个类型为 \DB\SQL\Schema::DT_{datatype} 的常量。有关数据类型的更多详细信息，请参阅 Column Class API。当 $force 为 TRUE 时，将 $datatype 字符串作为原始值使用，并直接传递给创建查询（对于自定义数据类型很有用）。

$column->nullable( $state )

将此列设置为 NULL 或 NOT NULL。默认为 true / 可为空。

$column->defaults( $value )

为记录添加默认值。

$column->after( $name )

尝试将新列放置在现有列之后。

$column->index([ bool $unique = false ])

为该字段添加索引。 $unique 使其成为一个 UNIQUE INDEX。

修改表

修改现有表与创建它们非常相似，但提供了一系列更多的可能性。以下是一个基本示例

$table = $schema->alterTable('products');
$table->addColumn('prize')->type($schema::DT_DECIMAL);
$table->addColumn('stock')->type($schema::DT_INT);
$table->dropColumn('foo_bar');
$table->renameColumn('title','name');
$table->build();

如你所见，$schema->alterTable() 返回一个新的表对象（TableModifier 实例），用于修改目的，它提供了 TableCreator 的所有方法以及一些额外的操作，如删除或重命名列。以下是一些您可以使用的方法

renameColumn( string $name, string $new_name );
updateColumn( string $name, string $datatype );
dropColumn( string $name );
addIndex( string | array $columns, [ bool $unique = false ]);
dropIndex( string | array $columns );
listIndex();
getCols([ bool $types = false ]);

SchemaBuilder 会引用所有的表和列标识符，并且应该能够抵抗保留字错误。

API 使用

Schema 类

Schema 类提供了以下简单方法来

管理数据库

$schema->getDatabases();

返回所有可用数据库的数组（除 SQLite 外）。在安装过程中，当您希望用户选择要工作的数据库时很有用。因此，只需创建数据库连接而不选择数据库，如下所示

$db = new \DB\SQL('mysql:host=localhost;port=3306;dbname=', $user, $password);

某些数据库引擎的默认设置也允许简单的读取操作，而无需设置用户/密码。

管理表

$schema->getTables();

返回当前数据库中所有可用表的数组。

$schema->createTable( string $tableName );

返回用于创建目的的新表对象。

$schema->alterTable( string $tableName );

返回用于对已存在的表进行修改操作的对象。

$schema->renameTable( string $name, string $new_name, [ bool $exec = true ]);

重命名一个表。如果您将 $exec 设置为 FALSE，则将返回生成的查询而不是执行它。您也可以在修改表对象时使用快捷方式，如 $table->rename( string $new_name, [ bool $exec = true ]);。

$schema->truncateTable( string $name, [ bool $exec = true ]);

清除表的内容。将 $exec 设置为 FALSE 将返回生成的查询而不是执行它。

$schema->dropTable( string $name, [ bool $exec = true ]);

删除一个表。将 $exec 设置为 FALSE 将返回生成的查询而不是执行它。您也可以在修改表对象时使用快捷方式，如 $table->drop([ bool $exec = true ]);。

$schema->isCompatible( string $colType, string $colDef );

这对于反向查找很有用。它检查数据类型是否与给定的列定义兼容，即 $schema->isCompatible('BOOLEAN','tinyint(1)');。

TableCreator 类

此类旨在创建新表。可以通过使用 $schema->createTable($name) 来创建它。

$table->addColumn($key,$args = null); 列

这会创建一个新的列对象并保存对其的引用。您可以使用后续的流畅调用来配置列，设置其公共参数或直接通过配置数组，如下所示

$table->addColumn('title',array(
	'type'=>\DB\SQL\Schema::DT_INT4,
	'nullable'=>false,
	'default'=>'untitled new entry',
	'after'=>'id',
	'index'=>true,
	'unique'=>true,
));

$table->addIndex($columns, $unique = FALSE);

您可以在添加新列时配置列对象以添加索引，或如下所示

$table->addIndex('name');

要添加多个列的组合索引，只需使用数组作为参数

$table->addIndex(array('name','email'));

$table->primary($pkeys);

如果您想在创建新表时立即更改默认的 id 命名主键，可以使用此方法

$table->primary('uid');

这将把 id 字段重命名为 uid。如果您想在多个列上设置主键（组合键），请使用数组

$table->primary(array('uid','version'));

此主键数组中的第一个元素始终被视为自动增长的字段。

示例

$table = $schema->createTable('news');
$table->addColumn('title')->type($schema::DT_VARCHAR128);
$table->addColumn('bodytext')->type($schema::DT_TEXT);
$table->addColumn('version')->type($schema::DT_INT8)->nullable(false)->defaults(1);
$table->primary(array('id', 'version'));
$table->build();

现在主键是基于两个列构建的，可以使用如下记录：id=1, version=1 和 id=1, version=2。

$table->setCharset( string $str [, $collation = 'unicode' ]);

此方法将为新表设置自定义字符集和默认校对。

例如，这将设置 utf8mb4 字符集和 utf8mb4_unicode_ci 校对作为默认值。

$table = $schema->createTable('comments');
$table->setCharset('utf8mb4');
// ...

注意：目前仅影响 MySQL。Postgre、SQLite 中1-4个多字节UTF8字符默认支持。SQL Server尚无解决方案。

$table->build([ bool $exec = true ]);

这将启动表生成过程，如果 $exec 为 TRUE，则执行所有查询，否则仅返回查询数组。

TableModifier 类

这个类用于创建新的表。可以通过使用 $schema->alterTable($name) 来创建。

$table->addColumn($key,$args = null); 列

添加一个新列

`$table->renameColumn( string $name, string $new_name );`

用于重命名现有列。

`$table->updateColumn( string $name, string datatype, [ bool $force = false ]);`

用于修改/更新列的数据类型。

`$table->dropColumn( string $name );`

尝试从表中删除列，如果存在的话。

`$table->addIndex( string | array $columns, [ bool $unique = false ]);`

为表中的一列或多列创建索引或唯一索引。

`$table->dropIndex( string | array $columns );`

删除索引。

`$table->listIndex();`

返回一个关联数组，索引名称作为键，array('unique'=>$value) 作为值。

`$table->primary( string | array $pkeys);`

在表上创建一个新的主键或组合键。

`$table->getCols([ bool $types = false ]);`

返回现有表列的数组。如果 $types 设置为 TRUE，则返回一个关联数组，列名作为键，模式数组作为值。

$table->build([ bool $exec = true ]);

这生成了表格变更所需的查询并在 $exec 为真时执行它们，否则以数组形式返回。

`$table->rename( string $new_name, [ bool $exec = true ]);`

这将立即重命名表。注意：执行不是在调用 build() 时执行，而是由 $exec 控制。

`$table->drop([ bool $exec = true ]);`

这将立即删除表。注意：执行不是在调用 build() 时执行，而是由 $exec 控制。

`$table->isCompatible( string $colType, string $column );`

这对于反向查找很有用。它检查数据类型是否与现有列类型兼容，即 $table->isCompatible('BOOLEAN','hidden');。

$table->setCharset( string $str [, $collation = 'unicode' ]);

此方法将设置自定义字符集和校对，并在 build() 时转换现有表。

在这个例子中，我们将一个表转换为 utf8mb4 字符集和 utf8mb4_general_ci 校对。

$table = $schema->alterTable('comments');
$table->setCharset('utf8mb4','general');
// ...

列类

方法 $table->addColumn($columnName); 向所选表添加一个额外的列字段并创建并返回一个新的 Column 对象，该对象可以以不同的方式配置，然后在最终构建之前。

type( string $datatype, [ bool $force = false ])

设置此列的数据类型。$force 参数将禁用数据类型检查与包含的映射，并使用您的原始字符串作为类型定义。

您可以在 \DB\SQL\Schema 中使用这些可用的映射类型作为常量。

用法

$table = $schema->alterTable('news');
$table->addColumn('author')->type(\DB\SQL\Schema::DT_VARCHAR128);
// or
$table->addColumn('bodytext')->type($schema::DT_TEXT);
// or the shorthand
$table->addColumn('bodytext')->type_text();

// save changes to database
$table->build();

还有许多简写方法可用，您可以用它们来代替 type()

type_tinyint()
type_smallint()
type_int()
type_bigint()
type_float()
type_decimal()
type_text()
type_longtext()
type_varchar([ $length = 255 ])
type_date()
type_datetime()
type_timestamp([ $asDefault = FALSE ])
type_blob()
type_bool()

passThrough([ bool $state = TRUE ])

当启用 pass-through 时，数据类型值被视为原始值，这使得可以设置任何其他未由包含的别名覆盖的自定义数据类型。这相当于 type() 与 $force = TRUE。

nullable( bool $state )

将此列设置为 NULL 或 NOT NULL。默认为 TRUE / 可空。您还可以将默认值设置为可空字段。

defaults( mixed $value )

为记录添加默认值。通常是一个 字符串 或整数值或 NULL。

CURRENT_TIMESTAMP 作为动态默认值

但是，如果您想将当前时间的戳添加到新插入的记录中，您可以使用具有特殊默认值的 TIMESTAMP 字段来实现这一点。

$table->addColumn('creation_date')->type($schema::DT_TIMESTAMP)->defaults($schema::DF_CURRENT_TIMESTAMP);

// a shorthand would be:
$table->addColumn('creation_date')->type_timestamp(TRUE);

after( string $name )

尝试将新列放在现有列的后面。(仅适用于 SQLite 和 MySQL)

index([ bool $unique = false ])

为该字段添加索引。 $unique 使其成为一个 UNIQUE INDEX。

copyfrom( 字符串 | 数组 $args )

从数组或hive键中获取数据列。

getColumnArray()

返回当前列配置的数组。

getTypeVal()

返回解析后的列数据类型。

许可证

GPLv3

喜欢这个插件吗？

ikkez / f3-schema-builder

维护者

详细信息

README

用于创建和修改 SQL 数据库表的扩展。

安装

快速入门

创建表

添加列

$column->type( $datatype [ bool $force = FALSE])

$column->nullable( $state )

$column->defaults( $value )

$column->after( $name )

$column->index([ bool $unique = false ])

修改表

API 使用

Schema 类

管理数据库

$schema->getDatabases();

管理表

$schema->getTables();

$schema->createTable( string $tableName );

$schema->alterTable( string $tableName );

$schema->renameTable( string $name, string $new_name, [ bool $exec = true ]);

$schema->truncateTable( string $name, [ bool $exec = true ]);

$schema->dropTable( string $name, [ bool $exec = true ]);

$schema->isCompatible( string $colType, string $colDef );

TableCreator 类

$table->addColumn($key,$args = null); 列

$table->addIndex($columns, $unique = FALSE);

$table->primary($pkeys);

$table->setCharset( string $str [, $collation = 'unicode' ]);

$table->build([ bool $exec = true ]);

TableModifier 类

$table->addColumn($key,$args = null); 列

$table->renameColumn( string $name, string $new_name );

$table->updateColumn( string $name, string datatype, [ bool $force = false ]);

$table->dropColumn( string $name );

$table->addIndex( string | array $columns, [ bool $unique = false ]);

$table->dropIndex( string | array $columns );

$table->listIndex();

$table->primary( string | array $pkeys);

$table->getCols([ bool $types = false ]);

$table->build([ bool $exec = true ]);

$table->rename( string $new_name, [ bool $exec = true ]);

$table->drop([ bool $exec = true ]);

$table->isCompatible( string $colType, string $column );

$table->setCharset( string $str [, $collation = 'unicode' ]);

列类

type( string $datatype, [ bool $force = false ])

passThrough([ bool $state = TRUE ])

nullable( bool $state )

defaults( mixed $value )

after( string $name )

index([ bool $unique = false ])

copyfrom( 字符串 | 数组 $args )

getColumnArray()

getTypeVal()

许可证

`$table->renameColumn( string $name, string $new_name );`

`$table->updateColumn( string $name, string datatype, [ bool $force = false ]);`

`$table->dropColumn( string $name );`

`$table->addIndex( string | array $columns, [ bool $unique = false ]);`

`$table->dropIndex( string | array $columns );`

`$table->listIndex();`

`$table->primary( string | array $pkeys);`

`$table->getCols([ bool $types = false ]);`

`$table->rename( string $new_name, [ bool $exec = true ]);`

`$table->drop([ bool $exec = true ]);`

`$table->isCompatible( string $colType, string $column );`