ColumnSchemaBuilder

API reference › yii › db › ColumnSchemaBuilder

class	`yii\db\ColumnSchemaBuilder`
Extends	`yii\base\BaseObject`
Implements	`Stringable`, `yii\base\Configurable`
Since	2.0.6
Source	`framework/db/ColumnSchemaBuilder.php`

4 subclasses

ColumnSchemaBuilder helps to define database schema types using a PHP interface.

See SchemaBuilderTrait for more detailed description and usage examples.

Properties

Property	Type	Description	Defined by
`$categoryMap`	`array`	Mapping of abstract column types (keys) to type categories (values).	`ColumnSchemaBuilder`
`$comment`	`string`	Comment value of the column. Default: `null`. Available since 2.0.8.	`ColumnSchemaBuilder`
`$db`	`Connection`	The current database connection. Default: `null`. Available since 2.0.8.	`ColumnSchemaBuilder`
`$typeCategoryMap` static	`array`	Mapping of abstract column types (keys) to type categories (values). Default: [\yii\db\Schema::TYPE_PK => self::CATEGORY_PK, \yii\db\Schema::TYPE_UPK => self::CATEGORY_PK, \yii\db\Schema::TYPE_BIGPK => self::CATEGORY_PK, \yii\db\Schema::TYPE_UBIGPK => self::CATEGORY_PK, \yii\db\Schema::TYPE_CHAR => self::CATEGORY_STRING, \yii\db\Schema::TYPE_STRING => self::CATEGORY_STRING, \yii\db\Schema::TYPE_TEXT => self::CATEGORY_STRING, \yii\db\Schema::TYPE_TINYINT => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_SMALLINT => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_INTEGER => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_BIGINT => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_FLOAT => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_DOUBLE => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_DECIMAL => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_DATETIME => self::CATEGORY_TIME, \yii\db\Schema::TYPE_TIMESTAMP => self::CATEGORY_TIME, \yii\db\Schema::TYPE_TIME => self::CATEGORY_TIME, \yii\db\Schema::TYPE_DATE => self::CATEGORY_TIME, \yii\db\Schema::TYPE_BINARY => self::CATEGORY_OTHER, \yii\db\Schema::TYPE_BOOLEAN => self::CATEGORY_NUMERIC, \yii\db\Schema::TYPE_MONEY => self::CATEGORY_NUMERIC]. Available since 2.0.43.	`ColumnSchemaBuilder`
`$typeDefinition` read-only	`string`	Abstract type plus optional length, for example `string(255)`. Available since 22.0.	`ColumnSchemaBuilder`
`$after` protected	`string`	The column after which this column will be added. Default: `null`. Available since 2.0.8.	`ColumnSchemaBuilder`
`$append` protected	`mixed`	SQL string to be appended to column schema definition. Default: `null`. Available since 2.0.9.	`ColumnSchemaBuilder`
`$check` protected	`string`	The `CHECK` constraint for the column. Default: `null`.	`ColumnSchemaBuilder`
`$default` protected	`mixed`	Default value of the column. Default: `null`.	`ColumnSchemaBuilder`
`$isFirst` protected	`bool`	Whether this column is to be inserted at the beginning of the table. Default: `null`. Available since 2.0.8.	`ColumnSchemaBuilder`
`$isNotNull` protected	`bool\|null`	Whether the column is or not nullable. Default: `null`.	`ColumnSchemaBuilder`
`$isUnique` protected	`bool`	Whether the column values should be unique. Default: `false`.	`ColumnSchemaBuilder`
`$isUnsigned` protected	`bool`	Whether the column values should be unsigned. Default: `false`. Available since 2.0.7.	`ColumnSchemaBuilder`
`$length` protected	`int\|string\|array`	Column size or precision definition. Default: `null`.	`ColumnSchemaBuilder`
`$type` protected	`string`	The column type definition such as INTEGER, VARCHAR, DATETIME, etc. Default: `null`.	`ColumnSchemaBuilder`

Methods

Method	Description	Defined by
`__construct()`	Create a column schema builder instance giving the type and value precision.	`ColumnSchemaBuilder`
`__call()`	Calls the named method which is not a class method.	`yii\base\BaseObject`
`__get()`	Returns the value of an object property.	`yii\base\BaseObject`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`yii\base\BaseObject`
`__set()`	Sets value of an object property.	`yii\base\BaseObject`
`__toString()`	Builds the full string for the column’s schema.	`ColumnSchemaBuilder`
`__unset()`	Sets an object property to null.	`yii\base\BaseObject`
`after()`	Adds an `AFTER` constraint to the column.	`ColumnSchemaBuilder`
`append()`	Specify additional SQL to be appended to column definition.	`ColumnSchemaBuilder`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`yii\base\BaseObject`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`yii\base\BaseObject`
`check()`	Sets a `CHECK` constraint for the column.	`ColumnSchemaBuilder`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`comment()`	Specifies the comment for column.	`ColumnSchemaBuilder`
`defaultExpression()`	Specify the default SQL expression for the column.	`ColumnSchemaBuilder`
`defaultValue()`	Specify the default value for the column.	`ColumnSchemaBuilder`
`first()`	Adds an `FIRST` constraint to the column.	`ColumnSchemaBuilder`
`getAppend()`	Returns the raw SQL fragment appended to the column definition.	`ColumnSchemaBuilder`
`getCategoryMap()`		`ColumnSchemaBuilder`
`getCheck()`	Returns the raw `CHECK` constraint expression of the column.	`ColumnSchemaBuilder`
`getDefault()`	Returns the raw default value of the column.	`ColumnSchemaBuilder`
`getTypeDefinition()`	Returns the abstract type together with its length or precision, without any constraint keywords.	`ColumnSchemaBuilder`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\BaseObject`
`hasProperty()`	Returns a value indicating whether a property is defined.	`yii\base\BaseObject`
`init()`	Initializes the object.	`yii\base\BaseObject`
`isNotNull()`	Returns the nullability state of the column as a tri-state value.	`ColumnSchemaBuilder`
`isUnique()`	Returns whether the column carries a `UNIQUE` constraint.	`ColumnSchemaBuilder`
`notNull()`	Adds a `NOT NULL` constraint to the column.	`ColumnSchemaBuilder`
`null()`	Adds a `NULL` constraint to the column.	`ColumnSchemaBuilder`
`setCategoryMap()`		`ColumnSchemaBuilder`
`unique()`	Adds a `UNIQUE` constraint to the column.	`ColumnSchemaBuilder`
`unsigned()`	Marks column as unsigned.	`ColumnSchemaBuilder`
`buildAfterString()` protected	Builds the after constraint for the column. Defaults to unsupported.	`ColumnSchemaBuilder`
`buildAppendString()` protected	Builds the custom string that’s appended to column definition.	`ColumnSchemaBuilder`
`buildCheckString()` protected	Builds the check constraint for the column.	`ColumnSchemaBuilder`
`buildCommentString()` protected	Builds the comment specification for the column.	`ColumnSchemaBuilder`
`buildCompleteString()` protected	Returns the complete column definition from input format.	`ColumnSchemaBuilder`
`buildDefaultString()` protected	Builds the default value specification for the column.	`ColumnSchemaBuilder`
`buildDefaultValue()` protected	Return the default value for the column.	`ColumnSchemaBuilder`
`buildFirstString()` protected	Builds the first constraint for the column. Defaults to unsupported.	`ColumnSchemaBuilder`
`buildLengthString()` protected	Builds the length/precision part of the column.	`ColumnSchemaBuilder`
`buildNotNullString()` protected	Builds the not null constraint for the column.	`ColumnSchemaBuilder`
`buildUniqueString()` protected	Builds the unique constraint for the column.	`ColumnSchemaBuilder`
`buildUnsignedString()` protected	Builds the unsigned string for column. Defaults to unsupported.	`ColumnSchemaBuilder`
`getTypeCategory()` protected	Returns the category of the column type.	`ColumnSchemaBuilder`

Constants

Constant	Value	Defined by
`CATEGORY_PK`	`'pk'`	`ColumnSchemaBuilder`
`CATEGORY_STRING`	`'string'`	`ColumnSchemaBuilder`
`CATEGORY_NUMERIC`	`'numeric'`	`ColumnSchemaBuilder`
`CATEGORY_TIME`	`'time'`	`ColumnSchemaBuilder`
`CATEGORY_OTHER`	`'other'`	`ColumnSchemaBuilder`

Property details

$db

public yii\db\Connection $db = null

The current database connection.

It is used mainly to escape strings safely when building the final column schema string.

Since

2.0.8

$isNotNull

protected bool|null $isNotNull = null

Whether the column is or not nullable.

If this is true, a NOT NULL constraint will be added. If this is false, a NULL constraint will be added.

$isUnique

protected bool $isUnique = false

Whether the column values should be unique.

If this is true, a UNIQUE constraint will be added.

$isUnsigned

protected bool $isUnsigned = false

Whether the column values should be unsigned.

If this is true, an UNSIGNED keyword will be added.

Since

2.0.7

$length

protected int|string|array $length = null

Column size or precision definition.

This is what goes into the parenthesis after the column type. This can be either a string, an integer or an array. If it is an array, the array values will be joined into a string separated by comma.

Method details

__construct()

public function __construct(string $type, int|string|array|null $length = null, yii\db\Connection|null $db = null, array $config = [])

Create a column schema builder instance giving the type and value precision.

Parameters

Parameter	Type	Description
`$type`	`string`	Type of the column. See `$type`.
`$length`	`int\|string\|array\|null`	Length or precision of the column. See `$length`.
`$db`	`Connection\|null`	The current database connection. See `$db`.
`$config`	`array`	Name-value pairs that will be used to initialize the object properties

__toString()

public function __toString(): string

Builds the full string for the column’s schema.

Returns

string

after()

public function after(string $after): $this

Adds an AFTER constraint to the column.

Note: MySQL and Oracle support only.

Parameters

Parameter	Type	Description
`$after`	`string`	The column after which $this column will be added.

Returns

$this

Since

2.0.8

append()

public function append(string $sql): $this

Specify additional SQL to be appended to column definition.

Position modifiers will be appended after column definition in databases that support them.

Parameters

Parameter	Type	Description
`$sql`	`string`	The SQL string to be appended.

Returns

$this

Since

2.0.9

check()

public function check(string $check): $this

Sets a CHECK constraint for the column.

Parameters

Parameter	Type	Description
`$check`	`string`	The SQL of the `CHECK` constraint to be added.

Returns

$this

comment()

public function comment(string $comment): $this

Specifies the comment for column.

Parameters

Parameter	Type	Description
`$comment`	`string`	The comment

Returns

$this

Since

2.0.8

defaultExpression()

public function defaultExpression(string $default): $this

Specify the default SQL expression for the column.

Parameters

Parameter	Type	Description
`$default`	`string`	The default value expression.

Returns

$this

Since

2.0.7

defaultValue()

public function defaultValue(mixed $default): $this

Specify the default value for the column.

Parameters

Parameter	Type	Description
`$default`	`mixed`	The default value.

Returns

$this

first()

public function first(): $this

Adds an FIRST constraint to the column.

Note: MySQL and Oracle support only.

Returns

$this

Since

2.0.8

getAppend()

public function getAppend(): string|null

Returns the raw SQL fragment appended to the column definition.

Returns

string|null: Appended SQL fragment, or null when none is set.

Since

22.0

getCategoryMap()

public function getCategoryMap(): array

Returns

array: Mapping of abstract column types (keys) to type categories (values).

Since

2.0.43

getCheck()

public function getCheck(): string|null

Returns the raw CHECK constraint expression of the column.

Returns

string|null: CHECK expression, or null when no constraint is set.

Since

22.0

getDefault()

public function getDefault(): mixed

Returns the raw default value of the column.

Returns

mixed: Scalar value, an Expression when defaultExpression() was used, or null when unset.

Since

22.0

getTypeDefinition()

public function getTypeDefinition(): string

Returns the abstract type together with its length or precision, without any constraint keywords.

The result is intended for QueryBuilder::getColumnType() to resolve the physical column type.

Returns

string: Abstract type plus optional length, for example string(255).

Since

22.0

isNotNull()

public function isNotNull(): bool|null

Returns the nullability state of the column as a tri-state value.

Returns

bool|null: true for NOT NULL, false for NULL, or null when the nullability is unspecified.

Since

22.0

isUnique()

public function isUnique(): bool

Returns whether the column carries a UNIQUE constraint.

Returns

bool: true when a UNIQUE constraint is set; false otherwise.

Since

22.0

notNull()

public function notNull(): $this

Adds a NOT NULL constraint to the column.

Returns

$this

null()

public function null(): $this

Adds a NULL constraint to the column.

Returns

$this

Since

2.0.9

setCategoryMap()

public function setCategoryMap(array $categoryMap): mixed

Parameters

Parameter	Type	Description
`$categoryMap`	`array`	Mapping of abstract column types (keys) to type categories (values).

Returns

mixed

Since

2.0.43

unique()

public function unique(): $this

Adds a UNIQUE constraint to the column.

Returns

$this

unsigned()

public function unsigned(): $this

Marks column as unsigned.

Returns

$this

Since

2.0.7

buildAfterString()

protected function buildAfterString(): string

Builds the after constraint for the column. Defaults to unsupported.

Returns

string: A string containing the AFTER constraint.

Since

2.0.8

buildAppendString()

protected function buildAppendString(): string

Builds the custom string that’s appended to column definition.

Returns

string: Custom string to append.

Since

2.0.9

buildCheckString()

protected function buildCheckString(): string

Builds the check constraint for the column.

Returns

string: A string containing the CHECK constraint.

buildCommentString()

protected function buildCommentString(): string

Builds the comment specification for the column.

Returns

string: A string containing the COMMENT keyword and the comment itself

Since

2.0.8

buildCompleteString()

protected function buildCompleteString(string $format): string

Returns the complete column definition from input format.

Parameters

Parameter	Type	Description
`$format`	`string`	The format of the definition.

Returns

string: A string containing the complete column definition.

Since

2.0.8

buildDefaultString()

protected function buildDefaultString(): string

Builds the default value specification for the column.

Returns

string: String with default value of column.

buildDefaultValue()

protected function buildDefaultValue(): string|null

Return the default value for the column.

Returns

string|null: String with default value of column.

buildFirstString()

protected function buildFirstString(): string

Builds the first constraint for the column. Defaults to unsupported.

Returns

string: A string containing the FIRST constraint.

Since

2.0.8

buildLengthString()

protected function buildLengthString(): string

Builds the length/precision part of the column.

Returns

string

buildNotNullString()

protected function buildNotNullString(): string

Builds the not null constraint for the column.

Returns

string: Returns ‘NOT NULL’ if isNotNull() is true, ‘NULL’ if isNotNull() is false or an empty string otherwise.

buildUniqueString()

protected function buildUniqueString(): string

Builds the unique constraint for the column.

Returns

string: Returns string ‘UNIQUE’ if isUnique() is true, otherwise it returns an empty string.

buildUnsignedString()

protected function buildUnsignedString(): string

Builds the unsigned string for column. Defaults to unsupported.

Returns

string: A string containing UNSIGNED keyword.

Since

2.0.7

getTypeCategory()

protected function getTypeCategory(): string

Returns the category of the column type.

Returns

string: A string containing the column type category name.

Since

2.0.8