see neos/neos-development-collection#4243 (comment)
TODO: should be later inlined when it doesnt change anymore ;)
The Setup Package operates strongly coupled with flow and sometimes at super early boot time. This documentation should explain the inner workings and why certain approaches where chosen.
┌──────────────────────────────────────────────┐
│ neos/neos-setup │
│ │ │
│ │ requires neos/neos │
│ │ provides additional steps: neosRequirements, │
┌────────────────────────────────────────────┐ │ │ administrator, siteimport │
│ │ │ │ │
│ │ │ └──────────────────────────────────────────────┘
│ neos/cli-setup │ │ │
│ │ totally unrelated - │
│ newer package (Neos 7.3) │ no code sharing requires
│ requires neos/neos (lives in neos dev │ │ │
│ collection) │ │ │
│ │ │ ▼
│ │ │ ┌─────────────────────────────────────┐
└────────────────────────────────────────────┘ │ │ neos/setup │
│ │ │
│ │ requires neos/flow │
│ │ flow specific steps (database) │
│ │ │
│ │ gui setup infrastructure │
│ │ (backend/configuration/frontend) │
│ │
└─────────────────────────────────────┘
┌────────────────────────────────────────────────────┐
│ neos/neos-setup v3 │
│ │
│ requires neos/neos │
│ │
│ cli commands for `setup:imagehandler` │
│ │
│ health check extensions: │
┌ ─ ─ ─ ─ ─ ─ ─ ─ ▶│ │
│ - (neos escr setup status in version v4) │
│ │ - at least one neos user exists │
neos specific │ - image handling configured? │
┌──────────────────────────────┐ commands extracted │ - site exists │
│ │ │ ... │
│ neos/cli-setup │ - setup:imagehandler │ │
│ │ └────────────────────────────────────────────────────┘
│ will be split up and │─ ─ ─ ─ ┬ ─ ─ ─ ─ ┘ │
│ deprecated │ │
│ │ │ │
└──────────────────────────────┘ │
│ │
┌─requires─┘
│ │
flow specific commands │
extracted │
│
- welcome ▼
- setup:database ┌────────────────────────────────────────────────────────────────────┐
│ │ neos/setup │
│ │
│ │ requires neos/flow │
│ │
│ │ `flow welcome` deprecated and becomes `flow setup` │
│ │
│ │ cli command `flow setup:database` │
│ │
└ ─ ─ ─ ─▶│ health check infrastructure (backend/configuration/frontend) │
│ │
│ │
│ flow specific health checks: │
│ - db connection │
│ - doctrine migration status │
│ - php version web and cli match │
│ │
└────────────────────────────────────────────────────────────────────┘
The previous package shipping flow welcome and flow setup:database as well as flow setup:imagehandler was Neos.CliSetup.
To ease the migration, eg. keep the command identifiers, but ship them with this package, the command controller was copied.
But this bears a problem: without adjustments, it could happen that both packages are installed side by side.
This would mean that the command flow setup:database cant be correctly resolved to one unique command controller.
To prevent the Neos.CliSetup being installed in the first place, we declare this package as composer replacement.
We decided to keep using the /setup endpoint for the web. For the cli setup Neos.CliSetup originally used flow welcome as entry point, but because it would be cool to have a similar entry point we decided for flow setup.
You might be wondering how it was possible for flow welcome to function, as you dont have to specify the actually command name: Simple, because the WelcomeController only had one method indexCommand (name can be chosen freely).
Flow doesn't offer us to have flow setup point directly to our entry point while we also have other commands like flow setup:database and more.
To work around this limitation we also use our COMMAND_IDENTIFIER_ALIAS_MAP to rewrite the setup to setup:index.
Another redirect is also setup to redirect any requests from flow welcome to flow setup, to provide a 1 to 1 replacement for Neos.CliSetup.
We have a custom request handler in place to realize pre compile time / super early, nearly no boot time checks.
This has the advantage
- No errors will be thrown when there are invalid php sources (as we don't attempt to require many classes / and maybe because we dont trigger the reflection service?)
- On Windows, the compiling might not succeed if the php binary is not set correctly
- We dont want to depend on caching framework
- Speed for the initial low level checks
- Because so little of the system is active, little can fail so it should provide a super stable endpoint across web hostings and development machines.
Our web request handler needs to take care itself of routing the JS & CSS files.
But this might not be anticipated by the webserver: Eg it might thing JS and CSS are always to be found in _Resources. To avoid this problem, we simply use no extension and request main_js instead.
We must use the Configuration manager without cache, as the caching framework and file monitor listener will not be active yet, and otherwise it would lead to a frozen/invalid cache. (In my testing on a fast maschine there is no difference between cache and no cache)