Wiki

#Oroboros Core

Current Release: 0.2.4

Author: Brian Dayhoff

Copyright: Copyright 2016, all rights reserved.

License: MIT

#Oroboros Core Design Specifications#

Below is a survey of our internal class, trait, and interface structure, what each is meant to accomplish, and how it interracts with the rest of this system.

##Interfaces##

Interfaces follow three root categories in Oroboros core:

Each of these fulfills a distinct purpose in this system. More detailed information on this can be found in their individual pages, but a brief overview is provided below:

###Contract Interfaces###

A Contract Api Interface enforces methods, and provides expected interface inheritance to honor a specification.

Applies to: Single classes, that honor a set of expected methods, either directly or through inheritance

Does not apply to: Families of classes not related by known inheritance, or values that need to be fixed declarations

Most 3rd party interfaces, PHP internal interfaces, or any other interface construct established to directly enforce methods and promote loose coupling could be considered to be a Contract Interface within the specifications of this system.

Contract Api Interfaces designate single classes as valid for a specific purpose.

Contract Api Interfaces SHOULD be implemented by any class that honors them, either directly or by inheritance.

Contract Api Interfaces SHOULD extend any other interface within their scope whose methods they honor either directly or indirectly, directly or indirectly extending them.

Contract Api Interfaces MUST NOT extend any Api Interface or Enumerated Api Interface either directly or indirectly.

###Api Interfaces###

An Api Interface defines a package of related constructs, how they correlate to each other, any prerequisites that must be met for the package that are out of scope, and any additional apis that the package can honor by inheritance of common base level abstraction.

Applies to: Families of related objects that collectively or interactively accomplish a single intended task

Does not apply to: Single classes, unless they completely honor all of their requirements without any other dependent objects

Api Interfaces define grouping and abstract relation within individually unrelated classes that work together for a common objective.

Api Interfaces designate a package or family of classes as valid for a specific purpose.

Api Interfaces SHOULD only be implemented by final concrete classes, not abstracts.

Api Interfaces MUST NOT extend any Contract Api Interface, either directly or indirectly.

Api Interfaces SHOULD NOT extend any Enumerated Api Interface, either directly or indirectly, UNLESS it provides values that SHOULD be available to every single class in the api.

Api Interfaces SHOULD NOT designate methods, UNLESS those methods SHOULD be made available by every single class in the api.

###Enumerated Api Interfaces###

An Enumerated Api Interface defines sets of expected, fixed, read-only values that either do not change, or change only in expected ways. Their purpose is to provide a quick index of common values that are either universally applicable, or do not warrant a broader programmatic design to access.

Applies to: Sets of known fixed, immutable values that need to be generally accessed, without global scope

Does not apply to: Enforcing method integrity (that is accomplished by contract interfaces)

Enumerated Api Interfaces provide fixed, read-only consistent values to implementers, without the need for additional abstraction or runtime processing via method calls. They are only appropriate when values should be easily accessible and are not subject to change.

Enumerated Api Interfaces designate fixed expected values only, and make them available to their implementers.

Enumerated Api Interfaces MAY designate constants, which SHOULD have a unique prefix scoped to that specific enumeration that is not going to collide elsewhere.

Enumerated Api Interfaces MAY inherit from one or more related Enumerated Api Interfaces, either directly or indirectly.

Enumerated Api Interfaces SHOULD provide a corresponding enumerator object, which is tasked with indexing it's values for objects that do not directly implement it (when constant collisions are possible). * You may extend the provided abstract \oroboros\core\abstracts\libraries\enum\AbstractEnum to accomplish this, which only needs to implement the Enumerated Api Interface in order to index it, though you MAY also override it's provided methods and determine a blacklist, mandatory prefix, or mandatory suffix if you have additional out-of-scope class constants present that you do not wish it to include. * You may use the provided trait \oroboros\core\traits\libraries\enum\EnumTrait to accomplish this, which requires that you also implement the Enumerated Api Interface in order to index it. You MAY also override it's provided methods and determine a blacklist, mandatory prefix, or mandatory suffix if you have additional out-of-scope class constants present that you do not wish it to include.

Enumerated Api Interfaces MUST NOT designate methods.

Enumerated Api Interfaces MUST NOT extend any Contract Interface, either directly or indirectly.

Enumerated Api Interfaces MUST NOT extend any Api Interface, either directly or indirectly.

##Traits##

In the context of Oroboros core, traits provide ALL method functionality, and the default methods required to honor all Contract Interfaces. As traits cannot directly implement interfaces or declare class constants, they will provide in their doc block comment any such required provisions for them to honor their purpose by their implementing class.

Applies to: Providing methods that honor a contract

Does not apply to: Enforcing programatically that the methods in the class are valid (interfaces accomplish that)

Traits provide all method functionality in this system.

Oroboros traits provide all methods this system offers.

Oroboros traits are written to directly satisfy the requirements of Contract Interfaces.

Oroboros traits MAY be implemented by any class that wants to honor a corresponding Contract Interfaces, provided the contract does not demand methods that are incompatible with the specific class.

Oroboros traits SHALL directly satisfy all requirements of a Contract Interfaces, with no additional work by the 3rd party aside from implementing both on a desired class.

Oroboros traits SHALL directly provide all other required method sets, by including the traits that honor those, which alleviates the need for the implementing class to sort this out manually.

##Classes##

In the context of Oroboros core, classes are just containers for traits, constants, and interfaces, which provide association, inheritance, and concrete constructs to work with, and nothing else. All abstraction is defined in traits, and all fixed values or api validation is defined in interfaces. Classes in this system only act as a means to associate them directly, and associate the class with a specific scope it is intended for.

Applies to: Creating association between a contract (an interface), and a signature(a trait)

Does not apply to: Direct declaration of methods (traits accomplish this), or determining inheritance (interfaces accomplish this)

Classes in this system are simple containers that provide association, and only that.

It should be noted that this is the internal approach to structure, but this is not enforced in any 3rd party useage at any time. You MAY write your own methods directly in classes if you wish, but contributions to internal Oroboros core logic if it is meant to be part of this package MUST abstract this into traits.

Oroboros Classes are containers that associate a contract (the interface) with a signature (the trait).

Oroboros Classes MUST declare a CLASS_TYPE constant directly, without inheriting this from an interface.

Oroboros Classes MUST declare a CLASS_SCOPE constant directly, without inheriting this from an interface.

Oroboros Classes MUST declare a API constant directly, without inheriting this from an interface.

Oroboros Classes MAY declareAPI, CLASS_TYPE, or CLASS_SCOPE as false if they do not apply (but they MUST be present).

Oroboros Classes SHOULD declareAPI as a string, corresponding to a valid api interface within the default namespace \oroboros\core\interfaces\api, or any custom extension namespace of this that you declare, provided it inherits from the base api interface.

Oroboros Classes SHOULD declareCLASS_TYPE as a direct reference to a value in \oroboros\core\interfaces\api\ClassTypeApi, using it's fully qualified static declaration.

Oroboros Classes SHOULD declareCLASS_SCOPE as a direct reference to a value in \oroboros\core\interfaces\api\ClassScopeApi, using it's fully qualified static declaration.

Oroboros Classes MUST be prefixed with either abstract or final.

Oroboros Classes MUST NOT directly declare methods.

###Class Type Declaration###

Class type is declared by defining the constant CLASS_TYPE within a class.

As some class types inherit from other class types, this designation MUST NOT be determined within an interface, as interface constants cannot be overridden, though class constants can be.

Class types equate to any valid value found within the class type api interface:

\oroboros\core\interfaces\api\ClassTypeApi

When this value is declared, it allows the system to manually validate that object against the supplied Api Interfaces and Contract Interfaces that correspond to it, even if the class did not implement either of them.

This is useful in a number of ways, including but not limited to: * Determining how close a class is to honoring it's api, without causing fatal errors for an instance of it not honoring it's interface during development. * Customizing the execution plan, access levels of objects, scope, or visibility to your own specific needs flexibly. * Determining preferential object hierarchy when multiple objects that can satisfy the same condition are present (eg: I have a lightweight operation to perform, and two objects that satisfy its api. One is heavily abstracted and adds significant weight to the underlying option for a specific purpose I don't need, and the other is generic and accomplishes the task quickly with no frills. I want the second one, to avoid performance impact, so I use the class type to determine preference, and allow substitution based on contract, and preference based on class type)

###Class Scope Declaration###

Class scope is declared by defining the constant CLASS_SCOPE within a class.

As some class scopes inherit from other class types, this designation MUST NOT be determined within an interface, as interface constants cannot be overridden, though class constants can be.

Class scopes equate to any valid value found within the class type api interface:

\oroboros\core\interfaces\api\ClassScopeApi

When this value is declared, it allows the system to manually validate that object against the supplied Api Interfaces and Contract Interfaces that correspond to it, even if the class did not implement either of them. Unlike CLASS_TYPE, CLASS_SCOPE is not concerned with direct inheritance, and instead defines a related category of functionality without regard to inheritance

This is useful in a number of ways, including but not limited to: * Determining what specific jobs an object is related to, without the need to establish a large enforced architecture through chains of interfaces or base classes. * Creating association toward a specific package or underlying pattern that requires the interraction of numerous classes that accomplish a related body of work, but do not extend each other. * Helps keep structure without enforcing direct coupling at compile time (though this MAY be used in conjunction with the standard approach, and SHOULD in all cases where it is logical to do so). * Helps create a measure of relation between unrelated objects that share no base interface or parent class, so they may be categorically indexed within the same body of intended purpose (eg: I have three extensions, each of which provides libraries, controllers, models, and views. Some of these from each deal with PDF files, but the packages are independently authored and share no real distinction with each other aside from a common generic ancestor. They have all scaffolded out their own abstraction to represent their own body of work individually, that bears no underlying specific correlation across packages. The CLASS_SCOPE allows this association to occur regardless of inheritance, so that any library, controller, model, or view regardless of package or implementation can categorize itself with dealing with files, and I also do not need to enforce that they are coupled via a dedicated \FileHandlingInterface to create this association, because I just want to know they are somewhat related, not that they have the same api, and I also do not want to add additional direct dependency overhead to them to accomplish this, which prevents any of these packages from failing if \FileHandlerInterface is not found).

###Api Declaration###

Class scope is declared by defining the constant CLASS_SCOPE within a class.

As some class scopes inherit from other class types, this designation MUST NOT be determined within an interface, as interface constants cannot be overridden, though class constants can be.

Class scopes equate to any valid value found within the class type api interface:

\oroboros\core\interfaces\api\ClassScopeApi

When this value is declared, it allows the system to manually validate that object against the supplied Api Interfaces and Contract Interfaces that correspond to it, even if the class did not implement either of them. Unlike CLASS_TYPE, CLASS_SCOPE is not concerned with direct inheritance, and instead defines a related category of functionality without regard to inheritance

##Configurations##

UNFINISHED: Pending full integration of data objects, file handler, and basic database accessor, please check back later.

Configurations within Oroboros are containers that are associated directly with a configuration source. They are always objects, but are iterable (and thereby can be treated as arrays), can perform read/write/create/delete upon their source, can be locked to be read-only, write-only, or no-access, can be designated to be unlockable only by specific classes (with or without inheritance substitution, as needed), specific interfaces (with or without inheritance substitution, as needed), only by ojects that can supply a passphrase (any object, but it must know the exact passphrase, which is generated at runtime and deleted at the end of execution, and cannot realistically be otherwise known or cracked), by specific object fingerprint (I want only this one specific object to open it, even if other exact clones of that object ask, say no).

Applies to: Straightforward uniform Api access to numerous possible configuration data-stores, and the read/write/edit/create privileges required to interact with them.

Does not apply to: Complex business logic (use a model or library for that)

Configurations are just reflections of an external resource (which can be a any flat-file that can be interpreted, database table, set of environment variables, remote service result, compiled enumerated set, memory store, or whatever is needed to establish the configuration)

Configurations MUST provide a measure of control over I/O with the resource, allowing safe distribution to objects that should not be trusted not to mutate the data accidentally.

Configurations MUST provide a consistent access api for any set of external data that feeds instructions to the system, so that (no direct regard needs to be given to their format or location during runtime)

Configurations MAY be registered with a scope, parent, class type, contract, 3rd party interface or class, passphrase, or specific object runtime fingerprint within the Codex, which allows any other object within that field of relation to then ask the system for a copy to work with.

Configurations MAY have privacy and access rights scoped similarly to the above registration options, at which point visibility and editability MAY be controlled as granularly as you would like.