Merge pull request #2450 from deeky666/add-immutable-date-types

Add immutable date types

docs/en/reference/known-vendor-issues.rst

@@ -26,7 +26,7 @@ full representation:
 
     2010-10-10 10:10:10.123456 (Y-m-d H:i:s.u)
 
-Using the DateTime, DateTimeTz or Time type with microseconds
+Using the DateTime, DateTimeTz or Time type (and immutable variants) with microseconds
 enabled columns can lead to errors because internally types expect
 the exact format 'Y-m-d H:i:s' in combination with
 ``DateTime::createFromFormat()``. This method is twice a fast as
@@ -42,8 +42,8 @@ without microseconds:
 
 If you do not let Doctrine create the date column types and rather
 use types with microseconds you have replace the "DateTime",
-"DateTimeTz" and "Time" types with a more liberal DateTime parser
-that detects the format automatically:
+"DateTimeTz" and "Time" types (and immutable variants) with a more
+liberal DateTime parser that detects the format automatically:
 
 ::
 
@@ -53,6 +53,10 @@ that detects the format automatically:
     Type::overrideType('datetimetz', 'Doctrine\DBAL\Types\VarDateTimeType');
     Type::overrideType('time', 'Doctrine\DBAL\Types\VarDateTimeType');
 
+    Type::overrideType('datetime_immutable', 'Doctrine\DBAL\Types\VarDateTimeImmutableType');
+    Type::overrideType('datetimetz_immutable', 'Doctrine\DBAL\Types\VarDateTimeImmutableType');
+    Type::overrideType('time_immutable', 'Doctrine\DBAL\Types\VarDateTimeImmutableType');
+
 Timezones and DateTimeTz
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -191,8 +195,8 @@ a value with microseconds = 0.
 
 If you do not let Doctrine create the date column types and rather
 use types with microseconds you have replace the "DateTime",
-"DateTimeTz" and "Time" types with a more liberal DateTime parser
-that detects the format automatically:
+"DateTimeTz" and "Time" types (and immutable variants) with a more
+liberal DateTime parser that detects the format automatically:
 
 ::
 
@@ -202,6 +206,10 @@ that detects the format automatically:
     Type::overrideType('datetimetz', 'Doctrine\DBAL\Types\VarDateTime');
     Type::overrideType('time', 'Doctrine\DBAL\Types\VarDateTime');
 
+    Type::overrideType('datetime_immutable', 'Doctrine\DBAL\Types\VarDateTimeImmutableType');
+    Type::overrideType('datetimetz_immutable', 'Doctrine\DBAL\Types\VarDateTimeImmutableType');
+    Type::overrideType('time_immutable', 'Doctrine\DBAL\Types\VarDateTimeImmutableType');
+
 PDO_SQLSRV: VARBINARY/BLOB columns
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/en/reference/types.rst

@@ -248,6 +248,17 @@ without time and timezone information, you should consider using this type.
 Values retrieved from the database are always converted to PHP's ``\DateTime`` object
 or ``null`` if no data is present.
 
+date_immutable
+^^^^^^^^^^^^^^
+
+The immutable variant of the ``date`` type.
+Values retrieved from the database are always converted to PHP's ``\DateTimeImmutable``
+object or ``null`` if no data is present.
+
+.. note::
+
+    Available since version ``2.6``.
+
 datetime
 ^^^^^^^^
 
@@ -271,6 +282,17 @@ or ``null`` if no data is present.
     and not parsed correctly by ``date_create()``, however since
     databases are rather strict on dates there should be no problem.
 
+datetime_immutable
+^^^^^^^^^^^^^^^^^^
+
+The immutable variant of the ``datetime`` type.
+Values retrieved from the database are always converted to PHP's ``\DateTimeImmutable``
+object or ``null`` if no data is present.
+
+.. note::
+
+    Available since version ``2.6``.
+
 datetimetz
 ^^^^^^^^^^
 
@@ -280,6 +302,17 @@ information, you should consider using this type.
 Values retrieved from the database are always converted to PHP's ``\DateTime`` object
 or ``null`` if no data is present.
 
+datetimetz_immutable
+^^^^^^^^^^^^^^^^^^^^
+
+The immutable variant of the ``datetimetz`` type.
+Values retrieved from the database are always converted to PHP's ``\DateTimeImmutable``
+object or ``null`` if no data is present.
+
+.. note::
+
+    Available since version ``2.6``.
+
 time
 ^^^^
 
@@ -289,6 +322,17 @@ without date, time and timezone information, you should consider using this type
 Values retrieved from the database are always converted to PHP's ``\DateTime`` object
 or ``null`` if no data is present.
 
+time_immutable
+^^^^^^^^^^^^^^
+
+The immutable variant of the ``time`` type.
+Values retrieved from the database are always converted to PHP's ``\DateTimeImmutable``
+object or ``null`` if no data is present.
+
+.. note::
+
+    Available since version ``2.6``.
+
 dateinterval
 ^^^^^^^^^^^^
 
@@ -374,7 +418,7 @@ json
 Maps and converts array data based on PHP's JSON encoding functions.
 If you know that the data to be stored always is in a valid UTF-8
 encoded JSON format string, you should consider using this type.
-Values retrieved from the database are always converted to PHP's ``array`` or 
+Values retrieved from the database are always converted to PHP's ``array`` or
 ``null`` types using PHP's ``json_decode()`` function.
 
 .. note::

lib/Doctrine/DBAL/Types/DateImmutableType.php

+<?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
+
+namespace Doctrine\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+
+/**
+ * Immutable type of {@see DateType}.
+ *
+ * @since  2.6
+ * @author Steve Müller <deeky666@googlemail.com>
+ */
+class DateImmutableType extends DateType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getName()
+    {
+        return Type::DATE_IMMUTABLE;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToDatabaseValue($value, AbstractPlatform $platform)
+    {
+        if (null === $value) {
+            return $value;
+        }
+
+        if ($value instanceof \DateTimeImmutable) {
+            return $value->format($platform->getDateFormatString());
+        }
+
+        throw ConversionException::conversionFailedInvalidType(
+            $value,
+            $this->getName(),
+            ['null', \DateTimeImmutable::class]
+        );
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToPHPValue($value, AbstractPlatform $platform)
+    {
+        if ($value === null || $value instanceof \DateTimeImmutable) {
+            return $value;
+        }
+
+        $dateTime = \DateTimeImmutable::createFromFormat('!' . $platform->getDateFormatString(), $value);
+
+        if (! $dateTime) {
+            throw ConversionException::conversionFailedFormat(
+                $value,
+                $this->getName(),
+                $platform->getDateFormatString()
+            );
+        }
+
+        return $dateTime;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function requiresSQLCommentHint(AbstractPlatform $platform)
+    {
+        return true;
+    }
+}

lib/Doctrine/DBAL/Types/DateTimeImmutableType.php

+<?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
+
+namespace Doctrine\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+
+/**
+ * Immutable type of {@see DateTimeType}.
+ *
+ * @since  2.6
+ * @author Steve Müller <deeky666@googlemail.com>
+ */
+class DateTimeImmutableType extends DateTimeType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getName()
+    {
+        return Type::DATETIME_IMMUTABLE;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToDatabaseValue($value, AbstractPlatform $platform)
+    {
+        if (null === $value) {
+            return $value;
+        }
+
+        if ($value instanceof \DateTimeImmutable) {
+            return $value->format($platform->getDateTimeFormatString());
+        }
+
+        throw ConversionException::conversionFailedInvalidType(
+            $value,
+            $this->getName(),
+            ['null', \DateTimeImmutable::class]
+        );
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToPHPValue($value, AbstractPlatform $platform)
+    {
+        if ($value === null || $value instanceof \DateTimeImmutable) {
+            return $value;
+        }
+
+        $dateTime = \DateTimeImmutable::createFromFormat($platform->getDateTimeFormatString(), $value);
+
+        if (! $dateTime) {
+            $dateTime = \date_create_immutable($value);
+        }
+
+        if (! $dateTime) {
+            throw ConversionException::conversionFailedFormat(
+                $value,
+                $this->getName(),
+                $platform->getDateTimeFormatString()
+            );
+        }
+
+        return $dateTime;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function requiresSQLCommentHint(AbstractPlatform $platform)
+    {
+        return true;
+    }
+}

lib/Doctrine/DBAL/Types/DateTimeTzImmutableType.php

+<?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
+
+namespace Doctrine\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+
+/**
+ * Immutable type of {@see DateTimeTzType}.
+ *
+ * @since  2.6
+ * @author Steve Müller <deeky666@googlemail.com>
+ */
+class DateTimeTzImmutableType extends DateTimeTzType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getName()
+    {
+        return Type::DATETIMETZ_IMMUTABLE;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToDatabaseValue($value, AbstractPlatform $platform)
+    {
+        if (null === $value) {
+            return $value;
+        }
+
+        if ($value instanceof \DateTimeImmutable) {
+            return $value->format($platform->getDateTimeTzFormatString());
+        }
+
+        throw ConversionException::conversionFailedInvalidType(
+            $value,
+            $this->getName(),
+            ['null', \DateTimeImmutable::class]
+        );
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToPHPValue($value, AbstractPlatform $platform)
+    {
+        if ($value === null || $value instanceof \DateTimeImmutable) {
+            return $value;
+        }
+
+        $dateTime = \DateTimeImmutable::createFromFormat($platform->getDateTimeTzFormatString(), $value);
+
+        if (! $dateTime) {
+            throw ConversionException::conversionFailedFormat(
+                $value,
+                $this->getName(),
+                $platform->getDateTimeTzFormatString()
+            );
+        }
+
+        return $dateTime;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function requiresSQLCommentHint(AbstractPlatform $platform)
+    {
+        return true;
+    }
+}

lib/Doctrine/DBAL/Types/TimeImmutableType.php

+<?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
+
+namespace Doctrine\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+
+/**
+ * Immutable type of {@see TimeType}.
+ *
+ * @since  2.6
+ * @author Steve Müller <deeky666@googlemail.com>
+ */
+class TimeImmutableType extends TimeType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getName()
+    {
+        return Type::TIME_IMMUTABLE;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToDatabaseValue($value, AbstractPlatform $platform)
+    {
+        if (null === $value) {
+            return $value;
+        }
+
+        if ($value instanceof \DateTimeImmutable) {
+            return $value->format($platform->getTimeFormatString());
+        }
+
+        throw ConversionException::conversionFailedInvalidType(
+            $value,
+            $this->getName(),
+            ['null', \DateTimeImmutable::class]
+        );
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToPHPValue($value, AbstractPlatform $platform)
+    {
+        if ($value === null || $value instanceof \DateTimeImmutable) {
+            return $value;
+        }
+
+        $dateTime = \DateTimeImmutable::createFromFormat('!' . $platform->getTimeFormatString(), $value);
+
+        if (! $dateTime) {
+            throw ConversionException::conversionFailedFormat(
+                $value,
+                $this->getName(),
+                $platform->getTimeFormatString()
+            );
+        }
+
+        return $dateTime;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function requiresSQLCommentHint(AbstractPlatform $platform)
+    {
+        return true;
+    }
+}

lib/Doctrine/DBAL/Types/Type.php

@@ -40,9 +40,13 @@ abstract class Type
     const BIGINT = 'bigint';
     const BOOLEAN = 'boolean';
     const DATETIME = 'datetime';
+    const DATETIME_IMMUTABLE = 'datetime_immutable';
     const DATETIMETZ = 'datetimetz';
+    const DATETIMETZ_IMMUTABLE = 'datetimetz_immutable';
     const DATE = 'date';
+    const DATE_IMMUTABLE = 'date_immutable';
     const TIME = 'time';
+    const TIME_IMMUTABLE = 'time_immutable';
     const DECIMAL = 'decimal';
     const INTEGER = 'integer';
     const OBJECT = 'object';
@@ -68,27 +72,31 @@ abstract class Type
      * @var array
      */
     private static $_typesMap = array(
-        self::TARRAY => 'Doctrine\DBAL\Types\ArrayType',
-        self::SIMPLE_ARRAY => 'Doctrine\DBAL\Types\SimpleArrayType',
-        self::JSON_ARRAY => 'Doctrine\DBAL\Types\JsonArrayType',
-        self::JSON => 'Doctrine\DBAL\Types\JsonType',
-        self::OBJECT => 'Doctrine\DBAL\Types\ObjectType',
-        self::BOOLEAN => 'Doctrine\DBAL\Types\BooleanType',
-        self::INTEGER => 'Doctrine\DBAL\Types\IntegerType',
-        self::SMALLINT => 'Doctrine\DBAL\Types\SmallIntType',
-        self::BIGINT => 'Doctrine\DBAL\Types\BigIntType',
-        self::STRING => 'Doctrine\DBAL\Types\StringType',
-        self::TEXT => 'Doctrine\DBAL\Types\TextType',
-        self::DATETIME => 'Doctrine\DBAL\Types\DateTimeType',
-        self::DATETIMETZ => 'Doctrine\DBAL\Types\DateTimeTzType',
-        self::DATE => 'Doctrine\DBAL\Types\DateType',
-        self::TIME => 'Doctrine\DBAL\Types\TimeType',
-        self::DECIMAL => 'Doctrine\DBAL\Types\DecimalType',
-        self::FLOAT => 'Doctrine\DBAL\Types\FloatType',
-        self::BINARY => 'Doctrine\DBAL\Types\BinaryType',
-        self::BLOB => 'Doctrine\DBAL\Types\BlobType',
-        self::GUID => 'Doctrine\DBAL\Types\GuidType',
-        self::DATEINTERVAL => 'Doctrine\DBAL\Types\DateIntervalType',
+        self::TARRAY => ArrayType::class,
+        self::SIMPLE_ARRAY => SimpleArrayType::class,
+        self::JSON_ARRAY => JsonArrayType::class,
+        self::JSON => JsonType::class,
+        self::OBJECT => ObjectType::class,
+        self::BOOLEAN => BooleanType::class,
+        self::INTEGER => IntegerType::class,
+        self::SMALLINT => SmallIntType::class,
+        self::BIGINT => BigIntType::class,
+        self::STRING => StringType::class,
+        self::TEXT => TextType::class,
+        self::DATETIME => DateTimeType::class,
+        self::DATETIME_IMMUTABLE => DateTimeImmutableType::class,
+        self::DATETIMETZ => DateTimeTzType::class,
+        self::DATETIMETZ_IMMUTABLE => DateTimeTzImmutableType::class,
+        self::DATE => DateType::class,
+        self::DATE_IMMUTABLE => DateImmutableType::class,
+        self::TIME => TimeType::class,
+        self::TIME_IMMUTABLE => TimeImmutableType::class,
+        self::DECIMAL => DecimalType::class,
+        self::FLOAT => FloatType::class,
+        self::BINARY => BinaryType::class,
+        self::BLOB => BlobType::class,
+        self::GUID => GuidType::class,
+        self::DATEINTERVAL => DateIntervalType::class,
     );
 
     /**

lib/Doctrine/DBAL/Types/VarDateTimeImmutableType.php

+<?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
+
+namespace Doctrine\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+
+/**
+ * Immutable type of {@see VarDateTimeType}.
+ *
+ * @since  2.6
+ * @author Steve Müller <deeky666@googlemail.com>
+ */
+class VarDateTimeImmutableType extends VarDateTimeType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getName()
+    {
+        return Type::DATETIME_IMMUTABLE;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToDatabaseValue($value, AbstractPlatform $platform)
+    {
+        if (null === $value) {
+            return $value;
+        }
+
+        if ($value instanceof \DateTimeImmutable) {
+            return $value->format($platform->getDateTimeFormatString());
+        }
+
+        throw ConversionException::conversionFailedInvalidType(
+            $value,
+            $this->getName(),
+            ['null', \DateTimeImmutable::class]
+        );
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function convertToPHPValue($value, AbstractPlatform $platform)
+    {
+        if ($value === null || $value instanceof \DateTimeImmutable) {
+            return $value;
+        }
+
+        $dateTime = date_create_immutable($value);
+
+        if (! $dateTime) {
+            throw ConversionException::conversionFailed($value, $this->getName());
+        }
+
+        return $dateTime;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function requiresSQLCommentHint(AbstractPlatform $platform)
+    {
+        return true;
+    }
+}

tests/Doctrine/Tests/DBAL/Types/DateImmutableTypeTest.php

+<?php
+
+namespace Doctrine\Tests\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Types\ConversionException;
+use Doctrine\DBAL\Types\DateImmutableType;
+use Doctrine\DBAL\Types\Type;
+
+class DateImmutableTypeTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @var \Doctrine\DBAL\Platforms\AbstractPlatform|\Prophecy\Prophecy\ObjectProphecy
+     */
+    private $platform;
+
+    /**
+     * @var DateImmutableType
+     */
+    private $type;
+
+    protected function setUp()
+    {
+        $this->type = Type::getType('date_immutable');
+        $this->platform = $this->prophesize(AbstractPlatform::class);
+    }
+
+    public function testFactoryCreatesCorrectType()
+    {
+        $this->assertSame(DateImmutableType::class, get_class($this->type));
+    }
+
+    public function testReturnsName()
+    {
+        $this->assertSame('date_immutable', $this->type->getName());
+    }
+
+    public function testReturnsBindingType()
+    {
+        $this->assertSame(\PDO::PARAM_STR, $this->type->getBindingType());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToDatabaseValue()
+    {
+        $date = $this->prophesize(\DateTimeImmutable::class);
+
+        $this->platform->getDateFormatString()->willReturn('Y-m-d')->shouldBeCalled();
+        $date->format('Y-m-d')->willReturn('2016-01-01')->shouldBeCalled();
+
+        $this->assertSame(
+            '2016-01-01',
+            $this->type->convertToDatabaseValue($date->reveal(), $this->platform->reveal())
+        );
+    }
+
+    public function testConvertsNullToDatabaseValue()
+    {
+        $this->assertNull($this->type->convertToDatabaseValue(null, $this->platform->reveal()));
+    }
+
+    public function testDoesNotSupportMutableDateTimeToDatabaseValueConversion()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToDatabaseValue(new \DateTime(), $this->platform->reveal());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToPHPValue()
+    {
+        $date = new \DateTimeImmutable();
+
+        $this->assertSame($date, $this->type->convertToPHPValue($date, $this->platform->reveal()));
+    }
+
+    public function testConvertsNullToPHPValue()
+    {
+        $this->assertNull($this->type->convertToPHPValue(null, $this->platform->reveal()));
+    }
+
+    public function testConvertsDateStringToPHPValue()
+    {
+        $this->platform->getDateFormatString()->willReturn('Y-m-d')->shouldBeCalled();
+
+        $date = $this->type->convertToPHPValue('2016-01-01', $this->platform->reveal());
+
+        $this->assertInstanceOf(\DateTimeImmutable::class, $date);
+        $this->assertSame('2016-01-01', $date->format('Y-m-d'));
+    }
+
+    public function testResetTimeFractionsWhenConvertingToPHPValue()
+    {
+        $this->platform->getDateFormatString()->willReturn('Y-m-d');
+
+        $date = $this->type->convertToPHPValue('2016-01-01', $this->platform->reveal());
+
+        $this->assertSame('2016-01-01 00:00:00.000000', $date->format('Y-m-d H:i:s.u'));
+    }
+
+    public function testThrowsExceptionDuringConversionToPHPValueWithInvalidDateString()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToPHPValue('invalid date string', $this->platform->reveal());
+    }
+
+    public function testRequiresSQLCommentHint()
+    {
+        $this->assertTrue($this->type->requiresSQLCommentHint($this->platform->reveal()));
+    }
+}

tests/Doctrine/Tests/DBAL/Types/DateTimeImmutableTypeTest.php

+<?php
+
+namespace Doctrine\Tests\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Types\ConversionException;
+use Doctrine\DBAL\Types\DateTimeImmutableType;
+use Doctrine\DBAL\Types\Type;
+
+class DateTimeImmutableTypeTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @var \Doctrine\DBAL\Platforms\AbstractPlatform|\Prophecy\Prophecy\ObjectProphecy
+     */
+    private $platform;
+
+    /**
+     * @var DateTimeImmutableType
+     */
+    private $type;
+
+    protected function setUp()
+    {
+        $this->type = Type::getType('datetime_immutable');
+        $this->platform = $this->prophesize(AbstractPlatform::class);
+    }
+
+    public function testFactoryCreatesCorrectType()
+    {
+        $this->assertSame(DateTimeImmutableType::class, get_class($this->type));
+    }
+
+    public function testReturnsName()
+    {
+        $this->assertSame('datetime_immutable', $this->type->getName());
+    }
+
+    public function testReturnsBindingType()
+    {
+        $this->assertSame(\PDO::PARAM_STR, $this->type->getBindingType());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToDatabaseValue()
+    {
+        $date = $this->prophesize(\DateTimeImmutable::class);
+
+        $this->platform->getDateTimeFormatString()->willReturn('Y-m-d H:i:s')->shouldBeCalled();
+        $date->format('Y-m-d H:i:s')->willReturn('2016-01-01 15:58:59')->shouldBeCalled();
+
+        $this->assertSame(
+            '2016-01-01 15:58:59',
+            $this->type->convertToDatabaseValue($date->reveal(), $this->platform->reveal())
+        );
+    }
+
+    public function testConvertsNullToDatabaseValue()
+    {
+        $this->assertNull($this->type->convertToDatabaseValue(null, $this->platform->reveal()));
+    }
+
+    public function testDoesNotSupportMutableDateTimeToDatabaseValueConversion()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToDatabaseValue(new \DateTime(), $this->platform->reveal());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToPHPValue()
+    {
+        $date = new \DateTimeImmutable();
+
+        $this->assertSame($date, $this->type->convertToPHPValue($date, $this->platform->reveal()));
+    }
+
+    public function testConvertsNullToPHPValue()
+    {
+        $this->assertNull($this->type->convertToPHPValue(null, $this->platform->reveal()));
+    }
+
+    public function testConvertsDateTimeStringToPHPValue()
+    {
+        $this->platform->getDateTimeFormatString()->willReturn('Y-m-d H:i:s')->shouldBeCalled();
+
+        $date = $this->type->convertToPHPValue('2016-01-01 15:58:59', $this->platform->reveal());
+
+        $this->assertInstanceOf(\DateTimeImmutable::class, $date);
+        $this->assertSame('2016-01-01 15:58:59', $date->format('Y-m-d H:i:s'));
+    }
+
+    /**
+     * @group DBAL-415
+     */
+    public function testConvertsDateTimeStringWithMicrosecondsToPHPValue()
+    {
+        $this->platform->getDateTimeFormatString()->willReturn('Y-m-d H:i:s');
+
+        $date = $this->type->convertToPHPValue('2016-01-01 15:58:59.123456', $this->platform->reveal());
+
+        $this->assertSame('2016-01-01 15:58:59', $date->format('Y-m-d H:i:s'));
+    }
+
+    public function testThrowsExceptionDuringConversionToPHPValueWithInvalidDateTimeString()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToPHPValue('invalid datetime string', $this->platform->reveal());
+    }
+
+    public function testRequiresSQLCommentHint()
+    {
+        $this->assertTrue($this->type->requiresSQLCommentHint($this->platform->reveal()));
+    }
+}

tests/Doctrine/Tests/DBAL/Types/DateTimeTzImmutableTypeTest.php

+<?php
+
+namespace Doctrine\Tests\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Types\ConversionException;
+use Doctrine\DBAL\Types\DateTimeTzImmutableType;
+use Doctrine\DBAL\Types\Type;
+
+class DateTimeTzImmutableTypeTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @var \Doctrine\DBAL\Platforms\AbstractPlatform|\Prophecy\Prophecy\ObjectProphecy
+     */
+    private $platform;
+
+    /**
+     * @var DateTimeTzImmutableType
+     */
+    private $type;
+
+    protected function setUp()
+    {
+        $this->type = Type::getType('datetimetz_immutable');
+        $this->platform = $this->prophesize(AbstractPlatform::class);
+    }
+
+    public function testFactoryCreatesCorrectType()
+    {
+        $this->assertSame(DateTimeTzImmutableType::class, get_class($this->type));
+    }
+
+    public function testReturnsName()
+    {
+        $this->assertSame('datetimetz_immutable', $this->type->getName());
+    }
+
+    public function testReturnsBindingType()
+    {
+        $this->assertSame(\PDO::PARAM_STR, $this->type->getBindingType());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToDatabaseValue()
+    {
+        $date = $this->prophesize(\DateTimeImmutable::class);
+
+        $this->platform->getDateTimeTzFormatString()->willReturn('Y-m-d H:i:s T')->shouldBeCalled();
+        $date->format('Y-m-d H:i:s T')->willReturn('2016-01-01 15:58:59 UTC')->shouldBeCalled();
+
+        $this->assertSame(
+            '2016-01-01 15:58:59 UTC',
+            $this->type->convertToDatabaseValue($date->reveal(), $this->platform->reveal())
+        );
+    }
+
+    public function testConvertsNullToDatabaseValue()
+    {
+        $this->assertNull($this->type->convertToDatabaseValue(null, $this->platform->reveal()));
+    }
+
+    public function testDoesNotSupportMutableDateTimeToDatabaseValueConversion()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToDatabaseValue(new \DateTime(), $this->platform->reveal());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToPHPValue()
+    {
+        $date = new \DateTimeImmutable();
+
+        $this->assertSame($date, $this->type->convertToPHPValue($date, $this->platform->reveal()));
+    }
+
+    public function testConvertsNullToPHPValue()
+    {
+        $this->assertNull($this->type->convertToPHPValue(null, $this->platform->reveal()));
+    }
+
+    public function testConvertsDateTimeWithTimezoneStringToPHPValue()
+    {
+        $this->platform->getDateTimeTzFormatString()->willReturn('Y-m-d H:i:s T')->shouldBeCalled();
+
+        $date = $this->type->convertToPHPValue('2016-01-01 15:58:59 UTC', $this->platform->reveal());
+
+        $this->assertInstanceOf(\DateTimeImmutable::class, $date);
+        $this->assertSame('2016-01-01 15:58:59 UTC', $date->format('Y-m-d H:i:s T'));
+    }
+
+    public function testThrowsExceptionDuringConversionToPHPValueWithInvalidDateTimeWithTimezoneString()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToPHPValue('invalid datetime with timezone string', $this->platform->reveal());
+    }
+
+    public function testRequiresSQLCommentHint()
+    {
+        $this->assertTrue($this->type->requiresSQLCommentHint($this->platform->reveal()));
+    }
+}

tests/Doctrine/Tests/DBAL/Types/TimeImmutableTypeTest.php

+<?php
+
+namespace Doctrine\Tests\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Types\ConversionException;
+use Doctrine\DBAL\Types\TimeImmutableType;
+use Doctrine\DBAL\Types\Type;
+
+class TimeImmutableTypeTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @var \Doctrine\DBAL\Platforms\AbstractPlatform|\Prophecy\Prophecy\ObjectProphecy
+     */
+    private $platform;
+
+    /**
+     * @var TimeImmutableType
+     */
+    private $type;
+
+    protected function setUp()
+    {
+        $this->type = Type::getType('time_immutable');
+        $this->platform = $this->prophesize(AbstractPlatform::class);
+    }
+
+    public function testFactoryCreatesCorrectType()
+    {
+        $this->assertSame(TimeImmutableType::class, get_class($this->type));
+    }
+
+    public function testReturnsName()
+    {
+        $this->assertSame('time_immutable', $this->type->getName());
+    }
+
+    public function testReturnsBindingType()
+    {
+        $this->assertSame(\PDO::PARAM_STR, $this->type->getBindingType());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToDatabaseValue()
+    {
+        $date = $this->prophesize(\DateTimeImmutable::class);
+
+        $this->platform->getTimeFormatString()->willReturn('H:i:s')->shouldBeCalled();
+        $date->format('H:i:s')->willReturn('15:58:59')->shouldBeCalled();
+
+        $this->assertSame(
+            '15:58:59',
+            $this->type->convertToDatabaseValue($date->reveal(), $this->platform->reveal())
+        );
+    }
+
+    public function testConvertsNullToDatabaseValue()
+    {
+        $this->assertNull($this->type->convertToDatabaseValue(null, $this->platform->reveal()));
+    }
+
+    public function testDoesNotSupportMutableDateTimeToDatabaseValueConversion()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToDatabaseValue(new \DateTime(), $this->platform->reveal());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToPHPValue()
+    {
+        $date = new \DateTimeImmutable();
+
+        $this->assertSame($date, $this->type->convertToPHPValue($date, $this->platform->reveal()));
+    }
+
+    public function testConvertsNullToPHPValue()
+    {
+        $this->assertNull($this->type->convertToPHPValue(null, $this->platform->reveal()));
+    }
+
+    public function testConvertsTimeStringToPHPValue()
+    {
+        $this->platform->getTimeFormatString()->willReturn('H:i:s')->shouldBeCalled();
+
+        $date = $this->type->convertToPHPValue('15:58:59', $this->platform->reveal());
+
+        $this->assertInstanceOf(\DateTimeImmutable::class, $date);
+        $this->assertSame('15:58:59', $date->format('H:i:s'));
+    }
+
+    public function testResetDateFractionsWhenConvertingToPHPValue()
+    {
+        $this->platform->getTimeFormatString()->willReturn('H:i:s');
+
+        $date = $this->type->convertToPHPValue('15:58:59', $this->platform->reveal());
+
+        $this->assertSame('1970-01-01 15:58:59', $date->format('Y-m-d H:i:s'));
+    }
+
+    public function testThrowsExceptionDuringConversionToPHPValueWithInvalidTimeString()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToPHPValue('invalid time string', $this->platform->reveal());
+    }
+
+    public function testRequiresSQLCommentHint()
+    {
+        $this->assertTrue($this->type->requiresSQLCommentHint($this->platform->reveal()));
+    }
+}

tests/Doctrine/Tests/DBAL/Types/VarDateTimeImmutableTypeTest.php

+<?php
+
+namespace Doctrine\Tests\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Types\ConversionException;
+use Doctrine\DBAL\Types\VarDateTimeImmutableType;
+use Doctrine\DBAL\Types\Type;
+
+class VarDateTimeImmutableTypeTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @var \Doctrine\DBAL\Platforms\AbstractPlatform|\Prophecy\Prophecy\ObjectProphecy
+     */
+    private $platform;
+
+    /**
+     * @var VarDateTimeImmutableType
+     */
+    private $type;
+
+    protected function setUp()
+    {
+        if (! Type::hasType('vardatetime_immutable')) {
+            Type::addType('vardatetime_immutable', VarDateTimeImmutableType::class);
+        }
+
+        $this->type = Type::getType('vardatetime_immutable');
+        $this->platform = $this->prophesize(AbstractPlatform::class);
+    }
+
+    public function testReturnsName()
+    {
+        $this->assertSame('datetime_immutable', $this->type->getName());
+    }
+
+    public function testReturnsBindingType()
+    {
+        $this->assertSame(\PDO::PARAM_STR, $this->type->getBindingType());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToDatabaseValue()
+    {
+        $date = $this->prophesize(\DateTimeImmutable::class);
+
+        $this->platform->getDateTimeFormatString()->willReturn('Y-m-d H:i:s')->shouldBeCalled();
+        $date->format('Y-m-d H:i:s')->willReturn('2016-01-01 15:58:59')->shouldBeCalled();
+
+        $this->assertSame(
+            '2016-01-01 15:58:59',
+            $this->type->convertToDatabaseValue($date->reveal(), $this->platform->reveal())
+        );
+    }
+
+    public function testConvertsNullToDatabaseValue()
+    {
+        $this->assertNull($this->type->convertToDatabaseValue(null, $this->platform->reveal()));
+    }
+
+    public function testDoesNotSupportMutableDateTimeToDatabaseValueConversion()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToDatabaseValue(new \DateTime(), $this->platform->reveal());
+    }
+
+    public function testConvertsDateTimeImmutableInstanceToPHPValue()
+    {
+        $date = new \DateTimeImmutable();
+
+        $this->assertSame($date, $this->type->convertToPHPValue($date, $this->platform->reveal()));
+    }
+
+    public function testConvertsNullToPHPValue()
+    {
+        $this->assertNull($this->type->convertToPHPValue(null, $this->platform->reveal()));
+    }
+
+    public function testConvertsDateishStringToPHPValue()
+    {
+        $this->platform->getDateTimeFormatString()->shouldNotBeCalled();
+
+        $date = $this->type->convertToPHPValue('2016-01-01 15:58:59.123456 UTC', $this->platform->reveal());
+
+        $this->assertInstanceOf(\DateTimeImmutable::class, $date);
+        $this->assertSame('2016-01-01 15:58:59.123456 UTC', $date->format('Y-m-d H:i:s.u T'));
+    }
+
+    public function testThrowsExceptionDuringConversionToPHPValueWithInvalidDateishString()
+    {
+        $this->expectException(ConversionException::class);
+
+        $this->type->convertToPHPValue('invalid date-ish string', $this->platform->reveal());
+    }
+
+    public function testRequiresSQLCommentHint()
+    {
+        $this->assertTrue($this->type->requiresSQLCommentHint($this->platform->reveal()));
+    }
+}