-
-
Notifications
You must be signed in to change notification settings - Fork 5.2k
[Runtime] Init Runtime component #15081
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Hi @Nyholm. Thanks for your enthusiasm regarding this new component. However, we're working hard on removing standalone component documentation... I think there are topics that are relevant in the framework-usage context:
And we surely also need to somehow document its standalone usage, but I'm not sure if we should add new articles to the Before you continue here, let's discuss with the @symfony/team-symfony-docs how to document this new component. |
Oh, And here I am adding new pages =) I started this work by adding a I'll wait for some opinions and guidance. |
…m global state (nicolas-grekas) This PR was merged into the 5.3-dev branch. Discussion ---------- [Runtime] a new component to decouple applications from global state | Q | A | ------------- | --- | Branch? | 5.x | Bug fix? | no | New feature? | yes | Deprecations? | no | Tickets | - | License | MIT | Doc PR | symfony/symfony-docs#15081 Follow up of #36652, see discussion there. What if we could decouple the bootstrapping logic of our apps from any global state? This PR makes it possible via a new proposed `symfony/runtime` component. The immediate benefit this provides is easier maintenance of Symfony apps: code that is currently shipped by recipes will be able to move to `vendor/`. Read the previous sentence twice, this is big :) Check the following PR to see how far this goes: symfony/recipes#787 The longer-term benefit is being able to run the exact same app under several runtimes: PHP-FPM, CLI, but also PHP-PM and similar. Thanks to the proposed interface, this benefit could span to any PHP apps; not only to apps using the Symfony HttpKernel/HttpFoundation components. This part could be moved to `symfony/contracts` in the future. Performance-wise, I measured no significant difference with the current way of running apps. RuntimeInterface ---------------- The core of this component is the `RuntimeInterface` which describes a high-order runtime logic. It 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 that wraps the application; 2. this callable is passed to `RuntimeInterface::getResolver()`, which returns a `ResolverInterface`; this resolver returns an array with the (potentially decorated) callable at index 0, and all its resolved arguments at index 1; 3. the callable is invoked with its arguments; it returns an object that represents the application; 4. that object is passed to `RuntimeInterface::getRunner()`, which returns a `RunnerInterface`: an instance that knows how to "run" the object; 5. that instance is `run()` and returns the exit status code as `int`; 6. the PHP engine is exited with this status code. This process is extremely flexible as it allows implementations of `RuntimeInterface` to hook into any critical steps. Autoloading ----------- This package registers itself as a Composer plugin to generate a `vendor/autoload_runtime.php` file. This file shall be required instead of the usual `vendor/autoload.php` in front-controllers that leverage this component and return a callable. Before requiring the `vendor/autoload_runtime.php` file, set the `$_SERVER['APP_RUNTIME']` variable to a class that implements `RuntimeInterface` and that should be used to run the returned callable. Alternatively, the class of the runtime can be defined in the `extra.runtime.class` entry of the `composer.json` file. A `SymfonyRuntime` is used by default. It knows the conventions to run Symfony and native PHP applications. Examples -------- This `public/index.php` is a "Hello World" that handles a "name" query parameter: ```php <?php require_once dirname(__DIR__).'/vendor/autoload_runtime.php'; return function (array $request, array $context): void { // $request holds keys "query", "body", "files" and "session", // which map to $_GET, $_POST, $_FILES and &$_SESSION respectively // $context maps to $_SERVER $name = $request['query']['name'] ?? 'World'; $time = $context['REQUEST_TIME']; echo sprintf('Hello %s, the current Unix timestamp is %s.', $name, $time); }; ``` This `bin/console.php` is a single-command "Hello World" application (run `composer require symfony/console` before launching it): ```php <?php use Symfony\Component\Console\Command\Command; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Output\OutputInterface; require_once dirname(__DIR__).'/vendor/autoload_runtime.php'; return function (Command $command) { $command->addArgument('name', null, 'Who should I greet?', 'World'); return $command->setCode(function (InputInterface $input, OutputInterface $output) { $name = $input->getArgument('name'); $output->writeln(sprintf('Hello <comment>%s</>', $name)); }); }; ``` The `SymfonyRuntime` can resolve and handle many types related to the `symfony/http-foundation` and `symfony/console` components. Check its source code for more information. Commits ------- 61b32ab [Runtime] a new component to decouple applications from global state
As I was curious about the runtime component, I saw your comment @wouterj:
What will happen with the documentation of components like Filesystem, Process, Console, etc.? Will they only be documented for usage in the Symfony framework? |
We're still a bit experimenting with this concept (which is why most components also still have their standalone docs). The main issue is twofold: lots of docs are duplicate & many people are confused (as they end up in component docs, while using a component within the framework). For some simpler components, we've moved the standalone example to the README file instead: https://github.com/symfony/routing#getting-started For HTTP client, we've used tabs to separate framework and component usage: https://symfony.com/doc/current/http_client.html Process and Filesystem have very similar usage in framework and standalone (like HTTP client). Personally, I'm thinking they end up as a main guide that explains how to do the setup in the framework and their generic usage. Then the standalone set-up will be either an example in the README, or the tab-based examples of the HTTP client docs. Components like Runtime are especially difficult, as their main goal is to be a generic package that can be reused.. |
I have added Let me know if I should remove them. Also, DOCtor-RST is red because:
That is a false positive, I refer the file, not the command. |
This PR was merged into the 5.3-dev branch. Discussion ---------- [Runtime] Remove "docs" from readme | Q | A | ------------- | --- | Branch? | 5.x | Bug fix? | no | New feature? | no | Deprecations? | no | Tickets | | License | MIT | Doc PR | symfony/symfony-docs#15081 Make the readme of the Runtime component link to the docs. This PR is blocked by the doc PR. Commits ------- 6f4552f [Runtime] Remove "docs" from readme
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍
Thank you very much for the help. Im happy with this PR.
I suggest merging this PR now. That will give some docs for the new component and it will allow others to help with small fixes. We also need a github label for the component. |
I agree 👍
friendly ping @fabpot @nicolas-grekas, not sure how and who is responsible for the labels |
Label added |
Co-authored-by: Oskar Stark <oskarstark@googlemail.com>
Co-authored-by: Ondřej Frei <37588173+freiondrej@users.noreply.github.com>
Co-authored-by: Denis Brumann <dbrumann@gmail.com>
Thank you @Nyholm for all your time invested in this document! |
Wohoo. Thank you for all the reviews and help |
Sorry for being impatient. When (or how often) is the documentation rebuilt? I was expected to see the content here: https://symfony.com/doc/current/runtime.html |
@Nyholm you can find it here: https://symfony.com/doc/5.3/components/runtime.html (and the docs are rebuild every night) |
Lovely. Thank you! |
This is documentation for symfony/symfony#38465
The docs is focus on "how to use" instead of "how it works". I will add a "creating your own Runtime" which will include "how it works".
As you may notice. I use two concepts: "the callback" and "the application". The fact that "the application" can be a callback and will be wrapped in callbacks is irrelevant here. I found it much easier to understand this way.