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 144 145 146 147 148 149 150 151 152 153 154 <?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\contract\bootstrap;
/**
* <Bootstrap Contract Interface>
* This interface enforces the methods required for a valid bootstrap object.
* These methods may be manually honored, or may be satisfied by using the
* corresponding bootstrap trait.Traits that extend upon this functionality
* should be expected to implement this for you.
*
* --------
* Contract interfaces enforce expected behavior in a non-colliding way.
* They are tasked with enforcing methods, and extending interfaces
* provided by standards and other packages for compatibility.
*
* All valid oroboros classes MUST extend at
* least one Contract Interface to be considered valid.
* --------
*
* @author Brian Dayhoff <mopsyd@me.com>
* @license http://opensource.org/licenses/MIT The MIT License (MIT)
* @link bitbucket.org/oroborosframework/oroboros-core/wiki/development/api/contract_interface.md
* @category contract-interfaces
* @package oroboros/core
* @subpackage codex
* @see \oroboros\core\traits\bootstrap\BootstrapTrait
* @see \oroboros\core\interfaces\api\bootstrap\BootstrapApi
* @version 0.2.4-alpha
* @since 0.2.4-alpha
*/
interface BootstrapContract
extends \oroboros\core\interfaces\contract\BaseContract
{
/**
* <Bootstrap Constructor>
* Instantiates the bootstrap object.
* Can be called with no parameters, but accepts substitution parameters
* for unit testing specific requests, or requesting specific functionality
* that is normally out of scope for the current environment. Also accepts
* flags, which it will propogate to any controllers that it references
* automatically through dependency injection.
*
* If you intend to do full initialization within the constructor,
* you should call the initialize method manually within your constructor,
* and still place your initialization logic in that method.
* This allows for re-initialization without the weight of creating
* a new object.
*
* @param array $params (optional) An array of parameters to pass into the bootstrap, to replace it's normally defined values. This may be used for unit-testing the bootstrap process with specific overrides of local dependencies before deploying them into the normal codebase, or to create a localized bootstrap that works as a subroutine, with custom parameters it would not otherwise use.
* @param array $flags (optional) An array of flags to pass into the bootstrap, which will be propogated to controllers and routers it controls to modify their behavior. This presents a simple way for setting up debug, testing, profiling, or benchmarking paradigms, and allows for an easy way to pass environmental considerations (such as dev vs production), that will automatically propogate through all subsequent objects in the stack on execution.
* @return $this
*/
public function __construct( array $params = null, array $flags = null );
/**
* <Bootstrap Destructor>
* The Bootstrap destructor MUST release all dependent objects and
* their children, and manually release it's memory footprint also.
* It should be configured to tell the webserver not to reserve it's
* memory and release it back into the pool for the actual machine
* hardware as well (apache does not do this by default, which can
* be problematic on servers with low memory or a lot of shared threads),
* though this action SHALL NOT be executed unless explicitly requested
* via a flag passed at either instantiation, initialization, or reset.
* @return void
*/
public function __destruct();
/**
* <Bootstrap Initialization>
* Initializes the bootstrap object.
* This method separates instantiation from initialization, and provides a
* reset point to restore to in the event that instantiation did not pass
* all of the values required, or if you needed multiple instances of the
* bootstrap object with different parameters.
*
* This method should contain ALL logic that needs to be performed prior
* to execution of the primary task of the Bootstrap object.
*
* @param array $params //null no-ops, empty array erases, populated array provides parameters. Parameters are not retained if replaced, reset, or reinitialized.
* @param array $flags //null no-ops, empty array erases, populated array provides flags. Flags are not retained if replaced, reset, or reinitialized.
* @return void
*/
public function initialize( $params = null, $flags = null );
/**
* <Bootstrap Reset>
* Resets the Bootstrap object to its state immediately after execution
* fires successfully, so it is initialized, but does not have any
* remnant data that was obtained through any action that occurred
* after initialization. The purpose of this method is to allow a
* degree of external control over the execution plan, and allow it
* to be called repeatedly if needed, without the weight of
* reinitialization.
*
* @param array $params //null no-ops, empty array erases, populated array provides parameters. Parameters are not retained if replaced, reset, or reinitialized.
* @param array $flags //null no-ops, empty array erases, populated array provides flags. Flags are not retained if replaced, reset, or reinitialized.
* @return void
*/
public function reset( $params = null, $flags = null );
/**
* <Bootstrap Launch>
* Launches the application.
* If the bootstrap has not already initialized fully, it will do so at
* this point using it's default values (bootstraps should be capable of
* autonomous operation, but not assume it).
*
* At this point it will obtain it's routes, check for a match,
* load the appropriate controller if a match is found,
* load the default (or supplied) error controller if no match is found,
* initialize it's selected controller and pass any flags into it that
* were given to the bootstrap, and execute the controller route.
*/
public function launch();
/**
* <Bootstrap Shutdown>
* This method terminates the bootstrap object, and causes it to release
* all objects that it has instantiated along with their own chid objects.
* This should clear it's entire stack and memory footprint, and leave the
* bootstrap in an empty, uninitialized state. This SHALL NOT terminate
* the object, but will leave it to be either reinitialized or unset as
* determined by it's controlling logic.
*/
public function shutdown();
}