1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 <?php
namespace oroboros\core\abstracts;
/*
* The MIT License
*
* Copyright 2016 Brian Dayhoff <brian@mopsyd.me>.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
/**
* <Oroboros Base Abstract Class>
* This class defines a few very simple configurations to identify
* as part of Oroboros, and implements common interfaces. All other
* Oroboros classes descend from this one wherever possible. There
* is a also a trait to emulate this behavior for classes that must
* extend a different class for some reason.
* @see \oroboros\core\traits\BaseTrait
*
* <There are only 4 meaningful programmatic lines in this base abstract>
* - implements \oroboros\core\interfaces\BaseAbstractInterface
* - use \oroboros\core\traits\BaseTrait;
* - const CLASS_SCOPE = \oroboros\core\interfaces\api\ClassScopeApi::CLASS_SCOPE_LIBRARY_ABSTRACT;
* - const API = false;
*
* <All other content in this class is documentation commenting>
*
* Any class can emulate this behavior without extending this class,
* and still be recognized as a valid Oroboros internal by doing the following:
*
* <How to interface with the system by extending core classes>
*
* - Extend one of the classes located in: \oroboros\core\abstracts
* - Declare the class constant: CLASS_SCOPE using one of the values in: \oroboros\core\interfaces\api\ClassScopeApi
* - Declare the class constant: API, either as false, or as one of the Api interfaces located in: \oroboros\core\interfaces\api
* - Profit.
*
* <How to interface with the system WITHOUT extending core classes>
*
* IF YOUR CONSTRUCTOR IS COMPATIBLE WITH THE ONE DEFINED HERE:
* (In this case we will register a fully qualified Oroboros class)
* - In your class, use the trait: \oroboros\core\traits\BaseTrait
* - Implement the interface: \oroboros\core\interfaces\BaseAbstractInterface
* - Declare the class constant: CLASS_SCOPE using one of the values in: \oroboros\core\interfaces\api\ClassScopeApi
* - Declare the class constant: API, either as false, or as one of the Api interfaces located in: \oroboros\core\interfaces\api
* - Profit.
*
* IF YOUR CONSTRUCTOR IS INCOMPATIBLE WITH THE ONE DEFINED ABOVE:
* (in this case we will register a utility,
* which is a 3rd party class that still connects to the system correctly)
* - In your class, use the trait: \oroboros\core\traits\utility\UtilityApiTrait
* - Implement the interface: \oroboros\core\interfaces\api\UtilityApi
* - Declare the class constant: CLASS_SCOPE using one of the values in: \oroboros\core\interfaces\api\ClassScopeApi
* - Declare the class constant: API, either as false, or as one of the Api interfaces located in: \oroboros\core\interfaces\api
* -Profit.
*
* <If you are extending a 3rd party or base level php class>
* it is suggested that you instead provide a utility,
* or alternately wrap it in an adapter.
* Larger packages may be provided as a module or extension.
*
* @see \oroboros\core\interfaces\api\UtilityApi
* @see \oroboros\core\interfaces\api\AdapterApi
* @see \oroboros\core\interfaces\api\ModuleApi
* @see \oroboros\core\interfaces\api\ExtensionApi
*
* @covers rootclass
* @author Brian Dayhoff <brian@mopsyd.me>
* @since 0.0.1a
*/
abstract class OroborosBaseAbstract
implements \oroboros\core\interfaces\BaseAbstractInterface
{
/**
* <Baseline Class Methods>
* All base functionality for the base class is defined in the following trait.
* The base class itself only connects the required interfaces and declares base
* level constants. Otherwise all functionality is provided here:
*/
use \oroboros\core\traits\BaseTrait;
/**
* <Default Abstract Class Scope>
* The class type and class scope determine what
* functionality to provide to the system.
* This default value resolves to ::abstract-library::
*
* You may override this within your class using the following definitions:
* @see \oroboros\core\interfaces\api\ClassScopeApi
*/
const CLASS_SCOPE = \oroboros\core\interfaces\api\ClassScopeApi::CLASS_SCOPE_LIBRARY_ABSTRACT;
/**
* <Default Class API Definition>
* Override this in child classes to define an API for the class.
* If you have an api, it should be a valid API interface,
* or a reference to it's enumerated getter object.
* (mandatory)
* @note You must define this as false by default in your class, or alternately follow the below instructions.
*
* (optional)
* @note bind to an existing provided Api, or:
*
* @note create an Api interface using the following criteria:
* @note Api interfaces MUST have Api.php as their suffix (no "." characters prior to this either)
* @note Api interfaces MUST declare a CLASS_TYPE constant, with a value provided by:
* @see \oroboros\core\interfaces\api\ClassTypeApi
* @note Api CLASS_TYPE determines what portion of the system the class is registered as an override for. You will probably only need to use ::module:: or ::extension::, but you may use any provided there.
* @note Api interfaces MUST declare the following class constants (all may be false by default): [API_DOCS, API_NAME, API_SDK, API_REPO, API_VERSION, API_AUTHOR, API_LICENSE, API_SITE];
* @note Api interface constant values MUST be false if not provided.
* @note Api interfaces SHOULD NOT extend other API interfaces, or the constants will collide.
*
* @example \oroboros\core\interfaces\api\DefaultApi
*
* @note DO NOT DO THIS IN AN INTERFACE OR YOU WILL WHITESCREEN
*
* API is repeatedly declared WITHIN CLASSES throughout the system.
* Any child class that inherits from a class that has this defined in
* their interface will not be able to declare their own api without
* causing a fatal error. For this reason, you should never declare
* this constant in an interface, or implement an interface that has
* it defined.
*/
const API = false;
}