Skip to content

Commit 70384af

Browse files
author
Marc Bennewitz
committed
updated README to match the new API
Also rewrite usage information to make it more clear
1 parent 9a00cad commit 70384af

File tree

1 file changed

+80
-168
lines changed

1 file changed

+80
-168
lines changed

‎README.md

Lines changed: 80 additions & 168 deletions
Original file line numberDiff line numberDiff line change
@@ -23,223 +23,135 @@ It's an abstract class that needs to be extended to use it.
2323
> particular concrete representation in the computer's memory; compilers and
2424
> interpreters can represent them arbitrarily.
2525
26-
27-
# Why not ```SplEnum```
28-
29-
* It's not build-in PHP and requires pecl extension
30-
* SplEnum is too much magic under the hod
31-
32-
33-
# API
34-
35-
abstract class MabeEnum\Enum
36-
{
37-
/**
38-
* Constructor
39-
* @param scalar $value The enum value to select
40-
* @throws InvalidArgumentException On unknwon value
41-
*/
42-
public function __construct($value);
43-
44-
/**
45-
* Returns an assoc array of defined constant names and the values
46-
* @return array
47-
*/
48-
final public function getConstants();
49-
50-
/**
51-
* Get the selected value
52-
* @return scalar
53-
*/
54-
final public function getValue();
55-
56-
/**
57-
* Get the constant name of the selected value
58-
* @return string
59-
*/
60-
final public function getName();
61-
62-
/**
63-
* Get the ordinal number of the selected value
64-
* @return int
65-
*/
66-
final public function getOrdinal();
67-
68-
/**
69-
* Get the selected value as string
70-
* (This will be called automatically on converting into a string)
71-
* @return string
72-
*/
73-
final public function __toString();
74-
75-
/**
76-
* Instantiate a new enum were the selected value
77-
* is the constant name of the called method name
78-
* (This will be called automatically on calling static method)
79-
* NOTE: THIS WILL WORK FOR PHP >= 5.3 ONLY
80-
* @param string $name The name of the constant to instantiate
81-
* @param array $args This should be an empty array (no arguments)
82-
* @throws BadMethodCallException If the called method hasn't the same name as a constant
83-
* @return MabeEnum\Enum The instantiated enum
84-
*/
85-
final public static __callStatic($name, array $args);
86-
}
87-
88-
8926
# Usage
9027

91-
## The way of class constants
28+
## Basics
9229

93-
class User
30+
use MabeEnum\Enum;
31+
32+
// define an own enumeration class
33+
class UserStatus extends Enum
9434
{
9535
const INACTIVE = 0;
9636
const ACTIVE = 1;
9737
const DELETED = 2;
98-
99-
protected $status = 0;
100-
101-
public function setStatus($status)
102-
{
103-
$intStatus = (int)$status;
104-
if (!in_array($intStatus, array(self::INACTIVE, self::ACTIVE, self::DELETED))) {
105-
throw new InvalidArgumentException("Invalid status {$status}");
106-
}
107-
$this->status = $intStatus;
108-
}
109-
110-
public function getStatus()
111-
{
112-
return $this->status;
113-
}
11438
}
39+
40+
// different ways to instantiate an enumeration
41+
$status = UserStatus::get(UserStatus::ACTIVE);
42+
$status = UserStatus::ACTIVE();
43+
$status = UserStatus::getByName('ACTIVE');
44+
$status = UserStatus::getByOrdinal(1);
45+
46+
// available methods to get the selected entry
47+
$status->getValue(); // returns the selected constant value
48+
$status->getName(); // returns the selected constant name
49+
$status->getOrdinal(); // returns the ordinal number of the selected constant
50+
(string) $status; // returns the selected constant name
51+
52+
// The same enumerations of the same class holds the same instance
53+
UserStatus::get(UserStatus::ACTIVE) === UserStatus::ACTIVE()
54+
UserStatus::get(UserStatus::DELETED) != UserStatus::INACTIVE()
11555

116-
$user = new User();
117-
echo 'Default user status: ' . $user->getStatus() . PHP_EOL;
118-
$user->setStatus(User::ACTIVE);
119-
echo 'Changed user status: ' . $user->getStatus() . PHP_EOL;
120-
121-
**PRINTS**
122-
123-
Default user status: 0
124-
Changed user status: 1
125-
126-
* Requires validation on every use
127-
* Hard to extend the list of possible values
128-
* Hard to get a human readable name of a value
129-
130-
## The way of php-enum:
13156

132-
use MabeEnum\Enum;
57+
## Type-Hint
13358

134-
class UserStatusEnum extends Enum
135-
{
136-
const INACTIVE = 0;
137-
const ACTIVE = 1;
138-
const DELETED = 2;
139-
}
59+
use MabeEnum\Enum;
60+
use UserStatus;
14061

14162
class User
14263
{
14364
protected $status;
14465

145-
public function setStatus(UserStatusEnum $status)
66+
public function setStatus(UserStatus $status)
14667
{
14768
$this->status = $status;
14869
}
14970

15071
public function getStatus()
15172
{
15273
if (!$this->status) {
153-
// init default status
154-
$this->status = UserStatusEnum::INACTIVE();
74+
// initialize a default value
75+
$this->status = UserStatus::get(UserStatus::INACTIVE);
15576
}
15677
return $this->status;
15778
}
15879
}
159-
160-
$user = new User();
161-
echo 'Default user status: ' . $user->getStatus() . '(' . $user->getStatus()->getValue() . ')' . PHP_EOL;
162-
$user->setStatus(UserStatusEnum::ACTIVE());
163-
echo 'Changed user status: ' . $user->getStatus() . '(' . $user->getStatus()->getValue() . ')' . PHP_EOL;
16480

165-
**PRINTS**
81+
## EnumMap
16682

167-
Default user status: INACTIVE (0)
168-
Changed user status: ACTIVE (1)
83+
An ```EnumMap``` maps enumeration instances of exactly one type to data assigned to.
84+
Internally the ```EnumMap``` is based of ```SplObjectStorage```.
16985

170-
* Validation will be already done on basic class ```MabeEnum\Enum```
171-
* Using type-hint makes arguments save
172-
* Human readable name of a value is simple accessable
86+
use MabeEnum\EnumMap;
87+
use UserStatus;
17388

89+
// create a new EnumMap
90+
$enumMap = new EnumMap('UserStatus');
17491

175-
# Install
92+
// attach entries (by value of by instance)
93+
$enumMap->attach(UserStatus::INACTIVE, 'inaktiv');
94+
$enumMap->attach(UserStatus::ACTIVE(), 'aktiv');
95+
$enumMap->attach(UserStatus::DELETED(), 'gelöscht');
96+
97+
// detach entries (by value or by instance)
98+
$enumMap->detach(UserStatus::INACTIVE);
99+
$enumMap->detach(UserStatus::DELETED());
100+
101+
// iterate
102+
var_dump(iterator_to_array($enumSet)); // array(0 => UserStatus{$value=1});
176103

177-
## Composer
104+
// it's possible to define the key and the value used for iteration
105+
$enumSet->setFlags(EnumSet::KEY_AS_NAME | EnumSet::CURRENT_AS_DATA);
106+
var_dump(iterator_to_array($enumSet)); // array('ACTIVE' => 'aktiv');
178107

179-
Add ```marc-mabe/php-enum``` to the project's composer.json dependencies and run
180-
```php composer.phar install```
181108

182-
## GIT
109+
## EnumSet
183110

184-
```git clone git://github.com/marc-mabe/php-enum.git```
111+
An ```EnumSet``` groups enumeration instances of exactly one type together.
112+
Internally it's based of a list (array) of ordinal values.
185113

186-
## ZIP / TAR
114+
use MabeEnum\EnumSet;
115+
use UserStatus;
187116

188-
Download the last version from [Github](https://github.com/marc-mabe/php-enum/tags)
189-
and extract it.
117+
// create a new EnumSet
118+
$enumSet = new EnumSet('UserStatus');
190119

120+
// attach entries (by value of by instance)
121+
$enumSet->attach(UserStatus::INACTIVE);
122+
$enumSet->attach(UserStatus::ACTIVE());
123+
$enumSet->attach(UserStatus::DELETED());
124+
125+
// detach entries (by value or by instance)
126+
$enumSet->detach(UserStatus::INACTIVE);
127+
$enumSet->detach(UserStatus::DELETED());
128+
129+
// iterate
130+
var_dump(iterator_to_array($enumSet)); // array(0 => UserStatus{$value=1});
191131

192-
# Examples
132+
# Why not ```SplEnum```
193133

194-
## Define a default value:
134+
* ```SplEnum``` is not build-in into PHP and requires pecl extension installed.
135+
* Instances of the same value of an ```SplEnum``` are not the same instances.
136+
* ```SplEnum``` doesn't have an implementaiton for ```EnumMap``` and ```EnumSet```.
195137

196-
This example defines the constant ```ONE``` with value ```1``` as default
197-
value.
198138

199-
use MabeEnum\Enum;
200-
201-
class MyEnumWithDefaultValue extends Enum
202-
{
203-
const ONE = 1;
204-
const TWO = 2;
205-
206-
public function __construct($value = self::ONE)
207-
{
208-
parent::__construct($value);
209-
}
210-
}
139+
# Install
211140

212-
## Inheritance
141+
## Composer
213142

214-
It's also possible to extend other enumerations.
143+
Add ```marc-mabe/php-enum``` to the project's composer.json dependencies and run
144+
```php composer.phar install```
215145

216-
use MabeEnum\Enum;
217-
218-
class MyEnum extends Enum
219-
{
220-
const ONE = 1;
221-
const TWO = 2;
222-
}
223-
224-
class EnumInheritance extends MyEnum
225-
{
226-
const INHERITANCE = 'Inheritance';
227-
}
146+
## GIT
228147

229-
## Simplified instantiation
148+
```git clone git://github.com/marc-mabe/php-enum.git```
230149

231-
It's possible to call one of the defined constants like a method
232-
and you will get the instantiated enum as a result.
150+
## ZIP / TAR
151+
152+
Download the last version from [Github](https://github.com/marc-mabe/php-enum/tags)
153+
and extract it.
233154

234-
use MabeEnum\Enum;
235-
236-
class MyEnum extends Enum
237-
{
238-
const ONE = 1;
239-
const TWO = 2;
240-
}
241-
242-
$enum = MyEnum::ONE();
243155

244156
# New BSD License
245157

0 commit comments

Comments
 (0)