Setup UI - Allow callers to wrap UI in their own page chrome. Clarify response format.
authorTim Otten <totten@civicrm.org>
Wed, 8 Jul 2020 00:10:17 +0000 (17:10 -0700)
committerTim Otten <totten@civicrm.org>
Wed, 8 Jul 2020 00:50:05 +0000 (17:50 -0700)
commit30bef769ba3d313c23c2fd6c907b032e53a72826
tree431fea9e177a77af379d088ecb1ef1302cbadde2
parent8072f89dfd12b089e87604b27d3b65ea319e33a0
Setup UI - Allow callers to wrap UI in their own page chrome. Clarify response format.

The general idiom for calling SetupController is like this:

```php
$ctrl = \Civi\Setup::instance()->createController()->getCtrl();
$ctrl->setUrls(...);
\Civi\Setup\BasicRunner::run($ctrl);
```

This changes the data exchanged between `BasicRunner` and `SetupController`
to allow more flexible runners. The `BasicRunner` is the only one currently
used by existing installers, so it's drop-in compatible.

Before
------

The `BasicRunner` calls `$ctrl->run(...)` and gets back an array with the response data
(`[0 => $headers, 1 => $body]`).

After
-----

The `BasicRunner` calls `$ctrl->run(...)` and gets back a `SetupResponse`. This
object provides the `[0]` and `[1]` keys (for backward compat), but it's better
to access the object properties (`$headers`, `$body`, etc).

It provides several additional properties - eg `$title`, `$assets`, `$code`.

Technical Details
------------------

This is a drop-in update for anything that uses `BasicRunner`.

Strictly speaking, if one wrote a different runner, it may or may not be
drop-in compatible.  But since I don't think there are any others, it's not
really worth spending much energy on verifying.

The bump in `Setup::PROTOCOL` (`1.0` => `1.1`) indicates that old installers
should generally be forward compatible with this protocol.  However, if one
writes a new installer and specifically uses the `SetupResponse` type,
then they should assert protocol `1.1`.
setup/src/Setup.php
setup/src/Setup/BasicRunner.php
setup/src/Setup/UI/SetupController.php
setup/src/Setup/UI/SetupResponse.php [new file with mode: 0644]