vasek-purchart/doctrine-date-time-immutable-types-bundle

Bundle integration of Doctrine DateTimeImmutable types for Symfony

2.0 2017-08-16 12:46 UTC

Requires

• doctrine/dbal: ~2.6
• doctrine/doctrine-bundle: ~1.3
• symfony/config: ~3.0
• symfony/dependency-injection: ~3.0
• symfony/http-kernel: ~3.0
• symfony/yaml: ~3.0

Requires (Dev)

• consistence/coding-standard: 2.0
• jakub-onderka/php-console-highlighter: 0.3.2
• jakub-onderka/php-parallel-lint: 0.9.2
• phing/phing: 2.16
• phpunit/phpunit: 6.3

MIT

• Vašek Purchart

• dbal
• symfony
• bundle
• doctrine
• type
• datetime
• immutable
• datetimeimmutable

README

In Doctrine DBAL 2.6 immutable DateTime types were added, so this bundle no longer uses custom DateTime types implementation, but rather offers control, how the immutable types are registered, offering the possibility to replace the original DateTime types.

If you cannot upgrade to Doctrine DBAL 2.6 use 1.0 version of this bundle, which uses the vasek-purchart/doctrine-date-time-immutable-types custom DateTime types implementation.

Why would I want to use immutable types?

All Doctrine date/time based types are using DateTime instances, which are mutable. This can lead to breaking encapsulation and therefore bugs. For two reasons:

1. You accidentally modify a date when you are doing some computation on it:

<?php

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity()
 */
class LogRow
{

	// ...

	/**
	 * @ORM/Column(type="datetime")
	 * @var \DateTime
	 */
	private $createdDate;

	public function getCreatedDate(): DateTime
	{
		return $this->createdDate;
	}

}

<?php

// created date might be modified
// even if this was not intended by the creator
// (there is no "setter" method for this on the entity)
var_dump($logRow->getCreatedDate()); // 2015-01-01 00:00:00
$logRow->getCreatedDate()->modify('+14 days');
var_dump($logRow->getCreatedDate()); // 2015-01-15 00:00:00

1. Or you do intentionally try to update it, which fails because Doctrine will not see this:

<?php

$product->getRenewDate()->modify('+1 year');
$entityManager->persist($product);
// no updates will be fired because Doctrine could not detect change
// (objects are compared by identity)
$entityManager->flush();

You can prevent this behaviour by returning a new instance (cloning) or using DateTimeImmutable (which returns a new instance when modified).

Configuration

Configuration structure with listed default values:

# app/config/config.yml
doctrine_date_time_immutable_types:
    # Choose under which names the types will be registered.
    register: add # One of "add"; "replace"

register

• add - add types as new - suffixed with _immutable (e.g. datetime_immutable) - this is already done by DBAL from version 2.6
• replace - replace the original types date, time, datetime, datetimetz, i.e. making them immutable

Usage

If you are using the replace option, you don't need to change any property mappings of your entities.

If you are using the add option (default), you only have to suffix your field types with _immutable:

<?php

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity()
 */
class LogRow
{

	// ...

	/**
	 * @ORM/Column(type="datetime_immutable")
	 * @var \DateTimeImmutable
	 */
	private $createdDate;

	public function getCreatedDate(): DateTimeImmutable
	{
		return $this->createdDate;
	}

}

<?php

// created date can no longer be modified from outside
var_dump($logRow->getCreatedDate()); // 2015-01-01 00:00:00
$logRow->getCreatedDate()->modify('+14 days');
var_dump($logRow->getCreatedDate()); // 2015-01-01 00:00:00

Installation

Install package vasek-purchart/doctrine-date-time-immutable-types-bundle with Composer:

composer require vasek-purchart/doctrine-date-time-immutable-types-bundle

Register the bundle in your application kernel:

// app/AppKernel.php
public function registerBundles()
{
	return array(
		// ...
		new VasekPurchart\DoctrineDateTimeImmutableTypesBundle\DoctrineDateTimeImmutableTypesBundle(),
	);
}