Enums

This package holds a simple class that may be used as an ancestor for your enum classes.

Installation

composer require greg0ire/enum

Usage

Basic usage

Extend the Greg0ire\Enum\AbstractEnum, define your enum key values as constants, and Bob's your uncle. You can make the class abstract or final, as you see fit.

useGreg0ire\Enum\AbstractEnum;
finalclass DaysOfWeek extends AbstractEnum {
constSunday = 0;
constMonday = 1;
constTuesday = 2;
constWednesday = 3;
constThursday = 4;
constFriday = 5;
constSaturday = 6;
}

Then, you may use the DaysOfWeek class for input validation:

DaysOfWeek::isValidName('Humpday'); // false
DaysOfWeek::isValidName('Monday'); // true
DaysOfWeek::isValidName('monday'); // false
DaysOfWeek::isValidName(0); // false
DaysOfWeek::isValidValue(0); // true
DaysOfWeek::isValidValue(5); // true
DaysOfWeek::isValidValue(7); // false
DaysOfWeek::isValidValue('Friday'); // false

Both methods have an assert* counterpart that will throw a Greg0ire\Enum\Exception\InvalidEnumValue exception:

DaysOfWeek::assertValidName(0); // InvalidEnumName
DaysOfWeek::assertValidValue('Friday'); // InvalidEnumValue

Additionally, you may get all the constants in your class as a hash:

DaysOfWeek::getConstants();
DaysOfWeek::getConstants('strtolower'); // Will combine your values with `DaysOfWeek::getKeys($callback)`.
DaysOfWeek::getConstants('strtolower', true); // Values combine with `DaysOfWeek::getClassPrefixedKeys($callback)`.
DaysOfWeek::getConstants('strtolower', true, '.'); // Same with `DaysOfWeek::getClassPrefixedKeys($callback, $separator)`.

You may also get all the keys in your class as an array:

DaysOfWeek::getKeys();
DaysOfWeek::getKeys('strtolower'); // Will call `array_map` with the given callback.

Or the key with the enum class prefix:

DaysOfWeek::getClassPrefixedKeys();
DaysOfWeek::getClassPrefixedKeys('strtolower'); // Will call `array_map` with the given callback.
DaysOfWeek::getClassPrefixedKeys('strtolower', '.'); // Replace the namespace separator ('_' by default).

If you would like to get the keys from a value:

$key = DaysOfWeek::getKeysFromValue(1); // Monday will be assigned to $key

If you have many keys with the same value you will get an array, and a value otherwise.

Advanced usage

If you need to get the constants from a class you cannot modify, or from an interface, or even from several classes / interfaces, you may override AbstractEnum::getEnumTypes().

For example, if you have the following class and interface :

namespaceVendor\Namespace;
class ClassFromAVendor
{
constSOMETHING = 'something';
constSOMETHING_ELSE = 'something_else';
}

namespaceMy\Namespace;
interface SomeInterface
{
constANOTHER_CONST = 'another_const';
}

You can get all three constants by creating this Enum :

useGreg0ire\Enum\AbstractEnum;
useMy\Namespace\SomeInterface;
useVendor\Namespace\ClassFromAVendor;
finalclass MyEnum extends AbstractEnum
{
protectedstaticfunctiongetEnumTypes()
{
return [ClassFromAVendor::class, SomeInterface::class];
}
}

Alternatively, you can specify a prefix for each type to avoid getting FQCNs in the hash keys.

useGreg0ire\Enum\AbstractEnum;
useMy\Namespace\SomeInterface;
useVendor\Namespace\ClassFromAVendor;
finalclass MyEnum extends AbstractEnum
{
protectedstaticfunctiongetEnumTypes()
{
return [
'prefix1' => ClassFromAVendor::class,
'prefix2' => SomeInterface::class,
];
}
}

Get label from a service

If you want to get the constant label behind an enum value, you can instantiate the GetLabel class and invoke it.

useGreg0ire\Enum\Bridge\Symfony\Translator\GetLabel;
$label = newGetLabel();
$label(Your\Enum\Class::VALUE, Your\Enum\Class::class);

To enable translation, require the symfony/translation component and pass a Symfony\Contracts\Translation\TranslationInterface instance on the GetLabel constructor

useGreg0ire\Enum\Bridge\Symfony\Translator\GetLabel;
useSymfony\Contracts\Translation\TranslationInterface;
$label = newGetLabel($translator);
$label(Your\Enum\Class::VALUE, Your\Enum\Class::class);

If you're using Symfony, alias the service and simply inject it. If translations are enabled, the TranslatorInterface will be automatically injected.

services:
# ...Greg0ire\Enum\Bridge\Symfony\Translator\GetLabel: "@greg0ire_enum.symfony.translator.get_label"

publicfunctionindex(GetLabel$label)
{
$label(Your\Enum\Class::VALUE, Your\Enum\Class::class);
$label(Your\Enum\Class::VALUE, Your\Enum\Class::class, 'another_domain'); // Change the translation domain$label(Your\Enum\Class::VALUE, Your\Enum\Class::class, false); // Disable translation. In this case the class prefix wont be added$label(Your\Enum\Class::VALUE, Your\Enum\Class::class, false, true); // Disable translation but keep class prefix$label(Your\Enum\Class::VALUE, Your\Enum\Class::class, false, true, '.'); // Disable translation but keep class prefix with a custom separator
}

Integration with other libraries

greg0ire/enum integrates with other libraries. The list is available in the suggest section of the Composer dependency manifest.

Symfony validator

This package provides a "ready to use" symfony validator. You have to require the symfony/validator package to get it working.

useGreg0ire\Enum\Bridge\Symfony\Validator\Constraint\Enum;
useSymfony\Component\Validator\Validation;
useYour\Namespace\EnumClass;
$validator = Validation::createValidator();
$violations = $validator->validateValue(42, newEnum(EnumClass::class));
// You can also show the constants keys on the error message:$violations = $validator->validateValue(42, newEnum(['class' => EnumClass::class, 'showKeys' => true]));
// Enum constraint inherits from Choice constraint. You can use inherited options too:$violations = $validator->validateValue(42, newEnum(['class' => EnumClass::class, 'strict' => true]));

Another example with annotations:

useDoctrine\Common\Annotations\AnnotationRegistry;
useGreg0ire\Enum\Bridge\Symfony\Validator\Constraint\EnumasEnumAssert;
useSymfony\Component\Validator\Validation;
class MyClass
{
/** * @EnumAssert("Your\Namespace\EnumClass") */private$dummy;
publicfunction__construct($dummy)
{
$this->dummy = $dummy
}
}
AnnotationRegistry::registerLoader('class_exists');
$validator = Validation::createValidatorBuilder()
->enableAnnotationMapping()
->getValidator();
$object = newMyClass(42);
$violations = $validator->validate($object);

Note: You will have to get doctrine/annotations and doctrine/cache packages to get it working.

Symfony form

This package provides a "ready to use" symfony form type. You have to require the symfony/form package to get it working.

useGreg0ire\Enum\Bridge\Symfony\Form\Type\EnumType;
useSymfony\Component\Form\Forms;
useYour\Namespace\EnumClass;
$formFactory = Forms::createFormFactory();
$view = $this->factory->create(EnumType::class, null, array(
'class' => EnumClass::class,
))->createView();

Twig extension

This package comes with an EnumExtension Twig class. It contains a filter and some functions. You have to require the twig/twig package to get it working.

Filter

The enum_label filter will try to return the constant label corresponding to the given value.

This filter relies on the Greg0ire\Enum\Bridge\Symfony\Translator\GetLabel service.

It will try to translate it if possible. To enable translation, require the symfony/translation component and pass a Symfony\Contracts\Translation\TranslationInterface instance on the GetLabel constructor. GetLabel instance will be injected on the EnumExtension constructor.

If translation is not available, you will have the default label with class prefixing.

Usage:

{{ value|enum_label('Your\\Enum\\Class') }}
{{ value|enum_label('Your\\Enum\\Class', 'another_domain') }} {# Change the translation domain #}
{{ value|enum_label('Your\\Enum\\Class', false) }} {# Disable translation. In this case the class prefix wont be added #}
{{ value|enum_label('Your\\Enum\\Class', false, true) }} {# Disable translation but keep class prefix #}
{{ value|enum_label('Your\\Enum\\Class', false, true, '.') }} {# Disable translation but keep class prefix with a custom separator #}

Functions

The 3 available twig functions are ports of some AbstractEnum methods that can be useful in a twig template:

• enum_get_constants => AbstractEnum::getConstants
• enum_get_keys => AbstractEnum::getKeys
• enum_get_class_prefixed_keys => AbstractEnum::getClassPrefixedKeys

The arguments are exactly the same except you have to specify the targeted class first (as enum_label filter).

Here is a concrete example with enum_get_constants function:

{% forenum_key, enum_valuein enum_get_constants('Your\\Enum\\Class') %}
{{ enum_key }} -> {{ enum_value }}
{% endfor %}

Twig extension as a service

On Symfony projects, the extension can be autoloaded. First, you have to require the symfony/framework-bundle and symfony/twig-bundle packages, or use Symfony fullstack.

Then, register the bundle in the kernel of your application:

// app/AppKernel.phppublicfunctionregisterBundles()
{
$bundles = [
// ...newGreg0ire\Enum\Bridge\Symfony\Bundle\Greg0ireEnumBundle(),
];
// ...return$bundles
}

That's all. You can now directly use the filter.

Contributing

see CONTRIBUTING.md

Credits

This is a shameless rip-off of this Stack Overflow answer, with one modification: the getConstants method has been made public so that it is available for building choice widgets, for instance. If you want to give credit to someone for this, give it to Brian Cline