#Oroboros Core

Current Release: 0.2.4

Author: Brian Dayhoff

Copyright: Copyright 2016, all rights reserved.

License: MIT

#Oroboros Core Enumerated Api Interface Specifications#

Contract interfaces enforce expected methods for interoperability, and remove direct class coupling from the equation.

The primary purpose of these interfaces is for easy interoperable compatibility, and enforcing expected behavior.

Internally, they are expected to be provided to verify that a given class registered for internal compatibility is capable of honoring it's stated obligations.

Classes recognized as internally interoperable MUST implement one or more Contract Interfaces All checks for internal compatibility are done against these.

You may declare your own set if you are extending this system, which must extend from the following interface (or any child of this interface, if you wish to use additional Oroboros class type expectations)

\oroboros\core\interfaces\enumerated\BaseEnumerated

Internally, Enumerated Api Interfaces are used as a means of validating fixed, expected values without any external dependencies, and for designating internal structural architecture considerations that the codebase should be able to resolve without external dependency in a flexible way.

Externally, the programming paradigm is presented as a potentially useful construct to extend upon for your own needs, though there is no requirement that you do so unless you are extending this system in a way that is meant to validate internally (abstraction for this is provided, so it should not be a huge consideration unless you are adding functionality that does not exist in this package already, such as providing new class types or class scopes).

#####Good uses of Enumerated Apis:#####

• Codifying error codes, class types, or other system-specific fixed values that are not dynamic.
• Codifying RFC specifications, which are fixed and unlikely to change in the near future, and provide a semantically correct, uniform approach to honoring the spec.
• Codifying expected values that honor a specific standard, compatibility requirement, or specification that demands precise and immutable parameters.
• Providing fixed, contextual information about other fixed values without the overhead of a database connection.
• Providing a means for global constants to compile as fixed, read-only values for classes at runtime (for example performing a conditional check if the environment is http or cgi, then defining a global constant that designates which, and then using that constant as the value in the Enumerated Api so all implementing classes are aware if they may reference http environmental assets or not without the requirement of being directly coupled with any external class or function utility to provide this check).
• Providing a means for 3rd parties to define floating point values that compile into fixed, read only designations (for example creating a company config interface that can be dynamically compiled at runtime instead of copy-pasta'd for each subsequent client)
• Indexing any uniform values that need to be consistent across all application (for example: valid response headers, valid request headers, street name types, postal codes, telephone area codes, etc, reuseable regexes, collections of interfaces that are distinct but collectively honor a larger package, etc)
• Validating expected results in a uniform way by providing a set of fixed but not neccessarily semantically related values, without the need for regular expressions or complex logic.
• Sets of simple fixed values that you need to access huge numbers of times without adding additional performance weight (class constants are fixed and read-only at compiletime, and do not require any additional memory to access, whereas function calls do)

#####Bad uses of Enumerated Apis:#####

• Hard coding any mutable values that are subject to frequent change
• Hard coding any value that would be better served with a data-layer approach (you SHOULD NOT codify huge constructs as Enumerated Api Interfaces, unless they MUST be available without any data-layer dependency AND should reflect directly in your codebase instead of being separated into a config)
• Hard coding values out of laziness to avoid better abstraction (Oroboros Core provides Enumerated Api's for fixed interal settings that designate scope, class type, error messages, and any required information for honoring a Psr specification that requires a set of fixed valid values. This can be extended upon easily for any purpose, but you SHOULD NOT rely on these to provide the majority of your own data specifications, UNLESS you are writing a standalone package that should not have external requirements whatsoever, in which case it is appropriate)
• Using them to avoid the overhead of a database call in any application where requiring one would be appropriate (Note: Oroboros core is a toolbox library, not an opinionated framework, and all of it's offerings SHOULD be available without any mandatory reliance on external resources whenever possible, but this is a conscious design choice appropriate to this package specifically, because this package's goal is to provide you utilities with NO opinion or external dependency attached to them. If you were creating a framework or CMS, it is not unreasonable to expect a data layer to be present, and in that case the database should be used for such considerations)

##Specifications##

Enumerated Api interfaces follow the following specifications:

• They MUST inherit \oroboros\core\interfaces\enumerated\BaseEnumerated
• They MAY declare fixed, non-colliding class constants that should be explicitly defined and are unexpected to change ()
• They MAY extend zero or more other Enumerated Api Interfaces
• They MUST NOT inherit any other interface that enforces a method.
• They MUST NOT extend any Contract Interfaces (which extend from: \oroboros\core\interfaces\contract\BaseContract as their parent),
• They MUST NOT extend any Api Interface (which extend from: \oroboros\core\interfaces\api\BaseApi as their parent)

#####An Example Use Case Enumerated Api Interface#####

This example provides a decent potential use case of enumeration.

The list of valid domain name suffixes is huge, often separated by subsections but not always, and does not have any really simple, uniform, and consistent designation that can be reliably regex'd without a great deal of complexity. Efforts to determine this frequently choke up on development uris, subdomains (particularly subdomains with multiple separation) and a number of other areas. Typically in any flexible system, a great deal of complexity arises from parsing these individually and applying a broader paradigm of substitution between environments, despite that the suffixes are unlikely to change often.

``

<?php namespace \vendorname\packagename\enumerated; interface ValidDomainSuffixes extends \oroboros\core\interfaces\enumerated\BaseEnumerated { const DOMAIN_SUFFIX_COM = '.com'; const DOMAIN_SUFFIX_ORG = '.org'; const DOMAIN_SUFFIX_CO = '.co'; const DOMAIN_SUFFIX_CO_UK = '.co.uk'; // ... and so on }

``

#####Useage#####

Oroboros provides you with two ways of easily indexing enumerated api interfaces.

There is an abstract you can extend:

\oroboros\core\abstracts\libraries\enum\AbstractEnum

Or a trait you can implement:

\oroboros\core\traits\libraries\enum\EnumTrait

Our system will validate whether your class is enumerable for other object interaction by checking for the following contract (or any extension of it):

\oroboros\core\interfaces\contract\libraries\enum\EnumContract

The presence of this Contract Interface indicates to the system that your class MAY provide a set of enumerated, fixed, read-only values, and that the implementing object can be treated as an authority on those values, and whether they are valid.

This is the simplest way to generate a valid auth or validation construct in this system, but not the only way.

If you have no need to integrate your class into the internals of Oroboros, then just attach the trait anywhere and you can read them without issue.

If you do not have any external class inheritance requirement (This system never enforces any), you may simply extend our provided abstract (which only implements the contract and trait, and declares it's api, and otherwise does no additional logic), and your class will validate everywhere as enumerable.

If you roll your own and want to see if it is valid, or if you bound the trait to a 3rd party class and need it to validate internally, then also implement the contract interface, and provided your class honors it (it will if you are also using the provided trait), then your class WILL validate internally as enumerable.

Oroboros provides several scoped Enumerated Api Interfaces that define class types, class scopes, error codes, generic scoped exception messages that can be used with sprintf() to inject values, and a number of other sets of fixed values that are required by specific standards or specs. Any class that wishes to use this information can just implement these enumerated apis and have it directly on hand, and most of them also provide a concrete generic enumerated accessor object that can index the set, validate one of its values, and be used as a direct string representation of a chosen value. These are useful if you don't want a billion constants directly attached to your class.