From 7388cc941f0c6bf084ecfe4de2cfb025fc00047b Mon Sep 17 00:00:00 2001 From: Nyholm Date: Tue, 9 Mar 2021 18:34:08 +0100 Subject: [PATCH 1/5] Init Runtime docs --- components/runtime.rst | 417 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 417 insertions(+) create mode 100644 components/runtime.rst diff --git a/components/runtime.rst b/components/runtime.rst new file mode 100644 index 00000000000..760b10397a4 --- /dev/null +++ b/components/runtime.rst @@ -0,0 +1,417 @@ +.. 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. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/runtime + +.. include:: /components/require_autoload.rst.inc + +Usage +----- + +The Runtime component allows you to write front-controllers in a generic way +and with use of configuration you may change the behavior. Let's consider the +``public/index.php`` as an example. It will return a callable which will create +and return the application:: + + handle(Request::createFromGlobals())->send()``. + +To make a console application, the same 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; + }; + +``:class:`Symfony\\Component\\Runtime\\RunnerInterface``` + The ``RuntimeInterface`` is a way to use a custom application with the + generic Runtime.:: + + '/var/task', + ]; + + require_once dirname(__DIR__).'/vendor/autoload_runtime.php'; + + // ... + +The second way to pass an option to ``SymfonyRuntime::__construct()`` is to use +``extra.runtime.options`` in ``composer.json``. + +.. code-block:: json + + { + "require": { + "...": "..." + }, + "extra": { + "runtime": { + "options": { + "project_dir": "/var/task" + } + } + } + } + +.. note:: + + The environment variable ``APP_DEBUG`` has special support to easily + turn on and off debugging. + +Creating 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 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: + + 1. The main entry point returns a callable (A) that wraps the application + 2. Callable (A) is passed to ``RuntimeInterface::getResolver()``, which returns a + ``ResolverInterface``. This resolver returns an array with the callable (A) + (or something that decorates the callable (A)) at index 0, and all its resolved + arguments at index 1. + 3. The callable A is invoked with its arguments, it will return an object that + represents the application (B). + 4. That object (B) is passed to ``RuntimeInterface::getRunner()``, which returns a + ``RunnerInterface``: an instance that knows how to "run" the object (B). + 5. The ``RunnerInterface::run($objectB)`` is executed and it returns the exit status + code as `int`. + 6. 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? + +To create a runtime for ReactPHP, we see that no special arguments are typically +required. We will use the standard arguments provided by :class:`Symfony\\Component\\Runtime\\GenericRuntime` +by extending tha class. But 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 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 = \React\EventLoop\Factory::create(); + + $server = new \React\Http\Server($loop, function (ServerRequestInterface $request) use ($application) { + return $application->handle($request); + }); + + $socket = new \React\Socket\Server($this->port, $loop); + $server->listen($socket); + + $loop->run(); + + return 0; + } + } + +Now we should create a new :class:`Symfony\\Component\\Runtime\\RuntimeInterface` +that is using our ``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); + } + + return parent::getRunner($application); + } + } + +The end user will now be able to create front controller like:: + + require_once dirname(__DIR__).'/vendor/autoload_runtime.php'; + + return function (array $context) { + return new Psr15Application(); + }; + + From 06414b72271a50303eaf138a8bc7c50b4ab0fdc2 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Fri, 12 Mar 2021 11:47:32 +0100 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Oskar Stark --- components/runtime.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/components/runtime.rst b/components/runtime.rst index 760b10397a4..86e3814ee0c 100644 --- a/components/runtime.rst +++ b/components/runtime.rst @@ -65,7 +65,7 @@ Selecting Runtimes The default Runtime is :class:`Symfony\\Component\\Runtime\\SymfonyRuntime`, it works excellent on most applications running with a webserver like Nginx and Apache, and PHP-FPM. You may change Runtime to :class:`Symfony\\Component\\Runtime\\GenericRuntime` -or a custom Runtime for Swoole or Aws Lambda. This can be done by specifying the +or a custom Runtime for Swoole or AWS Lambda. This can be done by specifying the Runtime class in the ``APP_RUNTIME`` environment variable or to specify the ``extra.runtime.class`` in ``composer.json``. @@ -82,8 +82,8 @@ Runtime class in the ``APP_RUNTIME`` environment variable or to specify the } } -Using SymfonyRuntime --------------------- +Using the SymfonyRuntime +------------------------ The :class:`Symfony\\Component\\Runtime\\RuntimeInterface` has two methods. One to get an instance of :class:`Symfony\\Component\\Runtime\\ResolverInterface` @@ -309,8 +309,8 @@ The second way to pass an option to ``SymfonyRuntime::__construct()`` is to use The environment variable ``APP_DEBUG`` has special support to easily turn on and off debugging. -Creating Your Own Runtime -------------------------- +Create Your Own Runtime +----------------------- This is an advanced topic that describes the internals of the Runtime component. @@ -319,7 +319,7 @@ could be versioned as a part of a normal package. If the application author deci to use this component, the package maintainer of the Runtime class will have more control and can fix bugs and add features. --- note:: +.. note:: Before Symfony 5.3, the boostrap logic was part of a Flex recipe. Since recipes are rarely updated by users, bug patches would rarely be installed. @@ -413,5 +413,3 @@ The end user will now be able to create front controller like:: return function (array $context) { return new Psr15Application(); }; - - From e7bacf17fae9eee8223b24a302bd1695ffefe913 Mon Sep 17 00:00:00 2001 From: Tobias Nyholm Date: Tue, 16 Mar 2021 08:57:48 +0100 Subject: [PATCH 3/5] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ondřej Frei <37588173+freiondrej@users.noreply.github.com> --- components/runtime.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/runtime.rst b/components/runtime.rst index 86e3814ee0c..9c868bdc05b 100644 --- a/components/runtime.rst +++ b/components/runtime.rst @@ -41,7 +41,7 @@ the autoload files since the component includes a composer plugin. The ``autoloa will instantiate a :class:`Symfony\\Component\\Runtime\\RuntimeInterface`, its job is to take the callable and resolve the arguments (``array $context``). Then it calls the callable to get the application ``App\Kernel``. At last it will run the application, -ie calling ``$kernel->handle(Request::createFromGlobals())->send()``. +i.e. calling ``$kernel->handle(Request::createFromGlobals())->send()``. To make a console application, the same bootstrap code would look like:: From 76de97372b3fde4f2472b836542649bdef30a1fe Mon Sep 17 00:00:00 2001 From: Wouter de Jong Date: Mon, 5 Apr 2021 14:22:59 +0200 Subject: [PATCH 4/5] [#15081] Finish the new Runtime docs --- .doctor-rst.yaml | 1 + components/runtime.rst | 287 ++++++++++++++++++++++++++--------------- 2 files changed, 182 insertions(+), 106 deletions(-) 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 index 9c868bdc05b..ae962dd18cb 100644 --- a/components/runtime.rst +++ b/components/runtime.rst @@ -7,7 +7,11 @@ 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. + Swoole, etc. without any changes. + +.. versionadded:: 5.3 + + The Runtime component was introduced in Symfony 5.3. Installation ------------ @@ -21,10 +25,10 @@ Installation Usage ----- -The Runtime component allows you to write front-controllers in a generic way -and with use of configuration you may change the behavior. Let's consider the -``public/index.php`` as an example. It will return a callable which will create -and return the application:: +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()``. +So how does this front-controller work? At first, the special +``autoload_runtime.php`` is automatically created by the Composer plugin in +the component. This file runs the following logic: + +#. It instantiates a :class:`Symfony\\Component\\Runtime\\RuntimeInterface`; +#. The callable (returned in the file) is passed to the Runtime, whose job + is to resolve the arguments (in this example: ``array $content``); +#. Then, this callable is called to get the application (``App\Kernel``); +#. At last, the Runtime is used to run the application (i.e. calling + ``$kernel->handle(Request::createFromGlobals())->send()``). -To make a console application, the same bootstrap code would look like:: +To make a console application, the bootstrap code would look like:: #!/usr/bin/env php application; - $loop = \React\EventLoop\Factory::create(); + $loop = ReactFactory::create(); - $server = new \React\Http\Server($loop, function (ServerRequestInterface $request) use ($application) { - return $application->handle($request); - }); + // configure ReactPHP to correctly handle the PSR-15 application + $server = new ReactHttpServer( + $loop, + function (ServerRequestInterface $request) use ($application) { + return $application->handle($request); + } + ); - $socket = new \React\Socket\Server($this->port, $loop); + // start the ReactPHP server + $socket = new ReactSocketServer($this->port, $loop); $server->listen($socket); $loop->run(); @@ -380,8 +448,8 @@ to run. That logic is added in a new class implementing :class:`Symfony\\Compone } } -Now we should create a new :class:`Symfony\\Component\\Runtime\\RuntimeInterface` -that is using our ``ReactPHPRunner``:: +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; @@ -402,14 +470,21 @@ that is using our ``ReactPHPRunner``:: 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:: + Date: Mon, 5 Apr 2021 18:55:04 +0200 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Denis Brumann --- components/runtime.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/components/runtime.rst b/components/runtime.rst index ae962dd18cb..dc745adb5c6 100644 --- a/components/runtime.rst +++ b/components/runtime.rst @@ -45,7 +45,7 @@ So how does this front-controller work? At first, the special the component. This file runs the following logic: #. It instantiates a :class:`Symfony\\Component\\Runtime\\RuntimeInterface`; -#. The callable (returned in the file) is passed to the Runtime, whose job +#. The callable (returned by ``public/index.php``) is passed to the Runtime, whose job is to resolve the arguments (in this example: ``array $content``); #. Then, this callable is called to get the application (``App\Kernel``); #. At last, the Runtime is used to run the application (i.e. calling @@ -107,7 +107,7 @@ Use the ``APP_RUNTIME`` environment variable or by specifying the Using the Runtime ----------------- -A Runtime is resposible for passing arguments into the closure and run the +A Runtime is responsible for passing arguments into the closure and run the application returned by the closure. The :class:`Symfony\\Component\\Runtime\\SymfonyRuntime` and :class:`Symfony\\Component\\Runtime\\GenericRuntime` supports a number of arguments and different applications that you can use in your @@ -245,7 +245,7 @@ The ``GenericRuntime`` and ``SymfonyRuntime`` also support these generic applications: :class:`Symfony\\Component\\Runtime\\RunnerInterface` - The ``RuntimeInterface`` is a way to use a custom application with the + The ``RunnerInterface`` is a way to use a custom application with the generic Runtime::