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 <?php
/*
* 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.
*/
namespace oroboros\core\interfaces\api;
/**
* <Base Api Interface>
* This interface represents the root level api interface.
* All other api interfaces extend from this root, excluding the
* enumerated api interface chain. This is a null api, meant to designate the
* origin of a chain of related interface constructs.
*
* ----------------
* PURPOSE
* ----------------
*
* An Api Interface is used to declare a family of related classes, and what
* they are meant to satisfy. It also declares any dependencies, and any
* interoperability that can occur with it, or any additional apis that it provides.
*
* This information is used internally to validate the execution plan.
*
* This information can be indexed by checking the Codex
*
* ----------------
* USAGE
* ----------------
*
* Effective useage of this interface construct without collisions requires
* that these interfaces ONLY BE IMPLEMENTED BY CONCRETE, FINAL CLASSES
*
* The traits and abstractions of this system are built to honor the
* considerations if these without directly implementing them.
*
* Concrete classes can implement them as proof that they honor their api.
* Internally, the system will FAVOR the object for jobs related to it's
* DECLARED API when it has MULTIPLE AVAILABLE OPTIONS that all honor a scope.
*
* DECLARE THE API IN THE CONCRETE CLASS if it is not met by inheritance
* (traits cannot accomplish this for you. You must either declare this
* yourself or inherit it from one of our base classes).
*
* const API = '\\oroboros\\core\\interfaces\\api\\adapters\AdapterApi'; //honors the adapter api
*
* Api Interfaces serve as an index of how class type and class scope
* relate to specific api use cases.
* This information is available by checking the Codex
*
* @see \oroboros\core\codex\Codex
*
* Which can also be done by any class using the codex trait
*
* @see \oroboros\core\traits\codex\CodexTrait
*
* Or by extending the abstract
*
* @see \oroboros\core\abstracts\codex\Codex
*
* ----------------
* CONSIDERATIONS
* ----------------
*
* These interfaces DO enforce methods, for objects to report their api.
* This condition can be satisfied by including the api trait in your class.
* Most traits use this one, so it is likely already available if you are
* implementing any other trait.
*
* @see \oroboros\core\traits\api\ApiTrait
*
* These interfaces DO declare numerous constants.
* There is a low probability of constant collision with external codebases.
* If this causes an issue, wrap the object that implements
* the api in one that doesn't, and use a pass-through to obtain it's values.
*
* There is a trait that can accomplish this strict enumeration based off of
* any interface attached to a class that uses it, which can also filter
* results by prefix or suffix of the constant name. It's super handy for
* indexing these in any class that uses them.
*
* @see \oroboros\core\traits\libraries\enum\EnumTrait
*
* There are also sets of provided defaults under the concrete namespace
*
* @see \oroboros\core\libraries\enum
*
* @satisfies \oroboros\core\interfaces\api\ClassTypeApi::CLASS_TYPE_API_VALID
* @author Brian Dayhoff <brian@mopsyd.me>
* @since 0.2.4-alpha
*/
interface BaseApi
{
//Forces the class to declare an api class constant.
const OROBOROS_DECLARED_API = self::API;
//Forces the class to declare a class type class constant.
const OROBOROS_DECLARED_CLASS_TYPE = self::CLASS_TYPE;
//Forces the class to declare a class scope class constant.
const OROBOROS_DECLARED_CLASS_SCOPE = self::CLASS_SCOPE;
}