RFC: App object to encapsulate global state and services

chillu commented 7 years ago

Acceptance Criteria

A kernel object exists, which can be easily overridden in user code, to control the boot process of any silverstripe application.
An application object exists, which can be easily overridden in user code, to control the execution of any request in a silverstripe application.
All components which make up the state of the Kernel object are available via Injector service, even if these components are initialised pre-config (including the Kernel itself).
Kernel has no static members.
The Kernel object can be nested (and un-nested), which internally nests all core services, as well as injector / config. However, this nesting is performed per-instance and not via static accessors as with config / injector.
Cookie, Requirements, Config::inst() and Injector::inst() functionality remains unaltered.
HTTPRequest is not a part of kernel, nor are any request-specific services.
Session should accessible through the HTTPRequest (no longer static).
Development experience should not be greatly adversely affected for classes which use the main core traits.
If a non-current instance of Injector / Config is ever invoked, it must raise a logic error to enforce application consistency.
The concept is applied to all core modules
The upgrade path is clearly documented

Excludes

Converting static methods on core classes to instance methods
Converting core classes to interfaces
Global variable state (e.g. $_SESSION, $_REQUEST) for initial implementation.

Notes

PSR-11 discourages the direct use of service locators in implementations
Symfony exposes services service locators (e.g. $this->app->get('my-dependency'))

RFC Versions

V1 by @sminnee - https://gist.github.com/sminnee/7fd620a026d551730a088d5e82e542f0
V2 by @tractorcow - https://gist.github.com/tractorcow/c0656a334c13eac8ae252610d226a1c6
V3 by @tractorcow / @chillu - https://gist.github.com/tractorcow/8be54d6b019412c037049c8caddf39eb
V4 by @tractorcow - https://gist.github.com/tractorcow/2bb76d12074b885b9b2923dafa07ae88

Tasks

[X] Agree on RFC and implementation goals
[x] Create new Kernel / Application interfaces and base classes
[X] Re-implement nesting and refactor injector / config manifests into CoreKernal
[x] Implement SilverStripe specific AppKernel to replace Core.php
[x] Refactor main.php into HTTPApplication (incl errorcontrolchain)
[x] Refactor cli-main.php to use new HTTPApplication (CLIApplication class is future-scope)
[x] Implement HTTPRequest::createFromEnviroment()
[x] Refactor Session instance to be a HTTPRequest member
[x] Ensure Director::test (or some equivalent) is still available
[x] Upgrading guide
[x] Documentation, including customising app in user code
[x] move ConfigureFromEnv.php into AppKernel::boot()
[x] Move is_running_tests() into Kernel
[x] lazy DB::connect()
[x] Upgrade unit tests

WIP branches

sminnee commented 7 years ago

Do we have to fix cookies (and everything else related to the controller stack) as part of this ticket? It feels like it's turning into a cascade of "fix everything annoying" ;-)

If I were to refactor cookie, I'd probably have a middleware that

builds a CookieJar object based on the cookie header of a request
- attaches it as an attribute to the request object
- after processing is compete, check for changes to the CookieJar object
- writes appropriate Set-Cookie headers to the response

However that's well beyond the scope of this card

tractorcow commented 7 years ago

I've had a discussion with @chillu and decided to update the scope of the request / response refactor.

https://gist.github.com/tractorcow/2bb76d12074b885b9b2923dafa07ae88

Cookies API remains unchanged, but we will move Session::inst() into $request->getSession().

chillu commented 7 years ago

Old ACs:

There is clear documentation on how to instantiate SS core classes and their dependencies (when to use new vs. dependency injection)
There is a way to replace dependencies during early bootstrap (e.g. caching layers initialised before injector kicks in)
Interoperability with other libraries is maintained by minimizing use of SS-specific references like Injector and Config in core classes
I can use smaller parts of SilverStripe without copying hundreds of lines of main.php and Core.php code in other controller stacks (e.g. Silex and Lumen). Note: This is an architectural goal, and doesn’t need to be operational as part of this card.
Configuration can easily be mocked directly on core class instances (without relying on Config::nest() global state)
It is clear which dependencies a class relies on without reading the entire class implementation
There are no directly overlapping APIs (DataModel method arguments)
The concept is applied to all core modules
The upgrade path is clearly documented

New ACs:

A kernel object exists, which can be easily overridden in user code, to control the boot process of any silverstripe application.
An application object exists, which can be easily overridden in user code, to control the execution of any request in a silverstripe application.
All components which make up the state of the Kernel object are available via Injector service, even if these components are initialised pre-config (including the Kernel itself).
Kernel has no static members.
The Kernel object can be nested (and un-nested), which internally nests all core services, as well as injector / config. However, this nesting is performed per-instance and not via static accessors as with config / injector.
Cookie, Requirements, Config::inst() and Injector::inst() functionality remains unaltered.
HTTPRequest is not a part of kernel, nor are any request-specific services.
Session should accessible through the HTTPRequest (no longer static).
Development experience should not be greatly adversely affected for classes which use the main core traits.
If a non-current instance of Injector / Config is ever invoked, it must raise a logic error to enforce application consistency.
The concept is applied to all core modules
The upgrade path is clearly documented

tractorcow commented 7 years ago

Nice +1 thanks @chillu

tractorcow commented 7 years ago

Just so that everyone here is clear, we are going to close and accept this RFC pretty early next week. Please get in your concerns early if you have anything you would like to add.

tractorcow commented 7 years ago

Hello, the discussion seems to have tailed off, and given our general agreement on approach we will close this discussion and move onto implementation.

tractorcow commented 7 years ago

todo : update A/C and task.

tractorcow commented 7 years ago

I've just updated the tasks for this story. Quite a lot of progress made so far!

no more ConfigureFromEnv.php
No more SapphireTest::is_running_tests()
Lazy-connect DB::getConn() (great for database-less requests)
no more DataModel
ErrorControlChain is now entirely optional middleware
no more die() anywhere (throwing HTTPResponse_Exception is now preferred).
no more Session::inst()
no more phpunitshim

tractorcow commented 7 years ago

I've added WIP branches to the initial story body.

New progress:

SapphireTest refactor (now boots custom application, injectable test state for restoring / setting initial state). Versioned / etc specific test state is now shifted into versioned module. See tests.yml for core config.
Refactor of nesting: No longer do we need to count nest() / unnest() instances! just keep a reference to the initial object, and call ->activate() on it to revert all subsequent nesting. Works on injector, config, and the new app kernel. I've removed static variables from injector / config.
Core tests are passing.

chillu commented 7 years ago

🎉🎉🎉

silverstripe / silverstripe-framework