bramus / enumeration
Yet Another Enumeration Implementation for PHP
Fund package maintenance!
bramus
Requires
- php: ^7.2
- bramus/reflection: ~1.0
Requires (Dev)
- phpunit/phpunit: ^8.0
README
bramus/enumeration
is an Enumeration Implementation for PHP. It allows one to create both singular enumerations and composed enumerations.
Built by Bram(us) Van Damme (https://www.bram.us) and Contributors
Prerequisites/Requirements
- PHP 7.2 or greater
Installation
Installation is possible using Composer
$ composer require bramus/enumeration ~1.4
Usage
Singular Enumerations
<?php use Bramus\Enumeration\Enumeration; class Weekday extends Enumeration { const MONDAY = 1; const TUESDAY = 2; const WEDNESDAY = 3; const THURSDAY = 4; const FRIDAY = 5; const SATURDAY = 6; const SUNDAY = 7; }
Creating and Playing with Instances
$instance = new Weekday(1); $instance = new Weekday(Weekday::MONDAY); $instance = Weekday::MONDAY();
$instance->getValue(); // ~> 1 $instance->getIdentifier(); // ~> 'MONDAY' (string) $instance; // ~> '1'
Converting between values and identifiers
Weekday::toValue('MONDAY'); // ~> 1 Weekday::toIdentifier(1); // ~> 'MONDAY;
Listing values and identifiers
Weekday::values(); // ~> [1, 2, 3, 4, 5, 6, 7] Weekday::identifiers(); // ~> ['MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY']
Checking values and identifiers
Weekday::isValidValue(2); // ~> true Weekday::isValidValue(8); // ~> false Weekday::isValidIdentifier('TUESDAY'); // ~> true Weekday::isValidIdentifier('SUMMERDAY'); // ~> false
Composed Enumerations
It's also possible to have one Enumeration be composed of several other enumerations
<?php namespace Bramus\Http\StatusCodes; use Bramus\Enumeration\Enumeration; use Bramus\Enumeration\ComposedEnumeration; abstract class Informal extends Enumeration { const CONTINUE = 100; const SWITCHING_PROTOCOLS = 101; const PROCESSING = 102; … } abstract class Success extends Enumeration { const OK = 200; const CREATED = 201; const ACCEPTED = 202; … } abstract class Redirection extends Enumeration { const MULTIPLE_CHOICES = 300; const MOVED_PERMANENTLY = 301; const FOUND = 302; … } abstract class ClientError extends Enumeration { const BAD_REQUEST = 400; const UNAUTHORIZED = 401; const PAYMENT_REQUIRED = 402; … const IM_A_TEAPOT = 418; … } abstract class ServerError extends Enumeration { const INTERNAL_SERVER_ERROR = 500; const NOT_IMPLEMENTED = 501; const BAD_GATEWAY = 502; … const NETWORK_AUTHENTICATION_REQUIRED = 511; } class StatusCode extends ComposedEnumeration { public static $classes = [ '\Bramus\Http\StatusCodes\Informal', '\Bramus\Http\StatusCodes\Success', '\Bramus\Http\StatusCodes\Redirection', '\Bramus\Http\StatusCodes\ClientError', '\Bramus\Http\StatusCodes\ServerError', ]; }
@note: Whilst it is technically possible to re-use the same identifiers and values throughout the classes that make up the composed Enumeration, it is discouraged to do so.
Creating and Playing with Instances
use Bramus\Http\StatusCodes\StatusCode; $instance = new StatusCode(200); // $instance = new StatusCode(StatusCode::OK); <-- This won't work, due to __getStatic not existing in PHP … $instance = StatusCode::OK();
$instance->getValue(); // ~> 200 $instance->getIdentifier(); // ~> 'OK' (string) $instance; // ~> '200'
Converting between values and identifiers
StatusCode::toValue('OK'); // ~> 200 StatusCode::toIdentifier(200); // ~> 'OK;
Listing values and identifiers
StatusCode::values(); // ~> [100, 101, 102, …, 200, 201, 202, …, 511] StatusCode::identifiers(); // ~> ['CONTINUE', 'SWITCHING_PROTOCOLS', 'PROCESSING', …, 'OK', 'CREATED', 'ACCEPTED', …, 'NETWORK_AUTHENTICATION_REQUIRED']
Checking values and identifiers
StatusCode::isValidValue(418); // ~> true StatusCode::isValidValue(700); // ~> false StatusCode::isValidIdentifier('IM_A_TEAPOT'); // ~> true StatusCode::isValidIdentifier('BROKEN'); // ~> false
Default Values
If you want, you can define a default value to use. Define it as a constant named __DEFAULT
on your class and you're good to go:
<?php use Bramus\Enumeration\Enumeration; class Weekday extends Enumeration { const __DEFAULT = 1; const MONDAY = 1; const TUESDAY = 2; … }
The default will be used when no value is passed into the constructor:
$instance = new Weekday(); // object(Weekday)#424 (2) { // ["value":"Bramus\Enumeration\Enumeration":private]=> // int(1) // ["identifier":"Bramus\Enumeration\Enumeration":private]=> // string(6) "MONDAY" //}
This works both for both the Enumeration
and ComposedEnumeration
classes:
class StatusCode extends ComposedEnumeration { const __DEFAULT = 200; public static $classes = [ … ]; }
Summaries and Descriptions
When defining DocBlocks to go with your enumeration constants, you can get its summary and description using the getSummary()
and getDescription()
methods respectively.
<?php use Bramus\Enumeration\Enumeration; class Weekday extends Enumeration { /** * Monday. * * The first day of the week. */ const MONDAY = 1; // }
$instance = new Weekday(1); $instance->getSummary(); // ~> 'Monday.' $instance->getDescription(); // ~> 'The first day of the week.'
Static methods to fetching these are also available. For each their only argument is a valid Enumeration value or a Bramus\Enumeration\Enumeration
instance:
Weekday::toSummary(Weekday::MONDAY); // ~> 'Monday.' Weekday::toSummary($instance); // ~> 'Monday.' Weekday::toDescription(Weekday::MONDAY); // ~> 'The first day of the week.' Weekday::toDescription($instance); // ~> 'The first day of the week.'
It's also possible to get a list of all summaries/descriptions. An array with the Enum values as keys is returned
$summaries = Weekday::summaries(); // ~> [1 => 'Monday.', 2 => 'Tuesday.', …, 7 => 'Sunday.'] $descriptions = Weekday::descriptions(); // ~> [1 => 'The first day of the week', 2 => 'The second day of the week', …, 7 => 'The seventh day of the week']
Comparing Values
To compare a Bramus\Enumeration\Enumeration
instance against a value, use $instance->equals()
$instance = new Weekday(Weekday::MONDAY); $instance->equals(1); // ~> true
Comparing Bramus\Enumeration\Enumeration
instances against other Bramus\Enumeration\Enumeration
is also possible
$instance = new Weekday(Weekday::MONDAY); $otherInstance = Weekday::MONDAY(); $instance->equals($otherInstance); // ~> true
Utility Classes
bramus/enumeration
comes with 2 utility classes. Whilst you most likely don't need to use these directly, they might be of help:
\Bramus\Enumeration\Helpers\Extractor
This class extracts constants/identifiers/values from \Bramus\Enumeration\Enumeration
classes. It is used by \Bramus\Enumeration\Enumeration
internally.
\Bramus\Enumeration\Helpers\Generator
This class allows one to generate instances of \Bramus\Enumeration\Enumeration
classes. Given the example \Bramus\Http\StatusCodes\StatusCode
class from above, its usage might be something like this:
use Bramus\Enumeration\Helpers\Generator; Generator::setNamespace('\\Bramus\\Http\\StatusCodes\\'); Generator::generateStatusCode(); // Generates a \Bramus\Http\StatusCodes\StatusCode instance with its default value Generator::generateStatusCode(404); // Generates a \Bramus\Http\StatusCodes\StatusCode instance with the value 404
@note: In case the Enumeration
has no __DEFAULT
(e.g. it is NULL
), calling Generator::generate*
will return a random value for the Enumeration.
Testing
bramus/enumeration
ships with unit tests using PHPUnit ~8.0
.
- If PHPUnit is installed globally run
phpunit
to run the tests. - If PHPUnit is not installed globally, install it locally throuh composer by running
composer install --dev
. Run the tests themselves by calling./vendor/bin/phpunit
or using the composer scriptcomposer test
$ composer test
License
bramus/enumeration
is released under the MIT public license. See the enclosed LICENSE
for details.