README

Enumeration value object. Enumerate values and behaviour with type-safety.

Repositories gitlab.grifart.cz and github.com.

Sponsored by grifart.com.

Do you like video 📺 instead of reading? Here is one in english and one in czech.

Introduction

Enums represent predefined set of values. The available values are defined statically by each enum class. Each value is represented by an instance of this class in a flyweight manner.

• This enum allows you to add individual behaviour for every enum value (as in Java). This allows you to transform your switches/ifs into more readable composition. (see example bellow)
• Checks enum annotations if phpdoc-declared methods are properly declared (will generate docblock for you when not specified or incorrect)
• ===, == and usage of switches is supported
• string or integer scalar keys are supported
• Easily access scalar value of enum DayOfWeek::MONDAY()->toScalar() or (string) DayOfWeek::MONDAY()

Also includes:

• It is type safe. By annotating your enumeration type, you are guaranteed that there will be no other values then you declared. function translateTo(DayOfWeek $day) { ...
• You can get a list of all the possible values Enum::getAvailableValues()

Installation

composer require grifart/enum

This library uses semantic versioning 2.0. You can safely use ^ constrain in you composer.json.

Requirements

This library requires PHP 7.1 and later.

Project status & release process

While this library is still under development, it is well tested and should be stable enough to use in production environments.

The current releases are numbered 0.x.y. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.), y is incremented.

When a breaking change is introduced, a new 0.x version cycle is always started.

It is therefore safe to lock your project to a given release cycle, such as 0.1.*.

If you need to upgrade to a newer release cycle, check the release history for a list of changes introduced by each further 0.x.0 version.

Overview

Static methods

• fromScalar() - returns enum instance (value) for given scalar
• getAvailableValues() - returns all values for given type
• provideInstances() - implement to return enum instances or automatically implemented by Grifart\Enum\AutoInstances trait.

Instance methods

• toScalar() - return scalar value identifier
• equals() - returns true if the same enum value is passed
• scalarEquals() - returns true if passed scalar value is equal to current value

Simplest enumeration

/**
 * @method static DayOfWeek MONDAY()
 * @method static DayOfWeek TUESDAY()
 */
final class DayOfWeek extends \Grifart\Enum\Enum
{
    use Grifart\Enum\AutoInstances;
    private const MONDAY = 'monday';
    private const TUESDAY = 'tuesday';
}

$monday = DayOfWeek::MONDAY();
function process(DayOfWeek $day): void { /* ... */ }

Values with behaviour

This way conditions can be replaced by composition.

This example originally comes from loyalty program domain, continue to full code sample with context.

/**
 * @method static ExpirationType ASSIGNMENT()
 * @method static ExpirationType FIXED()
 */
abstract class ExpirationType extends \Grifart\Enum\Enum
{
	protected const ASSIGNMENT = 'assignment';
	protected const FIXED = 'fixed';

	abstract public function computeExpiration(Offer $offer): \DateTimeImmutable;

	protected static function provideInstances() : array {
		return [
			new class(self::ASSIGNMENT) extends ExpirationType {
				public function computeExpiration(Offer $offer): \DateTimeImmutable {
					return /* behaviour A */;
				}
			},
			new class(self::FIXED) extends ExpirationType {
				public function computeExpiration(Offer $offer): \DateTimeImmutable {
					return /* behaviour B */;
				}
			},
		];
	}
}

Migrating from class constants [source code]

This guide show how to migrate from classes with constants to \Grifart\Enum in few simple steps. Continue to example

Adding behaviour to values [source code]

This guide show how to slowly add behaviour to enum values. Step by step. Continue to example

Complex showcase: order lifecycle tracking [source code]

This example contains 5 ways of implementing order state. Continue to example.

Big thanks

• David Grudl for making Nette Tester
• Ondřej Mirtes for making PHP Stan.

More reading

• consistence/consistence enum
• myclabs/php-enum
• Java enum (see planet example)
• great talk about "crafting wicked domain models" from Jimmy Bogard
• more my notes on DDD topic