$conf
$conf : \Phabstractic\Features\Zend\Config\Config
The objects configuration object
Should be an instance of Zend/Config
Enumeration Class - Creates and Defines OO-defined Enumeration Classes/Objects
The Enum class which when instantiated can define an enumeration that can then be 'baked' into the appropriate namespace (or global namespace) and accessed, once baked, as an enumeration class/object of itself.
NOTE: This class no longer uses the SPL Enum documented as of version 3.0
A static 'registry' makes sure that the programmer doesn't try to instantiate a fully qualified enumerator twice, and throws an error.
NOTE: If using the custom built class, to compare the value to defined enumerator constants, perform a string typecast first: (string) $myEnum == MyEnum::constant1 If you have to compare integer values try intval( (string) $myEnum ) as well If you use these methods, it should not matter if the object is SplEnum or not. (SplEnum no longer supported)
CHANGELOG
1.1: added createInstance static function - April 11th, 2013 1.2: added \ identifier before ReflectionClass - April 11th, 2013 1.3: added namespace braces 1.4: fixed throw statements to include new operator 1.5: added case checking for options arrays 1.6: made class constants count()-able. - April 21st, 2013 1.7: fully qualified classes in eval code - April 21st, 2013 1.8: added support for Set Falcraft\Data\Types, used in enums, and constants - April 22nd, 2013 1.9: added exception handling to gracefully exit enum generation and return false added code niceties and a bit more documentation - May 3rd, 2013 1.10: used standard object for options - May 27th, 2013 1.11: Fixed up some loopholes and cracks - May 27th, 2013 1.12: Changed default to default to 0 when missing - August 6th, 2013 1.13: Removed standard object and set dependency (loops, duh) - February 2nd, 2014 2.0: Refactored to use the Configuration Feature (Features/Configuration.php) - April 7th, 2015 2.0.1: Added enum list check in code generator - April 7th, 2015 2.0.2: Added more flexible options in constructor - April 10th, 2015 2.0.3: Ensured Default Values using static property - September 4th, 2015 3.0: reformatted for inclusion in phabstractic reverted constants to a non-associative array added value checking in generated class - July 8th, 2016 3.0.1: refined value checking in generated class - July 17th, 2016 3.0.2: added getConst method in generated class - JJuly 18th, 2016 3.0.3: implement configurationinterface - July 31st, 2016
configure(array|string|\Phabstractic\Features\Zend\Config\Config $configuration, string $format = null, mixed $context = null) : boolean
Configure An Object
Expects an array for configuration however, you can also pass it a filepath where it will read the information from a file automatically detecting the format using the file extension. You can also pass a Zend/Config object already made.
You can also pass a format specifier (forced format) for use in a if $configuration is a string formatted with such information. E.G. to load from a string in the format ini:
$this->configure($configString, 'ini');
The $context argument is used for any additional reader constructor information, such as the constructor for the 'yaml' format.
NOTE: You can override/extend the classes used for reading formats by identifying an additional array in the property $this->configReaders. This will merge with the standard formats array.
| array|string|\Phabstractic\Features\Zend\Config\Config | $configuration | The objects configuration information. |
| string | $format | The forced format, or format for configuration string |
| mixed | $context | Any additional information for a reader constructor, such as needed for the YAML format. |
True if instantiated
saveSettings(string $file, \Phabstractic\Features\Zend\Config\Writer\WriterInterface $writer = null, boolean $exclusive = true, mixed $context = null)
Save an Object's Configuration to a File
Takes an objects $conf property and writes the information contained therein to a file with a format automatically specified by the filename.
It is possible to retrieve a string of a particular format from this method by specifying the filename '#string' with an extension indicating the desired format, such as '#string.json'.
The $context argument is used for any additional reader constructor information, such as the constructor for the 'yaml' format.
NOTE: You can override/extend the classes used for writing formats by identifying an additional array in the property $this->configWriters. This will merge with the standard formats array.
| string | $file | The file path to write to, or '#string.ext' |
| \Phabstractic\Features\Zend\Config\Writer\WriterInterface | $writer | The optional writer object supplied to use (such as a MySQL writer) |
| boolean | $exclusive | Argument provided to toFile(), file exclusive lock when writing |
| mixed | $context | Any additionla writer constructor information (YAML) |
getSettings(string $format, $context = null) : string|boolean
Retrieve an Object's Configuration Information As String
This is a shortcut to ::saveSettings() which specifies a format and forces the return of a string, using the #string.ext filename -see documentation for ::saveSettings()-
| string | $format | The format to return, must be supported by ::saveSettings(), use $this->configWriters to support additional formats. |
| $context |
The formatted string, or false otherwise
processSettings(\Phabstractic\Features\Zend\Config\Processor\ProcessorInterface $processor)
Process an Object's Configuration
This uses a Zend\Config\Processor implementation to process the configuration information, such as constants. The processor must be supplied and implement ProcessorInterface
NOTE: Edits the $conf object in place.
| \Phabstractic\Features\Zend\Config\Processor\ProcessorInterface | $processor | The given processor object |
__construct(string $className, array $values, array|\Phabstractic\Data\Types\Zend\Config\Config|string $options = array())
Enum Construction, Set Up Enum Parameters
This sets up the parameters for the enum to be generated. It only generates the enum class when the option 'bake' is set to true
Options:
default => default constant identifier when instantiating class namespace => namespace to define this enumerator class in bake => define the class immediately with the given parameters
| string | $className | The name of the generated class |
| array | $values | The constant values in the form, identifier => value |
| array|\Phabstractic\Data\Types\Zend\Config\Config|string | $options | See above options |
bake()
Generates the enumerator class in the desired namespace.
Generates the enumerator class in the desired namespace using the given parameters, in essence solidifying them in place. Once an enum class is 'baked' it cannot be changed.
This class also pushes the qualified name onto a static stack so that future enum classes defined through this method don't clash in name, allowing the class to raise a RangeException
setClassname(string $className)
Sets the name of the class to be generated
Checks to make sure the proposed fully qualified name doesn't clash with an already created enumerator object, raising a RangeException error
| string | $className | The name of the class to be generated |
when the qualified name clashes with an already created enumerator class
when the class has already been baked
addConstant(string $name)
Add a single constant to the constant list
This method overrides any constant names already defined with the new proposed values
| string | $name | The name of the constant |
if the class has already been baked
addConstants(array $constants)
Add multiple constants to the constant list
This method employs the array structure identifier => value. Overrides any constant names already defined with the new proposed values
| array | $constants | The array of constants to add to the list |
if the class has already been baked
removeConstant(string $name)
Remove a constant from the constant list
This method removes a constant from the constant list only if the class has not been generated, otherwise it throws an error
| string | $name | Name of the constant |
if the class has already been baked
setDefault( $name) : boolean
Set the default of the generated enumerator class
| $name | The IDENTIFIER of the default [constant keys] (i.e. Red, Apple, ...) |
when the class has already been baked
Successful?
getDefaultValue() : mixed|null
Retrieve value of default of the enumerator class (identifier=>VALUE)
Note that no constant in an enumerated class can be null
Any value that meets the constants requirements, or NULL if there is no default OR the default is not in the constants list
setNamespace(string $namespace)
Sets up the namespace to be used when generating the enumeration class
This sets the namespace that will be used when the enumerator class is generated. How? Eval statements operate in the global namespace, or basically a clean slate enabling us to put a namespace statement at the beginning of our generated code. Any namespace will do, if there is no namespace, you must access your enumerator using the global namespace. ex: \Months::January, \Colors::Red, ...
| string | $namespace | The namespace specified |
when the class/namespace has already been generated via Enum
if the class has already been generated/baked.
getInstance(mixed $value) : object
Instantiate an instance of the generated class
The generated instance will be given the value parameter It's impossible to instantiate a generated class with a null value, thus no constant in the enumeration can be null
| mixed | $value | Any constant friendly value found in the enumerator |
if instantiated witho a null value
An instance of the generated enumerator class
createEnumeration(string $identifier, null $value = null) : object
Encapsulate an apprioriate value inside an enumeration object
Ex: 404 could turn into HTTP\ResponseCode(404);
| string | $identifier | The enum to use, as existing in the static variable |
| null | $value | The value to use in the newly created object |
createEnumerator(string $className, array $values, array $options = array())
Straight out define an enumerator class without instantiating
Takes care of the instantiation and defines the enumerator according to parameters
Added in version 1.1
| string | $className | The name of the enumerator class |
| array | $values | The constants values of the enumerator |
| array | $options | See Above (__construct) |
createEnum(string $className, array $values) : boolean
Generates the required class code and evaluates it
The function that pieces the generated code together and evaluates it It defines a custom enumerator class, SplEnum is not supported from version 3 onwards. Use ->get() to explicitly get the value of both SplEnum- (NOT SUPPORTED) and custom-derived classes.
NOTE: The eval'd code can throw an \UnexpectedValueException (root)
| string | $className | The name of the generated class |
| array | $values | The constant values in the form, identifier => value |
if enum couldn't be created
if enum class already exists
If enumerator was generated at all (without errors)