consistence-community / consistence-doctrine
Integration of Consistence library with Doctrine ORM
Installs: 306 613
Dependents: 2
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 9
Open Issues: 0
Requires
- php: ~7.4 || ~8.0
- consistence-community/consistence: ~2.1
- doctrine/annotations: ~1.7 || ^2.0
- doctrine/orm: ^2.10.0
Requires (Dev)
- consistence-community/coding-standard: 3.11.1
- doctrine/cache: ^1.11
- doctrine/persistence: ^1.3.5 || ^2.0
- phing/phing: 2.17.0
- php-parallel-lint/php-parallel-lint: 1.3.1
- phpunit/phpunit: 9.5.10
Replaces
README
This package is a fork of consistence/consistence-doctrine
maintained by community to support new PHP versions.
This library provides integration of Consistence value objects for Doctrine ORM so that you can use them in your entities.
For now, the only integration which is needed is for Enums, see the examples below.
Usage
Enums represent predefined set of values and of course, you will want to store these values in your database as well. Since Enums
are objects and you only want to store the represented value, there has to be some mapping.
You can see it in this example where you want to store sex for your User
s:
<?php namespace Consistence\Doctrine\Example\User; class Sex extends \Consistence\Enum\Enum { public const FEMALE = 'female'; public const MALE = 'male'; }
Now you can use the Sex
enum in your User
entity. There are two important things to notice:
type="string_enum"
inORM\Column
- this will be used for mapping the value to your database, that means if you have a string based enum (see values inSex
), usestring_enum
You can specify any other parameters for ORM\Column
as you would usually (nullability, length...).
There is also integer_enum
, float_enum
and boolean_enum
which can be used respectively for their types.
@Enum(class=Sex::class)
- this will be used for reconstructing theSex
enum object when loading the value back from database
The class
annotation parameter uses the same namespace resolution process as other Doctrine annotations, so it is practically the same as when you specify a targetEntity
in associations mapping.
<?php namespace Consistence\Doctrine\Example\User; use Consistence\Doctrine\Enum\EnumAnnotation as Enum; use Doctrine\ORM\Mapping as ORM; /** * @ORM\Entity() */ class User extends \Consistence\ObjectPrototype { // ... /** * @Enum(class=Sex::class) * @ORM\Column(type="string_enum", nullable=true) * @var \Consistence\Doctrine\Example\User\Sex|null */ private $sex; // ... public function __construct( // ... Sex $sex = null // ... ) { // ... $this->sex = $sex; // ... } // ... }
Now everything is ready to be used, when you call flush
, only female
will be saved:
<?php namespace Consistence\Doctrine\Example\User; $user = new User( // ... Sex::get(Sex::FEMALE) // ... ); /** @var \Doctrine\ORM\EntityManager $entityManager */ $entityManager->persist($user); // when persisting User::$sex to database, `female` will be saved $entityManager->flush();
And when you retrieve the entity back from database, you will receive the Sex
enum object again:
<?php namespace Consistence\Doctrine\Example\User; /** @var \Doctrine\ORM\EntityManager $entityManager */ $user = $entityManager->find(User::class, 1); var_dump($user->getSex()); /* class Consistence\Doctrine\Example\User\Sex#5740 (1) { private $value => string(6) "female" } */
This means that the objects API is symmetrical (you get the same type as you set) and you can start benefiting from Enums advantages such as being sure, that what you get is already a valid value and having the possibility to define methods on top of the represented values.
Installation
If you are using Symfony, you can use
consistence-community/consistence-doctrine-symfony
, which will take care of the integration.
- Install package
consistence-community/consistence-doctrine
with Composer:
composer require consistence-community/consistence-doctrine
- Register Doctrine DBAL types and annotations:
<?php use Consistence\Doctrine\Enum\Type\BooleanEnumType; use Consistence\Doctrine\Enum\Type\FloatEnumType; use Consistence\Doctrine\Enum\Type\IntegerEnumType; use Consistence\Doctrine\Enum\Type\StringEnumType; use Doctrine\Common\Annotations\AnnotationRegistry; use Doctrine\DBAL\Types\Type as DoctrineType; // path to your Composer autoload file $loader = require __DIR__ . '/../vendor/autoload.php'; // register loading of custom annotations // if you are already using Doctrine annotations you probably won't need this AnnotationRegistry::registerLoader([$loader, 'loadClass']); // register Doctrine DBAL types DoctrineType::addType(BooleanEnumType::NAME, BooleanEnumType::class); // boolean_enum DoctrineType::addType(FloatEnumType::NAME, FloatEnumType::class); // float_enum DoctrineType::addType(IntegerEnumType::NAME, IntegerEnumType::class); // integer_enum DoctrineType::addType(StringEnumType::NAME, StringEnumType::class); // string_enum
This step contains static call which have global effect, so I recommend putting them inside a bootstrap file (usually where you register the Composer autoloader now), which is run or included when the application starts.
If you are already using Doctrine annotations, the AnnotationRegistry::registerLoader()
might already be called somewhere in your application, so check that before adding it.
You need to register EnumPostLoadEntityListener
, which needs \Doctrine\Common\Annotations\Reader
. If you are using annotations Doctrine mapping, then you can use the same reader this way:
<?php use Consistence\Doctrine\Enum\EnumPostLoadEntityListener; use Doctrine\Common\Cache\ArrayCache; use Doctrine\ORM\Events; /** @var \Doctrine\ORM\EntityManager $entityManager */ /** @var \Doctrine\ORM\Mapping\Driver\AnnotationDriver $annotationDriver */ $annotationDriver = $entityManager->getConfiguration()->getMetadataDriverImpl(); $annotationReader = $annotationDriver->getReader(); // make sure to use the most appropriate cache for given environment to get the best performance $cache = new ArrayCache(); $entityManager->getEventManager()->addEventListener( Events::postLoad, new EnumPostLoadEntityListener($annotationReader, $cache) );
If not, just create a new instance and pass it to the constructor.
That's all, you are good to go!