0 follower

Class Yiisoft\Db\Schema\Column\DateTimeColumn

InheritanceYiisoft\Db\Schema\Column\DateTimeColumn » Yiisoft\Db\Schema\Column\AbstractColumn
ImplementsYiisoft\Db\Schema\Column\ColumnInterface

Represents the metadata for a datetime column.

Supported abstract column types:

  • ColumnType::TIMESTAMP
  • ColumnType::DATETIME
  • ColumnType::DATETIMETZ
  • ColumnType::TIME
  • ColumnType::TIMETZ
  • ColumnType::DATE
  • ColumnType::INTEGER
  • ColumnType::BIGINT
  • ColumnType::FLOAT
  • ColumnType::DOUBLE
  • ColumnType::DECIMAL

Possible issues:

  • MySQL DBMS converts TIMESTAMP column type values from database session time zone to UTC for storage, and back from UTC to the session time zone when retrieve the values;
  • Oracle DBMS converts TIMESTAMP WITH LOCAL TIME ZONE column type values from database session time zone to the database time zone for storage, and back from the database time zone to the session time zone when retrieve the values.

Both of them do not store time zone offset and require to convert datetime values to the database session time zone before insert and back to the PHP time zone after retrieve the values. This will be done in the {@see \Yiisoft\Db\Schema\Column\dbTypecast()} and {@see \Yiisoft\Db\Schema\Column\phpTypecast()} methods and guarantees that the values are stored in the database in the correct time zone.

To avoid possible time zone issues with the datetime values conversion, it is recommended to set the PHP and database time zones to UTC.

Protected Properties

Hide inherited properties

Property Type Description Defined By
$dbTimezone string The database time zone to be used when converting datetime values before inserting them into the database and when converting them back to PHP DateTimeImmutable objects. It is used when the column type does not have time zone information. Use empty string to disable time zone conversion. Yiisoft\Db\Schema\Column\DateTimeColumn
$format string|null Yiisoft\Db\Schema\Column\DateTimeColumn
$phpTimezone string The PHP time zone for the string datetime values when converting them to DateTimeImmutable objects before inserting them into the database or after retrieving them from the database. Use empty string to use current PHP time zone. Yiisoft\Db\Schema\Column\DateTimeColumn
$shouldConvertTimezone boolean|null Yiisoft\Db\Schema\Column\DateTimeColumn

Public Methods

Hide inherited methods

Method Description Defined By
__construct() Yiisoft\Db\Schema\Column\AbstractColumn
autoIncrement() Yiisoft\Db\Schema\Column\AbstractColumn
check() Yiisoft\Db\Schema\Column\AbstractColumn
comment() Yiisoft\Db\Schema\Column\AbstractColumn
computed() Yiisoft\Db\Schema\Column\AbstractColumn
dbType() Yiisoft\Db\Schema\Column\AbstractColumn
dbTypecast() Yiisoft\Db\Schema\Column\DateTimeColumn
defaultValue() Yiisoft\Db\Schema\Column\AbstractColumn
extra() Yiisoft\Db\Schema\Column\AbstractColumn
getCheck() Yiisoft\Db\Schema\Column\AbstractColumn
getComment() Yiisoft\Db\Schema\Column\AbstractColumn
getDbType() Yiisoft\Db\Schema\Column\AbstractColumn
getDefaultValue() Yiisoft\Db\Schema\Column\AbstractColumn
getExtra() Yiisoft\Db\Schema\Column\AbstractColumn
getName() Yiisoft\Db\Schema\Column\AbstractColumn
getReference() Yiisoft\Db\Schema\Column\AbstractColumn
getScale() Yiisoft\Db\Schema\Column\AbstractColumn
getSize() Yiisoft\Db\Schema\Column\AbstractColumn
getType() Yiisoft\Db\Schema\Column\AbstractColumn
hasDefaultValue() Yiisoft\Db\Schema\Column\AbstractColumn
isAutoIncrement() Yiisoft\Db\Schema\Column\AbstractColumn
isComputed() Yiisoft\Db\Schema\Column\AbstractColumn
isNotNull() Yiisoft\Db\Schema\Column\AbstractColumn
isPrimaryKey() Yiisoft\Db\Schema\Column\AbstractColumn
isUnique() Yiisoft\Db\Schema\Column\AbstractColumn
isUnsigned() Yiisoft\Db\Schema\Column\AbstractColumn
notNull() Yiisoft\Db\Schema\Column\AbstractColumn
null() Yiisoft\Db\Schema\Column\AbstractColumn
phpTypecast() Converts the value from the database format to PHP DateTimeImmutable object. Yiisoft\Db\Schema\Column\DateTimeColumn
primaryKey() Yiisoft\Db\Schema\Column\AbstractColumn
reference() Yiisoft\Db\Schema\Column\AbstractColumn
scale() Yiisoft\Db\Schema\Column\AbstractColumn
size() Yiisoft\Db\Schema\Column\AbstractColumn
type() Yiisoft\Db\Schema\Column\AbstractColumn
unique() Yiisoft\Db\Schema\Column\AbstractColumn
unsigned() Yiisoft\Db\Schema\Column\AbstractColumn
withName() Yiisoft\Db\Schema\Column\AbstractColumn

Protected Methods

Hide inherited methods

Method Description Defined By
getFormat() Yiisoft\Db\Schema\Column\DateTimeColumn
getMillisecondsFormat() Yiisoft\Db\Schema\Column\DateTimeColumn
getPhpTimezone() Returns the PHP time zone for the string datetime values when converting them to DateTimeImmutable objects before inserting them into the database or after retrieving them from the database. Yiisoft\Db\Schema\Column\DateTimeColumn
shouldConvertTimezone() Yiisoft\Db\Schema\Column\DateTimeColumn
throwWrongTypeException() Yiisoft\Db\Schema\Column\AbstractColumn

Constants

Hide inherited constants

Constant Value Description Defined By
DEFAULT_TYPE \Yiisoft\Db\Constant\ColumnType::DATETIME Yiisoft\Db\Schema\Column\DateTimeColumn

Property Details

Hide inherited properties

$dbTimezone protected property
protected string $dbTimezone 'UTC'
$format protected property
protected string|null $format null
$phpTimezone protected property
protected string $phpTimezone 'UTC'
$shouldConvertTimezone protected property

Method Details

Hide inherited methods

__construct() public method
public mixed __construct ( string|null $type null, boolean $autoIncrement false, string|null $check null, string|null $comment null, boolean $computed false, string|null $dbType null, string|null $extra null, boolean $primaryKey false, string|null $name null, boolean|null $notNull null, Yiisoft\Db\Constraint\ForeignKey|null $reference null, integer|null $scale null, integer|null $size null, boolean $unique false, boolean $unsigned false, mixed $args )
$type string|null

The column's abstract type.

$autoIncrement boolean

Whether the column is auto-incremental.

$check string|null

The check constraint for the column.

$comment string|null

The column's comment.

$computed boolean

Whether the column is a computed column.

$dbType string|null

The column's database type.

$extra string|null

Any extra information that needs to be appended to the column's definition.

$primaryKey boolean

Whether the column is a primary key.

$name string|null

The column's name.

$notNull boolean|null

Whether the column is not nullable.

$reference Yiisoft\Db\Constraint\ForeignKey|null

The foreign key constraint.

$scale integer|null

The number of digits to the right of the decimal point.

$size integer|null

The column's size.

$unique boolean

Whether the column is unique.

$unsigned boolean

Whether the column is unsigned.

$args mixed

Additional arguments to be passed to the constructor.

                public function __construct(
    ?string $type = null,
    private bool $autoIncrement = false,
    private ?string $check = null,
    private ?string $comment = null,
    private bool $computed = false,
    private ?string $dbType = null,
    private ?string $extra = null,
    private bool $primaryKey = false,
    private ?string $name = null,
    private ?bool $notNull = null,
    private ?ForeignKey $reference = null,
    private ?int $scale = null,
    private ?int $size = null,
    private bool $unique = false,
    private bool $unsigned = false,
    mixed ...$args,
) {
    $this->type = $type ?? static::DEFAULT_TYPE;
    if (array_key_exists('defaultValue', $args)) {
        $this->defaultValue = $args['defaultValue'];
        unset($args['defaultValue']);
    }
    /** @psalm-var array<string, mixed> $args */
    foreach ($args as $property => $value) {
        if (property_exists($this, $property)) {
            $this->$property = $value;
        }
    }
}

            
autoIncrement() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn autoIncrement ( boolean $autoIncrement true )
$autoIncrement boolean

                public function autoIncrement(bool $autoIncrement = true): static
{
    $this->autoIncrement = $autoIncrement;
    return $this;
}

            
check() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn check ( string|null $check )
$check string|null

                public function check(?string $check): static
{
    $this->check = $check;
    return $this;
}

            
comment() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn comment ( string|null $comment )
$comment string|null

                public function comment(?string $comment): static
{
    $this->comment = $comment;
    return $this;
}

            
computed() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn computed ( boolean $computed true )
$computed boolean

                public function computed(bool $computed = true): static
{
    $this->computed = $computed;
    return $this;
}

            
dbType() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn dbType ( string|null $dbType )
$dbType string|null

                public function dbType(?string $dbType): static
{
    $this->dbType = $dbType;
    return $this;
}

            
dbTypecast() public method

public float|integer|string|Yiisoft\Db\Expression\ExpressionInterface|null dbTypecast ( mixed $value )
$value mixed

The value representing datetime or time to be typecasted to the database format. Possible values:

  • null;
  • string - it can be:
    • empty string - treated as null;
    • string with integer value - treated as unix timestamp;
    • string with float value - treated as unix timestamp with microseconds;
    • string with datetime format;
  • Stringable object - converted to string;
  • integer - treated as unix timestamp;
  • float - treated as unix timestamp with microseconds;
  • DateTimeImmutable;
  • DateTimeInterface;
  • ExpressionInterface;

If the value is string or a Stringable object, it will be converted to a DateTimeImmutable object with the default time zone set specified in the {@see $phpTimezone} property. If the conversion fails, the original value will be returned.

                public function dbTypecast(mixed $value): float|int|string|ExpressionInterface|null
{
    /** @psalm-suppress MixedArgument, PossiblyFalseArgument */
    return match (gettype($value)) {
        GettypeResult::NULL => null,
        GettypeResult::STRING => $this->dbTypecastString($value),
        GettypeResult::INTEGER => $this->dbTypecastDateTime(DateTimeImmutable::createFromFormat('U', (string) $value)),
        GettypeResult::DOUBLE => $this->dbTypecastDateTime(DateTimeImmutable::createFromFormat('U.u', (string) $value)),
        GettypeResult::OBJECT => match (true) {
            $value instanceof DateTimeImmutable => $this->dbTypecastDateTime($value),
            $value instanceof DateTimeInterface => $this->dbTypecastDateTime(DateTimeImmutable::createFromInterface($value)),
            $value instanceof ExpressionInterface => $value,
            $value instanceof Stringable => $this->dbTypecastString((string) $value),
            default => $this->throwWrongTypeException($value::class),
        },
        default => $this->throwWrongTypeException(gettype($value)),
    };
}

            
defaultValue() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn defaultValue ( mixed $defaultValue )
$defaultValue mixed

                public function defaultValue(mixed $defaultValue): static
{
    $this->defaultValue = $defaultValue;
    return $this;
}

            
extra() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn extra ( string|null $extra )
$extra string|null

                public function extra(?string $extra): static
{
    $this->extra = $extra;
    return $this;
}

            
getCheck() public method
public string|null getCheck ( )

                public function getCheck(): ?string
{
    return $this->check;
}

            
getComment() public method
public string|null getComment ( )

                public function getComment(): ?string
{
    return $this->comment;
}

            
getDbType() public method
public string|null getDbType ( )

                public function getDbType(): ?string
{
    return $this->dbType;
}

            
getDefaultValue() public method
public mixed getDefaultValue ( )

                public function getDefaultValue(): mixed
{
    return $this->defaultValue ?? null;
}

            
getExtra() public method
public string|null getExtra ( )

                public function getExtra(): ?string
{
    return $this->extra;
}

            
getFormat() protected method

protected string getFormat ( )

                protected function getFormat(): string
{
    return $this->format ??= match ($this->getType()) {
        ColumnType::TIMESTAMP,
        ColumnType::DATETIME => 'Y-m-d H:i:s' . $this->getMillisecondsFormat(),
        ColumnType::DATETIMETZ => 'Y-m-d H:i:s' . $this->getMillisecondsFormat() . 'P',
        ColumnType::TIME => 'H:i:s' . $this->getMillisecondsFormat(),
        ColumnType::TIMETZ => 'H:i:s' . $this->getMillisecondsFormat() . 'P',
        ColumnType::DATE => 'Y-m-d',
        ColumnType::INTEGER,
        ColumnType::BIGINT => 'U',
        ColumnType::FLOAT ,
        ColumnType::DOUBLE,
        ColumnType::DECIMAL => 'U.u',
        default => throw new UnexpectedValueException(
            'Unsupported abstract column type ' . $this->getType() . ' for ' . static::class . ' class.',
        ),
    };
}

            
getMillisecondsFormat() protected method

protected string getMillisecondsFormat ( )

                protected function getMillisecondsFormat(): string
{
    return match ($this->getSize()) {
        0 => '',
        1, 2, 3 => '.v',
        default => '.u',
    };
}

            
getName() public method
public string|null getName ( )

                public function getName(): ?string
{
    return $this->name;
}

            
getPhpTimezone() protected method

Returns the PHP time zone for the string datetime values when converting them to DateTimeImmutable objects before inserting them into the database or after retrieving them from the database.

protected string getPhpTimezone ( )

                protected function getPhpTimezone(): string
{
    return empty($this->phpTimezone)
        ? date_default_timezone_get()
        : $this->phpTimezone;
}

            
getReference() public method
public Yiisoft\Db\Constraint\ForeignKey|null getReference ( )

                public function getReference(): ?ForeignKey
{
    return $this->reference;
}

            
getScale() public method
public integer|null getScale ( )

                public function getScale(): ?int
{
    return $this->scale;
}

            
getSize() public method
public integer|null getSize ( )

                public function getSize(): ?int
{
    return $this->size;
}

            
getType() public method
public string getType ( )

                public function getType(): string
{
    return $this->type;
}

            
hasDefaultValue() public method
public boolean hasDefaultValue ( )

                public function hasDefaultValue(): bool
{
    return property_exists($this, 'defaultValue');
}

            
isAutoIncrement() public method
public boolean isAutoIncrement ( )

                public function isAutoIncrement(): bool
{
    return $this->autoIncrement;
}

            
isComputed() public method
public boolean isComputed ( )

                public function isComputed(): bool
{
    return $this->computed;
}

            
isNotNull() public method
public boolean|null isNotNull ( )

                public function isNotNull(): ?bool
{
    return $this->notNull;
}

            
isPrimaryKey() public method
public boolean isPrimaryKey ( )

                public function isPrimaryKey(): bool
{
    return $this->primaryKey;
}

            
isUnique() public method
public boolean isUnique ( )

                public function isUnique(): bool
{
    return $this->unique;
}

            
isUnsigned() public method
public boolean isUnsigned ( )

                public function isUnsigned(): bool
{
    return $this->unsigned;
}

            
notNull() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn notNull ( boolean|null $notNull true )
$notNull boolean|null

                public function notNull(?bool $notNull = true): static
{
    $this->notNull = $notNull;
    return $this;
}

            
null() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn null ( )

                public function null(): static
{
    $this->notNull = false;
    return $this;
}

            
phpTypecast() public method

Converts the value from the database format to PHP DateTimeImmutable object.

If the database type does not have time zone information, the time zone will be set to the current PHP time zone.

public DateTimeImmutable|null phpTypecast ( string|null $value )
$value string|null

                public function phpTypecast(mixed $value): ?DateTimeImmutable
{
    if (is_string($value)) {
        $phpTimezone = $this->getPhpTimezone();
        if ($this->shouldConvertTimezone()) {
            /** @psalm-suppress ArgumentTypeCoercion */
            $datetime = new DateTimeImmutable($value, new DateTimeZone($this->dbTimezone));
            if ($phpTimezone !== $this->dbTimezone) {
                return $datetime->setTimezone(new DateTimeZone($phpTimezone));
            }
            return $datetime;
        }
        return new DateTimeImmutable($value, new DateTimeZone($phpTimezone));
    }
    return $value;
}

            
primaryKey() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn primaryKey ( boolean $primaryKey true )
$primaryKey boolean

                public function primaryKey(bool $primaryKey = true): static
{
    $this->primaryKey = $primaryKey;
    return $this;
}

            
reference() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn reference ( Yiisoft\Db\Constraint\ForeignKey|null $reference )
$reference Yiisoft\Db\Constraint\ForeignKey|null

                public function reference(?ForeignKey $reference): static
{
    $this->reference = $reference;
    return $this;
}

            
scale() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn scale ( integer|null $scale )
$scale integer|null

                public function scale(?int $scale): static
{
    $this->scale = $scale;
    return $this;
}

            
shouldConvertTimezone() protected method

protected boolean shouldConvertTimezone ( )

                protected function shouldConvertTimezone(): bool
{
    return $this->shouldConvertTimezone ??= $this->dbTimezone !== '' && match ($this->getType()) {
        ColumnType::DATETIMETZ,
        ColumnType::TIMETZ,
        ColumnType::DATE => false,
        default => true,
    };
}

            
size() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn size ( integer|null $size )
$size integer|null

                public function size(?int $size): static
{
    $this->size = $size;
    return $this;
}

            
throwWrongTypeException() protected method
protected never throwWrongTypeException ( string $type )
$type string

                protected function throwWrongTypeException(string $type): never
{
    throw new InvalidArgumentException("Wrong $type value for $this->type column.");
}

            
type() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn type ( string $type )
$type string

                public function type(string $type): static
{
    $this->type = $type;
    return $this;
}

            
unique() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn unique ( boolean $unique true )
$unique boolean

                public function unique(bool $unique = true): static
{
    $this->unique = $unique;
    return $this;
}

            
unsigned() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn unsigned ( boolean $unsigned true )
$unsigned boolean

                public function unsigned(bool $unsigned = true): static
{
    $this->unsigned = $unsigned;
    return $this;
}

            
withName() public method
public Yiisoft\Db\Schema\Column\DateTimeColumn withName ( string|null $name )
$name string|null

                public function withName(?string $name): static
{
    $new = clone $this;
    $new->name = $name;
    return $new;
}