Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bramus/enumeration
Yet Another Enumeration Implementation for PHP
https://github.com/bramus/enumeration
Last synced: about 2 months ago
JSON representation
Yet Another Enumeration Implementation for PHP
- Host: GitHub
- URL: https://github.com/bramus/enumeration
- Owner: bramus
- License: mit
- Created: 2019-04-10T14:30:15.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-12-07T21:59:19.000Z (about 3 years ago)
- Last Synced: 2024-09-13T04:48:58.912Z (4 months ago)
- Language: PHP
- Homepage: https://www.bram.us/2019/04/12/bramus-enumeration-a-package-to-work-with-enumerations-in-php/
- Size: 43 KB
- Stars: 5
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# `bramus/enumeration`
[](https://github.com/bramus/enumeration/actions) [](https://github.com/bramus/enumeration) [](https://packagist.org/packages/bramus/enumeration) [](https://packagist.org/packages/bramus/enumeration/stats) [](https://github.com/bramus/enumeration/blob/master/LICENSE)
`bramus/enumeration` is an Enumeration Implementation for PHP. It allows one to create both [singular enumerations](#singular-enumerations) and [composed enumerations](#composed-enumerations).
Built by Bram(us) Van Damme _([https://www.bram.us](https://www.bram.us))_ and [Contributors](https://github.com/bramus/enumeration/graphs/contributors)
## Prerequisites/Requirements
- PHP 7.2 or greater
## Installation
Installation is possible using Composer
```
$ composer require bramus/enumeration ~1.4
```
## Usage
### Singular Enumerations
```php
getValue();
// ~> 1
$instance->getIdentifier();
// ~> 'MONDAY'
(string) $instance;
// ~> '1'
```
#### Converting between values and identifiers
```php
Weekday::toValue('MONDAY');
// ~> 1
Weekday::toIdentifier(1);
// ~> 'MONDAY;
```
#### Listing values and identifiers
```php
Weekday::values();
// ~> [1, 2, 3, 4, 5, 6, 7]
Weekday::identifiers();
// ~> ['MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY']
```
#### Checking values and identifiers
```php
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
getValue();
// ~> 200
$instance->getIdentifier();
// ~> 'OK'
(string) $instance;
// ~> '200'
```
#### Converting between values and identifiers
```php
StatusCode::toValue('OK');
// ~> 200
StatusCode::toIdentifier(200);
// ~> 'OK;
```
#### Listing values and identifiers
```php
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
```php
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
// int(1)
// ["identifier":"Bramus\Enumeration\Enumeration":private]=>
// string(6) "MONDAY"
//}
```
This works both for both the `Enumeration` and `ComposedEnumeration` classes:
```php
class StatusCode extends ComposedEnumeration
{
const __DEFAULT = 200;
public static $classes = [
…
];
}
```
### Summaries and Descriptions
When defining [DocBlocks](https://docs.phpdoc.org/references/phpdoc/basic-syntax.html) to go with your enumeration constants, you can get its summary and description using the `getSummary()` and `getDescription()` methods respectively.
```php
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:
```php
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
```php
$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()`
```php
$instance = new Weekday(Weekday::MONDAY);
$instance->equals(1);
// ~> true
```
Comparing `Bramus\Enumeration\Enumeration` instances against other `Bramus\Enumeration\Enumeration` is also possible
```php
$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:
```php
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](https://github.com/sebastianbergmann/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.