{"id":18887671,"url":"https://github.com/bramus/enumeration","last_synced_at":"2025-04-14T22:34:07.055Z","repository":{"id":62496634,"uuid":"180599750","full_name":"bramus/enumeration","owner":"bramus","description":"Yet Another Enumeration Implementation for PHP","archived":false,"fork":false,"pushed_at":"2021-12-07T21:59:19.000Z","size":44,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T10:54:22.955Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.bram.us/2019/04/12/bramus-enumeration-a-package-to-work-with-enumerations-in-php/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bramus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-10T14:30:15.000Z","updated_at":"2025-01-16T07:23:20.000Z","dependencies_parsed_at":"2022-11-02T09:46:00.755Z","dependency_job_id":null,"html_url":"https://github.com/bramus/enumeration","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fenumeration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fenumeration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fenumeration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fenumeration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bramus","download_url":"https://codeload.github.com/bramus/enumeration/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248973331,"owners_count":21191944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T07:38:54.038Z","updated_at":"2025-04-14T22:34:02.033Z","avatar_url":"https://github.com/bramus.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `bramus/enumeration`\n\n[![Build Status](https://github.com/bramus/enumeration/workflows/CI/badge.svg)](https://github.com/bramus/enumeration/actions) [![Source](http://img.shields.io/badge/source-bramus/enumeration-blue.svg?style=flat-square)](https://github.com/bramus/enumeration) [![Version](https://img.shields.io/packagist/v/bramus/enumeration.svg?style=flat-square)](https://packagist.org/packages/bramus/enumeration) [![Downloads](https://img.shields.io/packagist/dt/bramus/enumeration.svg?style=flat-square)](https://packagist.org/packages/bramus/enumeration/stats) [![License](https://img.shields.io/packagist/l/bramus/enumeration.svg?style=flat-square)](https://github.com/bramus/enumeration/blob/master/LICENSE)\n\n`bramus/enumeration` is an Enumeration Implementation for PHP. It allows one to create both [singular enumerations](#singular-enumerations) and [composed enumerations](#composed-enumerations).\n\nBuilt by Bram(us) Van Damme _([https://www.bram.us](https://www.bram.us))_ and [Contributors](https://github.com/bramus/enumeration/graphs/contributors)\n\n## Prerequisites/Requirements\n\n- PHP 7.2 or greater\n\n## Installation\n\nInstallation is possible using Composer\n\n```\n$ composer require bramus/enumeration ~1.4\n```\n\n## Usage\n\n### Singular Enumerations\n\n```php\n\u003c?php\n\nuse Bramus\\Enumeration\\Enumeration;\n\nclass Weekday extends Enumeration\n{\n\tconst MONDAY = 1;\n\tconst TUESDAY = 2;\n\tconst WEDNESDAY = 3;\n\tconst THURSDAY = 4;\n\tconst FRIDAY = 5;\n\tconst SATURDAY = 6;\n\tconst SUNDAY = 7;\n}\n```\n\n#### Creating and Playing with Instances\n\n```php\n$instance = new Weekday(1);\n$instance = new Weekday(Weekday::MONDAY);\n$instance = Weekday::MONDAY();\n```\n\n```php\n$instance-\u003egetValue();\n// ~\u003e 1\n\n$instance-\u003egetIdentifier();\n// ~\u003e 'MONDAY'\n\n(string) $instance;\n// ~\u003e '1'\n```\n\n#### Converting between values and identifiers\n\n```php\nWeekday::toValue('MONDAY');\n// ~\u003e 1\n\nWeekday::toIdentifier(1);\n// ~\u003e 'MONDAY;\n```\n\n#### Listing values and identifiers\n\n```php\nWeekday::values();\n// ~\u003e [1, 2, 3, 4, 5, 6, 7]\n\nWeekday::identifiers();\n// ~\u003e ['MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY']\n```\n\n#### Checking values and identifiers\n\n```php\nWeekday::isValidValue(2);\n// ~\u003e true\n\nWeekday::isValidValue(8);\n// ~\u003e false\n\nWeekday::isValidIdentifier('TUESDAY');\n// ~\u003e true\n\nWeekday::isValidIdentifier('SUMMERDAY');\n// ~\u003e false\n```\n\n### Composed Enumerations\n\nIt's also possible to have one Enumeration be composed of several other enumerations\n\n```php\n\u003c?php\n\nnamespace Bramus\\Http\\StatusCodes;\n\nuse Bramus\\Enumeration\\Enumeration;\nuse Bramus\\Enumeration\\ComposedEnumeration;\n\nabstract class Informal extends Enumeration\n{\n\tconst CONTINUE = 100;\n\tconst SWITCHING_PROTOCOLS = 101;\n\tconst PROCESSING = 102;\n\t…\n}\n\nabstract class Success extends Enumeration\n{\n\tconst OK = 200;\n\tconst CREATED = 201;\n\tconst ACCEPTED = 202;\n\t…\n}\n\nabstract class Redirection extends Enumeration\n{\n\tconst MULTIPLE_CHOICES = 300;\n\tconst MOVED_PERMANENTLY = 301;\n\tconst FOUND = 302;\n\t…\n}\n\nabstract class ClientError extends Enumeration\n{\n\tconst BAD_REQUEST = 400;\n\tconst UNAUTHORIZED = 401;\n\tconst PAYMENT_REQUIRED = 402;\n\t…\n\tconst IM_A_TEAPOT = 418;\n\t…\n}\n\nabstract class ServerError extends Enumeration\n{\n\tconst INTERNAL_SERVER_ERROR = 500;\n\tconst NOT_IMPLEMENTED = 501;\n\tconst BAD_GATEWAY = 502;\n\t…\n\tconst NETWORK_AUTHENTICATION_REQUIRED = 511;\n}\n\nclass StatusCode extends ComposedEnumeration\n{\n\tpublic static $classes = [\n\t\t'\\Bramus\\Http\\StatusCodes\\Informal',\n\t\t'\\Bramus\\Http\\StatusCodes\\Success',\n\t\t'\\Bramus\\Http\\StatusCodes\\Redirection',\n\t\t'\\Bramus\\Http\\StatusCodes\\ClientError',\n\t\t'\\Bramus\\Http\\StatusCodes\\ServerError',\n\t];\n}\n```\n\n@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.\n\n#### Creating and Playing with Instances\n\n```php\nuse Bramus\\Http\\StatusCodes\\StatusCode;\n\n$instance = new StatusCode(200);\n// $instance = new StatusCode(StatusCode::OK); \u003c-- This won't work, due to __getStatic not existing in PHP …\n$instance = StatusCode::OK();\n```\n\n```php\n$instance-\u003egetValue();\n// ~\u003e 200\n\n$instance-\u003egetIdentifier();\n// ~\u003e 'OK'\n\n(string) $instance;\n// ~\u003e '200'\n```\n\n#### Converting between values and identifiers\n\n```php\nStatusCode::toValue('OK');\n// ~\u003e 200\n\nStatusCode::toIdentifier(200);\n// ~\u003e 'OK;\n```\n\n#### Listing values and identifiers\n\n```php\nStatusCode::values();\n// ~\u003e [100, 101, 102, …, 200, 201, 202, …, 511]\n\nStatusCode::identifiers();\n// ~\u003e ['CONTINUE', 'SWITCHING_PROTOCOLS', 'PROCESSING', …, 'OK', 'CREATED', 'ACCEPTED', …, 'NETWORK_AUTHENTICATION_REQUIRED']\n```\n\n#### Checking values and identifiers\n\n```php\nStatusCode::isValidValue(418);\n// ~\u003e true\n\nStatusCode::isValidValue(700);\n// ~\u003e false\n\nStatusCode::isValidIdentifier('IM_A_TEAPOT');\n// ~\u003e true\n\nStatusCode::isValidIdentifier('BROKEN');\n// ~\u003e false\n```\n\n### Default Values\n\nIf 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:\n\n```php\n\u003c?php\n\nuse Bramus\\Enumeration\\Enumeration;\n\nclass Weekday extends Enumeration\n{\n\tconst __DEFAULT = 1;\n\n\tconst MONDAY = 1;\n\tconst TUESDAY = 2;\n\t…\n}\n```\n\nThe default will be used when no value is passed into the constructor:\n\n```php\n$instance = new Weekday();\n\n// object(Weekday)#424 (2) {\n//  [\"value\":\"Bramus\\Enumeration\\Enumeration\":private]=\u003e\n//  int(1)\n//  [\"identifier\":\"Bramus\\Enumeration\\Enumeration\":private]=\u003e\n//  string(6) \"MONDAY\"\n//}\n```\n\nThis works both for both the `Enumeration` and `ComposedEnumeration` classes:\n\n```php\nclass StatusCode extends ComposedEnumeration\n{\n\tconst __DEFAULT = 200;\n\n\tpublic static $classes = [\n\t\t…\n\t];\n}\n```\n\n### Summaries and Descriptions\n\nWhen 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.\n\n```php\n\u003c?php\n\nuse Bramus\\Enumeration\\Enumeration;\n\nclass Weekday extends Enumeration\n{\n\t/**\n\t * Monday.\n\t *\n\t * The first day of the week.\n\t */\n\tconst MONDAY = 1;\n\n\t//\n}\n```\n\n```php\n$instance = new Weekday(1);\n\n$instance-\u003egetSummary();\n// ~\u003e 'Monday.'\n\n$instance-\u003egetDescription();\n// ~\u003e 'The first day of the week.'\n```\n\nStatic methods to fetching these are also available. For each their only argument is a valid Enumeration value or a `Bramus\\Enumeration\\Enumeration` instance:\n\n```php\nWeekday::toSummary(Weekday::MONDAY);\n// ~\u003e 'Monday.'\n\nWeekday::toSummary($instance);\n// ~\u003e 'Monday.'\n\nWeekday::toDescription(Weekday::MONDAY);\n// ~\u003e 'The first day of the week.'\n\nWeekday::toDescription($instance);\n// ~\u003e 'The first day of the week.'\n```\n\nIt's also possible to get a list of all summaries/descriptions. An array with the Enum values as keys is returned\n\n```php\n$summaries = Weekday::summaries();\n// ~\u003e [1 =\u003e 'Monday.', 2 =\u003e 'Tuesday.', …, 7 =\u003e 'Sunday.']\n\n$descriptions = Weekday::descriptions();\n// ~\u003e [1 =\u003e 'The first day of the week', 2 =\u003e 'The second day of the week', …, 7 =\u003e 'The seventh day of the week']\n```\n\n## Comparing Values\n\nTo compare a `Bramus\\Enumeration\\Enumeration` instance against a value, use `$instance-\u003eequals()`\n\n```php\n$instance = new Weekday(Weekday::MONDAY);\n\n$instance-\u003eequals(1);\n// ~\u003e true\n```\n\nComparing `Bramus\\Enumeration\\Enumeration` instances against other `Bramus\\Enumeration\\Enumeration` is also possible\n\n```php\n$instance = new Weekday(Weekday::MONDAY);\n$otherInstance = Weekday::MONDAY();\n\n$instance-\u003eequals($otherInstance);\n// ~\u003e true\n```\n\n## Utility Classes\n\n`bramus/enumeration` comes with 2 utility classes. Whilst you most likely don't need to use these directly, they might be of help:\n\n### `\\Bramus\\Enumeration\\Helpers\\Extractor`\n\nThis class extracts constants/identifiers/values from `\\Bramus\\Enumeration\\Enumeration` classes. It is used by `\\Bramus\\Enumeration\\Enumeration` internally.\n\n### `\\Bramus\\Enumeration\\Helpers\\Generator`\n\nThis 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:\n\n```php\nuse Bramus\\Enumeration\\Helpers\\Generator;\n\nGenerator::setNamespace('\\\\Bramus\\\\Http\\\\StatusCodes\\\\');\n\nGenerator::generateStatusCode(); // Generates a \\Bramus\\Http\\StatusCodes\\StatusCode instance with its default value\nGenerator::generateStatusCode(404); // Generates a \\Bramus\\Http\\StatusCodes\\StatusCode instance with the value 404\n```\n\n@note: In case the `Enumeration` has no `__DEFAULT` _(e.g. it is `NULL`)_, calling `Generator::generate*` will return a random value for the Enumeration.\n\n## Testing\n\n`bramus/enumeration` ships with unit tests using [PHPUnit](https://github.com/sebastianbergmann/phpunit/) `~8.0`.\n\n- If PHPUnit is installed globally run `phpunit` to run the tests.\n- 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`\n\n```\n$ composer test\n```\n\n## License\n\n`bramus/enumeration` is released under the MIT public license. See the enclosed `LICENSE` for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbramus%2Fenumeration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbramus%2Fenumeration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbramus%2Fenumeration/lists"}