vendor/doctrine/dbal/lib/Doctrine/DBAL/Types/DateTimeTzType.php

   1 <?php
   2 /*
   3  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   4  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   5  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   6  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
   7  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   8  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   9  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  10  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  11  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  12  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  13  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14  *
  15  * This software consists of voluntary contributions made by many individuals
  16  * and is licensed under the MIT license. For more information, see
  17  * <http://www.doctrine-project.org>.
  18  */
  19
  20
  21 namespace Doctrine\DBAL\Types;
  22
  23 use Doctrine\DBAL\Platforms\AbstractPlatform;
  24
  25 /**
  26  * DateTime type saving additional timezone information.
  27  *
  28  * Caution: Databases are not necessarily experts at storing timezone related
  29  * data of dates. First, of all the supported vendors only PostgreSQL and Oracle
  30  * support storing Timezone data. But those two don't save the actual timezone
  31  * attached to a DateTime instance (for example "Europe/Berlin" or "America/Montreal")
  32  * but the current offset of them related to UTC. That means depending on daylight saving times
  33  * or not you may get different offsets.
  34  *
  35  * This datatype makes only sense to use, if your application works with an offset, not
  36  * with an actual timezone that uses transitions. Otherwise your DateTime instance
  37  * attached with a timezone such as Europe/Berlin gets saved into the database with
  38  * the offset and re-created from persistence with only the offset, not the original timezone
  39  * attached.
  40  *
  41  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  42  * @link        www.doctrine-project.com
  43  * @since       1.0
  44  * @author      Benjamin Eberlei <kontakt@beberlei.de>
  45  * @author      Guilherme Blanco <guilhermeblanco@hotmail.com>
  46  * @author      Jonathan Wage <jonwage@gmail.com>
  47  * @author      Roman Borschel <roman@code-factory.org>
  48  */
  49 class DateTimeTzType extends Type
  50 {
  51     public function getName()
  52     {
  53         return Type::DATETIMETZ;
  54     }
  55
  56     public function getSQLDeclaration(array $fieldDeclaration, AbstractPlatform $platform)
  57     {
  58         return $platform->getDateTimeTzTypeDeclarationSQL($fieldDeclaration);
  59     }
  60
  61     public function convertToDatabaseValue($value, AbstractPlatform $platform)
  62     {
  63         return ($value !== null)
  64             ? $value->format($platform->getDateTimeTzFormatString()) : null;
  65     }
  66
  67     public function convertToPHPValue($value, AbstractPlatform $platform)
  68     {
  69         if ($value === null || $value instanceof \DateTime) {
  70             return $value;
  71         }
  72
  73         $val = \DateTime::createFromFormat($platform->getDateTimeTzFormatString(), $value);
  74         if ( ! $val) {
  75             throw ConversionException::conversionFailedFormat($value, $this->getName(), $platform->getDateTimeTzFormatString());
  76         }
  77         return $val;
  78     }
  79 }