grifart / enum
Provides bullet proof enums with behaviours.
Installs: 188 075
Dependents: 2
Suggesters: 0
Security: 0
Stars: 23
Watchers: 5
Forks: 3
Open Issues: 3
Requires
- php: >=7.1.0
Requires (Dev)
- grifart/phpstan-oneline: ^0.2.0
- nette/tester: ^2.1.0
- phpstan/phpstan: ^0.10.7
- phpstan/phpstan-strict-rules: ^0.10.1
This package is auto-updated.
Last update: 2024-10-13 13:38:14 UTC
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
switch
es/if
s 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 ofswitch
es 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.