From 2ec825df258fa53c526caee7d6b9b65128dc7b72 Mon Sep 17 00:00:00 2001
From: Christoph Wurst <christoph@winzerhof-wurst.at>
Date: Mon, 8 Jun 2020 18:06:49 +0200
Subject: [PATCH] Document current bootstrap mechanism

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
---
 developer_manual/app/bootstrap.rst | 58 ++++++++++++++++++++++++++++++
 developer_manual/app/index.rst     |  1 +
 developer_manual/app/init.rst      | 35 ------------------
 3 files changed, 59 insertions(+), 35 deletions(-)
 create mode 100644 developer_manual/app/bootstrap.rst

diff --git a/developer_manual/app/bootstrap.rst b/developer_manual/app/bootstrap.rst
new file mode 100644
index 00000000000..1cf6c6e2a98
--- /dev/null
+++ b/developer_manual/app/bootstrap.rst
@@ -0,0 +1,58 @@
+=============
+Bootstrapping
+=============
+
+Every php process has a relatively short lifespan that lasts as long as the HTTP request or the invokation of the command
+line program. At the beginning of this lifespan, Nextcloud initializes its services. At the same time, any additional apps
+might want to register their services to Nextcloud as well. This event is called the *bootstrapping* and this chapter
+shall shed some light on how to hook into this with an app.
+
+
+.. _app-php:
+
+app.php
+-------
+
+Nextcloud will ``require_once`` every installed and enabled app's ``appinfo/app.php`` file if it exists. The app can use
+this file to run registrations of services, event listeners and similar.
+
+To leverage the advantages of object-oriented programming, it's recommended to put the logic into an :ref:`application-php`
+class and query an instance like
+
+.. code-block:: php
+
+    <?php
+
+    declare(strict_types=1);
+
+    $app = \OC::$server->query(\OCA\MyApp\AppInfo\Application::class);
+    $app->registerHooks();
+
+
+.. _application-php:
+
+Application
+-----------
+
+An `Application` class shall serve as central initialization point of an app.
+
+.. code-block:: php
+
+    <?php
+
+    declare(strict_types=1);
+
+    namespace OCA\MyApp\AppInfo;
+
+    use OCP\AppFramework\App;
+
+    class Application extends App {
+
+        public function registerHooks(): void {
+            \OCP\Util::connectHook('OC_User', 'pre_deleteUser', 'OCA\MyApp\Hooks\User', 'deleteUser');
+        }
+
+    }
+
+.. note:: Nextcloud does not load this class for every request. You should query an instance inside your :ref:`app-php` to
+          load for every request, if desired.
diff --git a/developer_manual/app/index.rst b/developer_manual/app/index.rst
index c6a018b1aa2..81161bacecf 100644
--- a/developer_manual/app/index.rst
+++ b/developer_manual/app/index.rst
@@ -8,6 +8,7 @@ App development
    intro
    tutorial
    upgrade-guide
+   bootstrap
    npm
    javascript-apis
    requests/index
diff --git a/developer_manual/app/init.rst b/developer_manual/app/init.rst
index 2c8deb1fa6c..f360e369b8c 100644
--- a/developer_manual/app/init.rst
+++ b/developer_manual/app/init.rst
@@ -60,38 +60,3 @@ purpose there are several events emitted that an app can act upon.
             \OCP\Util::addStyle('myapp', 'style');
         }
     );
-
-Best practice
--------------
-
-A common way to have a cleaner code structure is to create a class Application in :file:`lib/AppInfo/Application.php` that will then execute your setup of hooks or background tasks. You can then just call it in your :file:`appinfo/app.php`. That way you can also make use of Nextclouds dependency injection feature and properly test those methods.
-
-
-appinfo/app.php
-^^^^^^^^^^^^^^^
-
-.. code-block:: php
-
-    <?php
-
-    $app = new \OCA\MyApp\AppInfo\Application();
-    $app->registerHooks();
-
-
-lib/AppInfo/Application.php
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: php
-
-    <?php
-    namespace OCA\MyApp\AppInfo;
-
-    use OCP\AppFramework\App;
-
-    class Application extends App {
-
-        public function registerHooks() {
-            \OCP\Util::connectHook('OC_User', 'pre_deleteUser', 'OCA\MyApp\Hooks\User', 'deleteUser');
-        }
-
-    }