bramus/enumeration

Yet Another Enumeration Implementation for PHP

1.4 2020-12-10 14:34 UTC

Requires

• php: ^7.2
• bramus/reflection: ~1.0

Requires (Dev)

• phpunit/phpunit: ^8.0

MIT

• Bramus

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 script composer test

$ composer test

License

bramus/enumeration is released under the MIT public license. See the enclosed LICENSE for details.