diff --git a/.doctor-rst.yaml b/.doctor-rst.yaml index 61b56614a29..388147a8281 100644 --- a/.doctor-rst.yaml +++ b/.doctor-rst.yaml @@ -101,3 +101,4 @@ whitelist: - 'provides a ``loginUser()`` method to simulate logging in in your functional' - '.. code-block:: twig' - '.. versionadded:: 3.6' # MonologBundle + - '// bin/console' diff --git a/components/runtime.rst b/components/runtime.rst new file mode 100644 index 00000000000..dc745adb5c6 --- /dev/null +++ b/components/runtime.rst @@ -0,0 +1,490 @@ +.. index:: + single: Runtime + single: Components; Runtime + +The Runtime Component +====================== + + The Runtime Component decouples the bootstrapping logic from any global state + to make sure the application can run with runtimes like PHP-FPM, ReactPHP, + Swoole, etc. without any changes. + +.. versionadded:: 5.3 + + The Runtime component was introduced in Symfony 5.3. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/runtime + +.. include:: /components/require_autoload.rst.inc + +Usage +----- + +The Runtime component abstracts most bootstrapping logic as so-called +*runtimes*, allowing you to write front-controllers in a generic way. +For instance, the Runtime component allows Symfony's ``public/index.php`` +to look like this:: + + handle(Request::createFromGlobals())->send()``). + +To make a console application, the bootstrap code would look like:: + + #!/usr/bin/env php + setCode(function (InputInterface $input, OutputInterface $output) { + $output->write('Hello World'); + }); + + return $command; + }; + +:class:`Symfony\\Component\\Console\\Application` + Useful with console applications with more than one command. This will use the + :class:`Symfony\\Component\\Runtime\\Runner\\Symfony\\ConsoleApplicationRunner``:: + + setCode(function (InputInterface $input, OutputInterface $output) { + $output->write('Hello World'); + }); + + $app = new Application(); + $app->add($command); + $app->setDefaultCommand('hello', true); + + return $app; + }; + +The ``GenericRuntime`` and ``SymfonyRuntime`` also support these generic +applications: + +:class:`Symfony\\Component\\Runtime\\RunnerInterface` + The ``RunnerInterface`` is a way to use a custom application with the + generic Runtime:: + + '/var/task', + ]; + + require_once dirname(__DIR__).'/vendor/autoload_runtime.php'; + + // ... + +You can also configure ``extra.runtime.options`` in ``composer.json``: + +.. code-block:: json + + { + "require": { + "...": "..." + }, + "extra": { + "runtime": { + "options": { + "project_dir": "/var/task" + } + } + } + } + +The following options are supported by the ``SymfonyRuntime``: + +``env`` (default: ``APP_ENV`` environment variable, or ``"dev"``) + To define the name of the environment the app runs in. +``disable_dotenv`` (default: ``false``) + To disable looking for ``.env`` files. +``dotenv_path`` (default: ``.env``) + To define the path of dot-env files. +``use_putenv`` + To tell Dotenv to set env vars using ``putenv()`` (NOT RECOMMENDED). +``prod_envs`` (default: ``["prod"]``) + To define the names of the production envs. +``test_envs`` (default: ``["test"]``) + To define the names of the test envs. + +Besides these, the ``GenericRuntime`` and ``SymfonyRuntime`` also support +these options: + +``debug`` (default: ``APP_DEBUG`` environment variable, or ``true``) + Toggles displaying errors. +``runtimes`` + Maps "application types" to a ``GenericRuntime`` implementation that + knows how to deal with each of them. +``error_handler`` (default: :class:`Symfony\\Component\\Runtime\\Internal\\BasicErrorHandler` or :class:`Symfony\\Component\\Runtime\\Internal\\SymfonyErrorHandler` for ``SymfonyRuntime``) + Defines the class to use to handle PHP errors. + +Create Your Own Runtime +----------------------- + +This is an advanced topic that describes the internals of the Runtime component. + +Using the Runtime component will benefit maintainers because the bootstrap +logic could be versioned as a part of a normal package. If the application +author decides to use this component, the package maintainer of the Runtime +class will have more control and can fix bugs and add features. + +.. note:: + + Before Symfony 5.3, the Symfony boostrap logic was part of a Flex recipe. + Since recipes are rarely updated by users, bug patches would rarely be + installed. + +The Runtime component is designed to be totally generic and able to run any +application outside of the global state in 6 steps: + +#. The main entry point returns a *callable* (the "app") that wraps the application; +#. The *app callable* is passed to ``RuntimeInterface::getResolver()``, which returns + a :class:`Symfony\\Component\\Runtime\\ResolverInterface`. This resolver returns + an array with the app callable (or something that decorates this callable) at + index 0 and all its resolved arguments at index 1. +#. The *app callable* is invoked with its arguments, it will return an object that + represents the application. +#. This *application object* is passed to ``RuntimeInterface::getRunner()``, which + returns a :class:`Symfony\\Component\\Runtime\\RunnerInterface`: an instance + that knows how to "run" the appliction object. +#. The ``RunnerInterface::run(object $application)`` is called and it returns the + exit status code as `int`. +#. The PHP engine is exited with this status code. + +When creating a new runtime, there are two things to consider: First, what arguments +will the end user use? Second, what will the user's application look like? + +For instance, imagine you want to create a runtime for `ReactPHP`_: + +**What arguments will the end user use?** + +For a generic ReactPHP application, no special arguments are +typically required. This means that you can use the +:class:`Symfony\\Component\\Runtime\\GenericRuntime`. + +**What will the user's application look like?** + +There is also no typical React application, so you might want to rely on +the `PSR-15`_ interfaces for HTTP request handling. + +However, a ReactPHP application will need some special logic to *run*. That logic +is added in a new class implementing :class:`Symfony\\Component\\Runtime\\RunnerInterface`:: + + use Psr\Http\Message\ServerRequestInterface; + use Psr\Http\Server\RequestHandlerInterface; + use React\EventLoop\Factory as ReactFactory; + use React\Http\Server as ReactHttpServer; + use React\Socket\Server as ReactSocketServer; + use Symfony\Component\Runtime\RunnerInterface; + + class ReactPHPRunner implements RunnerInterface + { + private $application; + private $port; + + public function __construct(RequestHandlerInterface $application, int $port) + { + $this->application = $application; + $this->port = $port; + } + + public function run(): int + { + $application = $this->application; + $loop = ReactFactory::create(); + + // configure ReactPHP to correctly handle the PSR-15 application + $server = new ReactHttpServer( + $loop, + function (ServerRequestInterface $request) use ($application) { + return $application->handle($request); + } + ); + + // start the ReactPHP server + $socket = new ReactSocketServer($this->port, $loop); + $server->listen($socket); + + $loop->run(); + + return 0; + } + } + +By extending the ``GenericRuntime``, you make sure that the application is +always using this ``ReactPHPRunner``:: + + use Symfony\Component\Runtime\GenericRuntime; + use Symfony\Component\Runtime\RunnerInterface; + + class ReactPHPRuntime extends GenericRuntime + { + private $port; + + public function __construct(array $options) + { + $this->port = $options['port'] ?? 8080; + parent::__construct($options); + } + + public function getRunner(?object $application): RunnerInterface + { + if ($application instanceof RequestHandlerInterface) { + return new ReactPHPRunner($application, $this->port); + } + + // if it's not a PSR-15 application, use the GenericRuntime to + // run the application (see "Resolvable Applications" above) + return parent::getRunner($application); + } + } + +The end user will now be able to create front controller like:: + +