├── .gitignore
├── README.md
├── bootstrap.php
├── composer.json
├── src
    ├── Bootstrapper.php
    ├── BootstrapperInterface.php
    ├── Symfony
    │   └── Component
    │   │   ├── Console
    │   │       ├── ApplicationHandler.php
    │   │       ├── Input
    │   │       │   └── InputInterfaceSingleton.php
    │   │       └── Output
    │   │       │   └── OutputInterfaceSingleton.php
    │   │   └── HttpFoundation
    │   │       └── RequestSingleton.php
    └── SymfonyBootstrapper.php
└── symfony-bootstrap.php


/.gitignore:
--------------------------------------------------------------------------------
1 | /composer.lock
2 | /vendor/
3 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | Tchwork Bootstrapper
  2 | ====================
  3 | 
  4 | What if we could decouple the bootstrapping logic of our apps from any global state?
  5 | 
  6 | This package makes it possible with a few conventions.
  7 | 
  8 | BootstrapperInterface
  9 | ---------------------
 10 | 
 11 | The core of this package is the `BootstrapperInterface`, which describes a high-order bootstrapping logic.
 12 | 
 13 | It is designed to be totally generic and able to run any application outside of the global state in 6 steps:
 14 | 
 15 |  1. your front-controller returns a `Closure` that wraps your app;
 16 |  2. `BootstrapperInterface::getRuntime()` is given this closure and returns a closure too (potentially the same but
 17 |     it could also be decorated) and its arguments (typically PHP superglobals turned into your domain objects);
 18 |  3. the returned closure, let's call it the "runtime", is called with the arguments computed at the previous step;
 19 |  4. the result of the runtime closure, the runtime closure and its arguments are all passed to `BootstrapperInterface::getHandler()`,
 20 |     which should return another closure, the "handler", that will handle the result itself;
 21 |  5. the handler closure is now called with the result of the runtime closure as argument;
 22 |  6. the PHP engine is terminated with the integer status code returned by the handler closure.
 23 | 
 24 | This process is extremely flexible as it allows implementations of `BootstrapperInterface` to hook into any critical steps.
 25 | 
 26 | Bootstrapping files
 27 | -------------------
 28 | 
 29 | The simplest way to use this package is to require the provided `bootstrap.php` file or an equivalent *instead of* the typical `vendor/autoload.php` file.
 30 | 
 31 | This will use an instance of `Bootstrapper` (see below) by default, but you can provide another implementation by using the `$_SERVER['APP_BOOTSTRAPPER']` variable.
 32 | When provided, `$_SERVER['APP_BOOTSTRAPPER']` should be set to a class name or an instance of `BootstrapperInterface` that will be used to run the app.
 33 | 
 34 | By design, requiring the `bootstrap.php` file *after* the `vendor/autoload.php` one will *not* do anything.
 35 | This allows requiring your front-controller several times without any side-effect.
 36 | 
 37 | If you are in the context of a Symfony app, you can include the `symfony-bootstrap.php` file instead,
 38 | which sets `$_SERVER['APP_BOOTSTRAPPER']` to `SymfonyBootstrapper`, adding common Symfony bootstrapping logic to the process:
 39 | 
 40 |  - `.env` files are always loaded if they are found in the root dir of your app;
 41 |  - PHP warnings and notices are turned into `ErrorException`;
 42 |  - the `APP_ENV` and the `APP_DEBUG` environement variables are used to configure the mode in which the app should run;
 43 |  - on the command line, `-e|--env` allows forcing a specific value for `APP_ENV` and `--no-debug` allows forcing `APP_DEBUG` to `0`.
 44 | 
 45 | Example
 46 | -------
 47 | 
 48 | Take a Symfony default skeleton and require `tchwork/bootstrapper`:
 49 | ```sh
 50 | symfony new test-app --version=dev-master # Symfony 5.1 works best for the example
 51 | cd test-app/
 52 | composer require tchwork/bootstrapper:@dev
 53 | ```
 54 | 
 55 | Replace the content of the `public/index.php` file by:
 56 | ```php
 57 | <?php
 58 | 
 59 | use App\Kernel;
 60 | 
 61 | require_once dirname(__DIR__).'/vendor/tchwork/bootstrapper/symfony-bootstrap.php';
 62 | 
 63 | return function (array $context) {
 64 |     return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
 65 | };
 66 | ```
 67 | 
 68 | And the content of the `bin/console` file by:
 69 | ```php
 70 | #!/usr/bin/env php
 71 | <?php
 72 | 
 73 | use App\Kernel;
 74 | use Symfony\Bundle\FrameworkBundle\Console\Application;
 75 | 
 76 | require_once dirname(__DIR__).'/vendor/tchwork/bootstrapper/symfony-bootstrap.php';
 77 | 
 78 | return function (array $context) {
 79 |     $kernel = new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
 80 | 
 81 |     return new Application($kernel);
 82 | };
 83 | ```
 84 | 
 85 | Profit.
 86 | 
 87 | The closures are going to be called automatically.
 88 | The `$context` argument will be provided with the `$_SERVER` superglobal, augmented with the values found in `.env` files.
 89 | The return value will be handled automatically using generic handlers.
 90 | 
 91 | Try also this front controller, e.g. `public/hello.php`:
 92 | ```php
 93 | <?php
 94 | 
 95 | use Symfony\Component\HttpFoundation\Request;
 96 | use Symfony\Component\HttpFoundation\Response;
 97 | 
 98 | require_once dirname(__DIR__).'/vendor/tchwork/bootstrapper/symfony-bootstrap.php';
 99 | 
100 | return function (Request $request) {
101 |     return new Response('Hello World!');
102 | };
103 | ```
104 | 
105 | The `$request` argument will be created automatically from superglobals and the returned response will be sent as expected.
106 | 
107 | The mechanism to create the arguments and handle the return value can be configured to deal with any kind of objects.
108 | 
109 | Extensibility
110 | -------------
111 | 
112 | This section describes the extensibility mechanism supported by `Bootstrapper`.
113 | You can provide any other mechanism by implementing `BootstrapperInterface`.
114 | 
115 | `Bootstrapper` builds on two simple conventions to provide argument resolvers and return value handlers:
116 | 
117 |  - to create an argument for a class/interface named `MyNamespace\InputObject`,
118 |    create a derived class with the `Tchwork\Bootstrapper\` prefix and the `Singleton` suffix.
119 |    Then, implement a static method `get()` on that class. It should return the object computed from global state:
120 |    ```php
121 |    namespace Tchwork\Bootstrapper\MyNamespace
122 | 
123 |    use MyNamespace\InputObject;
124 | 
125 |    class InputObjectSingleton
126 |    {
127 |        private static $inputObject;
128 | 
129 |        public static function get(): InputObject
130 |        {
131 |            return self::$inputObject ?? self::$inputObject = new InputObject();
132 |        }
133 |    }
134 |    ```
135 | 
136 |  - to handle a return value of type `MyNamespace\OutputObject`, create a class with the `Handler` suffix and a `handle()` method:
137 |    ```php
138 |    namespace Tchwork\Bootstrapper\MyNamespace
139 | 
140 |    use MyNamespace\OutputObject;
141 | 
142 |    class OutputObjectHandler
143 |    {
144 |        public static function handle(OutputObject $outputObject): int
145 |        {
146 |            // do something with $outputObject
147 | 
148 |            return 0; // the method shall return the exit status code - 0 means successfull
149 |        }
150 |    }
151 |    ```
152 | 
153 | This package already provides some for the Symfony component.
154 | Check their source code for inspiration.
155 | 
156 | Please give it a try and tell me what you think about it!
157 | 
158 | Protip: adding `auto_prepend_file=/path/to/your-bootstrap.php` to your `php.ini` file allows removing the `require` statements in the examples.
159 | 


--------------------------------------------------------------------------------
/bootstrap.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | use Tchwork\Bootstrapper\Bootstrapper;
 4 | 
 5 | if (true === require_once dirname(__DIR__, 2).'/autoload.php') {
 6 |     return;
 7 | }
 8 | 
 9 | if (!isset($_SERVER['APP_BOOTSTRAPPER'])) {
10 |     $_SERVER['APP_BOOTSTRAPPER'] = new Bootstrapper();
11 | } elseif (is_string($_SERVER['APP_BOOTSTRAPPER'])) {
12 |     $_SERVER['APP_BOOTSTRAPPER'] = new $_SERVER['APP_BOOTSTRAPPER']();
13 | }
14 | 
15 | if (1 === $closure = require $_SERVER['SCRIPT_FILENAME']) {
16 |     exit(0);
17 | }
18 | 
19 | [$closure, $arguments] = $_SERVER['APP_BOOTSTRAPPER']->getRuntime($closure);
20 | $result = $closure(...$arguments);
21 | $closure = $_SERVER['APP_BOOTSTRAPPER']->getHandler($result, $closure, $arguments);
22 | 
23 | exit($closure($result));
24 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "tchwork/bootstrapper",
 3 |     "description": "Takes care of booting your app from global state provided by the engine",
 4 |     "type": "library",
 5 |     "license": "MIT",
 6 |     "authors": [
 7 |         {
 8 |             "name": "Nicolas Grekas",
 9 |             "email": "p@tchwork.com"
10 |         }
11 |     ],
12 |     "autoload": {
13 |         "psr-4": {
14 |             "Tchwork\\Bootstrapper\\": "src/"
15 |         }
16 |     },
17 |     "require": {
18 |         "php": ">=7.2.5"
19 |     },
20 |     "suggest": {
21 |         "symfony/dotenv": "To use the SymfonyBootstrapper",
22 |         "symfony/error-handler": "To use the SymfonyBootstrapper"
23 |     },
24 |     "extra": {
25 |         "branch-alias": {
26 |             "dev-master": "1.0-dev"
27 |         }
28 |     }
29 | }
30 | 


--------------------------------------------------------------------------------
/src/Bootstrapper.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Tchwork\Bootstrapper;
 4 | 
 5 | class Bootstrapper implements BootstrapperInterface
 6 | {
 7 |     public function getRuntime(\Closure $closure): array
 8 |     {
 9 |         $arguments = [];
10 | 
11 |         foreach ((new \ReflectionFunction($closure))->getParameters() as $parameter) {
12 |             $class = 'Tchwork\Bootstrapper\\'.$parameter->getType()->getName().'Singleton';
13 | 
14 |             if ('Tchwork\Bootstrapper\arraySingleton' === $class) {
15 |                 $arguments[] = $_SERVER;
16 |                 continue;
17 |             }
18 | 
19 |             if (class_exists($class)) {
20 |                 $arguments[] = $class::get();
21 |                 continue;
22 |             }
23 | 
24 |             $arguments[] = null;
25 |         }
26 | 
27 |         return [$closure, $arguments];
28 |     }
29 | 
30 |     public function getHandler(object $result, \Closure $closure, array $arguments): callable
31 |     {
32 |         $class = \get_class($result);
33 | 
34 |         if (class_exists($c = 'Tchwork\Bootstrapper\\'.$class.'Handler')) {
35 |             return [$c, 'handle'];
36 |         }
37 | 
38 |         foreach (class_parents($class) as $c) {
39 |             if (class_exists($c = 'Tchwork\Bootstrapper\\'.$c.'Handler')) {
40 |                 return [$c, 'handle'];
41 |             }
42 |         }
43 | 
44 |         foreach (class_implements($class) as $c) {
45 |             if (class_exists($c = 'Tchwork\Bootstrapper\\'.$c.'Handler')) {
46 |                 return [$c, 'handle'];
47 |             }
48 |         }
49 | 
50 |         return static function (object $result): int {
51 |             echo 'The runtime returned an unsupported value of type '.$class.".\n";
52 | 
53 |             return 1;
54 |         };
55 |     }
56 | }
57 | 


--------------------------------------------------------------------------------
/src/BootstrapperInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Tchwork\Bootstrapper;
 4 | 
 5 | interface BootstrapperInterface
 6 | {
 7 |     /**
 8 |      * Returns a closure and its arguments; they will run the main code.
 9 |      */
10 |     public function getRuntime(\Closure $closure): array;
11 | 
12 |     /**
13 |      * Returns a handler that can deal with the result provided by the runtime.
14 |      */
15 |     public function getHandler(object $result, \Closure $closure, array $arguments): callable;
16 | }
17 | 


--------------------------------------------------------------------------------
/src/Symfony/Component/Console/ApplicationHandler.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Tchwork\Bootstrapper\Symfony\Component\Console;
 4 | 
 5 | use Symfony\Component\Console\Application;
 6 | 
 7 | /**
 8 |  * @internal
 9 |  */
10 | class ApplicationHandler
11 | {
12 |     public static function handle(Application $app): int
13 |     {
14 |         if (!\in_array(\PHP_SAPI, ['cli', 'phpdbg', 'embed'], true)) {
15 |             echo 'Warning: The console should be invoked via the CLI version of PHP, not the '.\PHP_SAPI.' SAPI'.\PHP_EOL;
16 |         }
17 | 
18 |         set_time_limit(0);
19 | 
20 |         return $app->run(Input\InputInterfaceSingleton::get(), Output\OutputInterfaceSingleton::get());
21 |     }
22 | }
23 | 


--------------------------------------------------------------------------------
/src/Symfony/Component/Console/Input/InputInterfaceSingleton.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Tchwork\Bootstrapper\Symfony\Component\Console\Input;
 4 | 
 5 | use Symfony\Component\Console\Input\ArgvInput;
 6 | use Symfony\Component\Console\Input\InputInterface;
 7 | 
 8 | /**
 9 |  * @internal
10 |  */
11 | final class InputInterfaceSingleton
12 | {
13 |     private static $input;
14 | 
15 |     public static function get(): InputInterface
16 |     {
17 |         if (self::$input) {
18 |             return self::$input;
19 |         }
20 | 
21 |         $input = new ArgvInput();
22 | 
23 |         if (null !== $env = $input->getParameterOption(['--env', '-e'], null, true)) {
24 |             putenv('APP_ENV='.$_SERVER['APP_ENV'] = $_ENV['APP_ENV'] = $env);
25 |         }
26 | 
27 |         if ($input->hasParameterOption('--no-debug', true)) {
28 |             putenv('APP_DEBUG='.$_SERVER['APP_DEBUG'] = $_ENV['APP_DEBUG'] = '0');
29 |         }
30 | 
31 |         return self::$input = $input;
32 |     }
33 | }
34 | 


--------------------------------------------------------------------------------
/src/Symfony/Component/Console/Output/OutputInterfaceSingleton.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Tchwork\Bootstrapper\Symfony\Component\Console\Output;
 4 | 
 5 | use Symfony\Component\Console\Output\ConsoleOutput;
 6 | use Symfony\Component\Console\Output\OutputInterface;
 7 | 
 8 | /**
 9 |  * @internal
10 |  */
11 | final class OutputInterfaceSingleton
12 | {
13 |     private static $output;
14 | 
15 |     public static function get(): OutputInterface
16 |     {
17 |         return self::$output ?? self::$output = new ConsoleOutput();
18 |     }
19 | }
20 | 


--------------------------------------------------------------------------------
/src/Symfony/Component/HttpFoundation/RequestSingleton.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Tchwork\Bootstrapper\Symfony\Component\HttpFoundation;
 4 | 
 5 | use Symfony\Component\HttpFoundation\Request;
 6 | 
 7 | /**
 8 |  * @internal
 9 |  */
10 | final class RequestSingleton
11 | {
12 |     private static $request;
13 | 
14 |     public static function get(): Request
15 |     {
16 |         return self::$request ?? self::$request = Request::createFromGlobals();
17 |     }
18 | }
19 | 


--------------------------------------------------------------------------------
/src/SymfonyBootstrapper.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Tchwork\Bootstrapper;
 4 | 
 5 | use Symfony\Component\Console\Input\ArgvInput;
 6 | use Symfony\Component\Dotenv\Dotenv;
 7 | use Symfony\Component\ErrorHandler\Debug;
 8 | use Symfony\Component\ErrorHandler\ErrorHandler;
 9 | use Symfony\Component\HttpFoundation\Response;
10 | use Symfony\Component\HttpKernel\HttpKernelInterface;
11 | use Symfony\Component\HttpKernel\TerminableInterface;
12 | use Tchwork\Bootstrapper\Symfony\Component\Console\Input\InputInterfaceSingleton;
13 | use Tchwork\Bootstrapper\Symfony\Component\HttpFoundation\RequestSingleton;
14 | 
15 | // Help opcache.preload discover always-needed symbols
16 | class_exists(RequestSingleton::class);
17 | 
18 | if (!class_exists(Dotenv::class)) {
19 |     throw new \LogicException(sprintf('You cannot use "%s" as the Dotenv component is not installed. Try running "composer require symfony/dotenv".', SymfonyBootstrapper::class));
20 | }
21 | 
22 | if (!class_exists(ErrorHandler::class)) {
23 |     throw new \LogicException(sprintf('You cannot use "%s" as the ErrorHandler component is not installed. Try running "composer require symfony/error-handler".', SymfonyBootstrapper::class));
24 | }
25 | 
26 | class SymfonyBootstrapper extends Bootstrapper
27 | {
28 |     public function __construct(string $projectDir = null)
29 |     {
30 |         $projectDir = $projectDir ?? \dirname(__DIR__, 4);
31 | 
32 |         if (isset($_SERVER['argv']) && class_exists(ArgvInput::class)) {
33 |             InputInterfaceSingleton::get();
34 |         }
35 | 
36 |         (new Dotenv())->bootEnv($projectDir.'/.env');
37 | 
38 |         if ($_SERVER['APP_DEBUG']) {
39 |             umask(0000);
40 |             Debug::enable();
41 |         } else {
42 |             ErrorHandler::register();
43 |         }
44 |     }
45 | 
46 |     public function getHandler(object $result, \Closure $closure, array $arguments): callable
47 |     {
48 |         if ($result instanceof HttpKernelInterface) {
49 |             return static function ($kernel) {
50 |                 $request = RequestSingleton::get();
51 |                 $response = $kernel->handle($request);
52 |                 $response->send();
53 | 
54 |                 if ($kernel instanceof TerminableInterface) {
55 |                     $kernel->terminate($request, $response);
56 |                 }
57 | 
58 |                 return 0;
59 |             };
60 |         }
61 | 
62 |         if ($result instanceof Response) {
63 |             return static function ($response) {
64 |                 $response->send();
65 | 
66 |                 return 0;
67 |             };
68 |         }
69 | 
70 |         return parent::getHandler($result, $closure, $arguments);
71 |     }
72 | }
73 | 


--------------------------------------------------------------------------------
/symfony-bootstrap.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | use Tchwork\Bootstrapper\SymfonyBootstrapper;
 4 | 
 5 | if (!isset($_SERVER['APP_BOOTSTRAPPER'])) {
 6 |     $_SERVER['APP_BOOTSTRAPPER'] = SymfonyBootstrapper::class;
 7 | }
 8 | 
 9 | require __DIR__.'/bootstrap.php';
10 | 


--------------------------------------------------------------------------------