Enum PHP Library

Overview

This library provides an Enum / Enumeration implementation for PHP.

Why use this library

Very simple to implement and use.
Complex can optionally be mapped by providing a map() method.
Allows type-hinting when passing enumerated values between methods and classes.

Usage

First create a new class that extends \Rexlabs\Enum\Enum and do the following;

Declare your constants
Optional: provide a map() method:

Example

<?php

class City extends \Rexlabs\Enum\Enum
{
    const BRISBANE = 'Brisbane';
    const MELBOURNE = 'Melbourne';
    const SYDNEY = 'Sydney';
    
    // OPTIONAL - Provide a map() method if you would like to
    // map additional data, which will be available from the ->value() method
    public static function map(): array 
    {
        return [
            static::BRISBANE => ["state"=>"QLD", "population"=>""],
            static::MELBOURNE => ["state"=>"VIC", "population"=>"5m"],
            static::SYDNEY => ["state"=>"NSW", "population"=>"5m"],
        ];
    }
    
}

// Static access
echo City::BRISBANE;                 // "Brisbane"
echo City::MELBOURNE;                // "Melbourne"
City::names();                       // (array)["BRISBANE", "BRISBANE", "SYDNEY"]
City::keys();                        // (array)["Brisbane", "Melbourne", "Sydney"]
City::keyForName('BRISBANE');        // "Brisbane"
City::nameForKey('Melbourne');       // "MELBOURNE"
City::isValidKey('Sydney');          // (boolean)true
City::isValidKey('Paris');           // (boolean)false
               
// Getting an instance - all return a City instance.
$city = City::BRISBANE();                   
$city = City::instanceFromName('BRISBANE'); 
$city = City::instanceFromKey('Brisbane');

// Working with an instance
$city->name();                       // "BRISBANE"
$city->key();                        // "Brisbane"
$city->value()['population'];        // null - no value mapped
$city->is(City::BRISBANE);           // (boolean)true
$city->is(City::BRISBANE());         // (boolean)true
$city->is(City::SYDNEY());           // (boolean)false

// Or ...
City::SYDNEY()->key();               // "Sydney"
City::SYDNEY()->value();             // (array)["state"=>"NSW", "population"=>"5m"]

Dependencies

PHP 7.0 or above.

Installation

To install in your project:

composer require rexlabs/enum

Type-hinting

Now you can type-hint your Enum object as a dependency:

<?php
function announceCity(City $city) {
    echo "{$city->key()} is located in {$city->value()["state"]}, population: {$city->value()["population"]}\n";
}

// Get a new instance
announceCity(City::SYDNEY());      // "Sydney is located in NSW, population: 5m"

Instance Methods

Each instance of Enum provides the following methods:

name()

Returns the constant name.

$enum->name();

key()

Returns the value/key assigned to the constant in the const MY_CONST = 'key' declaration.

$enum->key();

value()

Returns the value (if-any) that is mapped (in the array returned by map()). If no value is mapped, then this method returns null.

$enum->value();

is(Enum|string $compare)

Returns true if this instance is the same as the given constant key or enumeration instance.

$enum->is(City::SYDNEY);       // Compare to constant key
$enum->is(City::SYDNEY());     // Compare to instance

__toString()

The __toString() method is defined to return the constant name.

(string)City::SYDNEY();      // "SYDNEY"

Static Methods

map()

Returns an array which maps the constant keys to a value. This method can be optionally implemented in a sub-class. The default implementation returns an array of keys mapped to null.