Document new database package installation plugin (#135)

See WoltLab/WCF#4077

diff --git a/docs/migration/wsc53/php.md b/docs/migration/wsc53/php.md
index d9b5c110d661545757d04a4a212b38f7ce36d468..607f538010d176f7824fa6c38ed96e54915d608b 100644 (file)
--- a/docs/migration/wsc53/php.md
+++ b/docs/migration/wsc53/php.md
@@ -48,6 +48,13 @@ For further details on these methods, please refer to the [documentation in the
 
 !!! warning "Do not interact directly with the flood control database table but only via the `FloodControl` class!"
 
+## DatabasePackageInstallationPlugin
+
+`DatabasePackageInstallationPlugin` is a new idempotent package installation plugin (thus it is available in the sync function in the devtools) to update the database schema using the PHP-based database API.
+`DatabasePackageInstallationPlugin` is similar to `ScriptPackageInstallationPlugin` by requiring a PHP script that is included during the execution of the script.
+The script is expected to return an array of `DatabaseTable` objects representing the schema changes so that in contrast to using `ScriptPackageInstallationPlugin`, no `DatabaseTableChangeProcessor` object has to be created.
+The PHP file must be located in the `acp/database/` directory for the devtools sync function to recognize the file.
+
 ## PHP Database API
 
 The PHP API to add and change database tables during package installations and updates in the `wcf\system\database\table` namespace now also supports renaming existing table columns with the new `IDatabaseTableColumn::renameTo()` method:

diff --git a/docs/package/pip.md b/docs/package/pip.md
index b9ecbdc8f6b445292f3298c8c5da09c6f9a3e1a1..6c4011150ac0a60d435f857dce0e7311c8661f9e 100644 (file)
--- a/docs/package/pip.md
+++ b/docs/package/pip.md
@@ -17,6 +17,7 @@ Package Installation Plugins (PIPs) are interfaces to deploy and edit content as
 | [clipboardAction](pip/clipboard-action.md) | Perform bulk operations on marked objects |
 | [coreObject](pip/core-object.md) | Access Singletons from within the template |
 | [cronjob](pip/cronjob.md) | Periodically execute code with customizable intervals |
+| [database](pip/database.md) | Updates the database layout using [the PHP API](database-php-api.md) |
 | [eventListener](pip/event-listener.md) | Register listeners for the event system |
 | [file](pip/file.md) | Deploy any type of files with the exception of templates |
 | [language](pip/language.md) | Language items |

diff --git a/docs/package/pip/database.md b/docs/package/pip/database.md
new file mode 100644 (file)
index 0000000..f2fa132
--- /dev/null
+++ b/docs/package/pip/database.md
@@ -0,0 +1,39 @@
+# Database Package Installation Plugin
+
+!!! info "Available since WoltLab Suite 5.4."
+
+Update the database layout using [the PHP API](../database-php-api.md).
+
+!!! warning "You must install the PHP script through the [file package installation plugin](file.md)."
+
+!!! warning "The installation will attempt to delete the script after successful execution."
+
+## Attributes
+
+### `application`
+
+The `application` attribute must have the same value as the `application` attribute of the `file` package installation plugin instruction so that the correct file in the intended application directory is executed.
+For further information about the `application` attribute, refer to its documentation on the [acpTemplate package installation plugin page](acp-template.md#application).
+
+
+## Expected value
+
+The `database`-PIP expects a relative path to a `.php` file that returns an array of `DatabaseTable` objects.
+
+### Naming convention
+
+The PHP script is deployed by using the [file package installation plugin](file.md).
+To prevent it from colliding with other install script (remember: You cannot overwrite files created by another plugin), we highly recommend to make use of these naming conventions:
+
+- Installation: `acp/database/install_<package>_<version>.php` (example: `acp/database/install_com.woltlab.wbb_5.4.0.php`)
+- Update: `acp/database/update_<package>_<targetVersion>.php` (example: `acp/database/update_com.woltlab.wbb_5.4.1.php`)
+
+`<targetVersion>` equals the version number of the current package being installed.
+If you're updating from `1.0.0` to `1.0.1`, `<targetVersion>` should read `1.0.1`.
+
+If you run multiple update scripts, you can append additional information in the filename.
+
+
+## Execution environment
+
+The script is included using `include()` within [DatabasePackageInstallationPlugin::updateDatabase()](https://github.com/WoltLab/WCF/blob/148da7ceaf3a80bfc91447635b0299089ddf7015/wcfsetup/install/files/lib/system/package/plugin/DatabasePackageInstallationPlugin.class.php#L69).