doctrineum/scalar

Enumeration types and value dependent sub-types for Doctrine

4.0.0 2019-02-13 08:42 UTC

Requires

• php: >=7.1
• doctrine/dbal: ~2.4
• doctrineum/self-registering-type: ~2.1
• granam/scalar-enum: ~1.0
• granam/tools: ^3.0

Requires (Dev)

• granam/exceptions-hierarchy: ~4.0
• mockery/mockery: ~1.0
• phpunit/phpunit: ~7.0
• roave/security-advisories: dev-master

MIT

• Jaroslav Týc

• doctrine
• enum
• sub-type
• value-dependent enum
• self-typed enum

README

Customizable enumeration type for Doctrine 2.4+

About custom Doctrine types, see the official documentation. For default types see the official documentation as well.

Usage

1. Installation
2. Custom type registration
3. Map property as an enum
4. Create enum
5. Register subtype enum
6. NULL is NULL, not Enum
7. Understand the basics
8. Exceptions philosophy

Installation

composer.phar require doctrineum/scalar

or manually edit composer.json at your project and "require": block (extend existing)

    "require": {
        "doctrineum/scalar": "dev-master"
    }

Custom type registration

By helper method

ScalarEnum::registerSelf(); // quick self-registration

Or manually using "magic" class::class constant

use Doctrineum\Scalar\ScalarEnumType;
// ...
Type::addType(ScalarEnumType::getTypeName(), ScalarEnumType::class);
Type::addType(BarScalarEnumType::getTypeName(), BarScalarEnumType::class);

Or manually by old fashion way

<?php
// in bootstrapping code
// ...
use Doctrine\DBAL\Types\Type;
use Doctrineum\Scalar\ScalarEnumType;
// ...
// Register type
Type::addType(ScalarEnumType::getTypeName(), '\Doctrineum\ScalarEnumType');
Type::addType(BarScalarEnumType::getTypeName(), '\Foo\BarScalarEnumType');

Or if your project uses Symfony2

# app/config/config.yml
doctrine:
    dbal:
        # ...
        types:
            scalar_enum: Doctrineum\Scalar\ScalarEnumType
            bar: Foo\BarScalarEnumType
            #...

Map property as an enum

<?php
class Foo
{
    /** @Column(type="scalar_enum") */
    protected $field;
}

Create enum

<?php
use Doctrineum\Scalar\ScalarEnum;
$enum = ScalarEnum::getEnum('foo bar');

Register subtype enum

You can register infinite number of enums, which are built according to a regexp of your choice.

<?php
use Doctrineum\Scalar\ScalarEnumType;
ScalarEnumType::addSubTypeEnum('\Foo\Bar\YourSubTypeEnum', '~get me different enum for this value~');
// ...
$enum = $ScalarEnumType->convertToPHPValue('foo');
get_class($enum) === '\Doctrineum\Scalar\ScalarEnum'; // true
get_class($enum) === '\Foo\Bar\YourSubTypeEnum'; // false
$byRegexpDeterminedEnum = $ScalarEnumType->convertToPHPValue('And now get me different enum for this value.');
get_class($byRegexpDeterminedEnum) === '\Foo\Bar\YourSubTypeEnum'; // true

NULL is NULL, Enum can not hold it

You can not create ScalarEnum with NULL value. Just use NULL directly for such column value.

Beware on using subtypes only when main enum is an abstract class. You have to resolve from-database-NULL->to-PHP-value conversion, or register subtype explicitly for NULL value (empty string respectively), otherwise fatal error by abstract class instance creation occurs.

Understand the basics

There are two roles - the factory and the value.

• ScalarEnumType is the factory (as part of the Doctrine\DBAL\Types\Type family), building an ScalarEnum by following ScalarEnumType rules.
• ScalarEnum is the value holder, de facto singleton, represented by a class. And class, as you know, can do a lot of things, which makes enum more sexy then whole scalar value.
• Subtype is an ScalarEnumType, but ruled not just by type, but also by current value itself. One type can has any number of subtypes, in dependence on your imagination and used enum values.

Exceptions philosophy

Doctrineum adopts Granam exception hierarchy ideas. That means every exceptionable state is probably by a logic mistake, rather than a runtime situation.