Merge branch 'global-state-and-some-docs' into 'dev'

Reduce some global state and add some docs

See merge request hubzilla/core!2119

5 files changed, 92 insertions, 33 deletions

diff --git a/Zotlabs/Module/Setup.php b/Zotlabs/Module/Setup.php
index 74b10de25..65d4ec471 100644
--- a/Zotlabs/Module/Setup.php
+++ b/Zotlabs/Module/Setup.php
@@ -1,5 +1,4 @@
 <?php
-namespace Zotlabs\Module;
 /**
  * @file Zotlabs/Module/Setup.php
  *
@@ -8,11 +7,12 @@ namespace Zotlabs\Module;
  * @todo This setup module could need some love and improvements.
  */
 
+namespace Zotlabs\Module;
+
 use Zotlabs\Lib\Config;
 
 /**
- * @brief Initialisation for the setup module.
- *
+ * Controller for the initial setup/installation.
  */
 class Setup extends \Zotlabs\Web\Controller {
 
diff --git a/Zotlabs/Web/Controller.php b/Zotlabs/Web/Controller.php
index 2d0f58891..6384f24df 100644
--- a/Zotlabs/Web/Controller.php
+++ b/Zotlabs/Web/Controller.php
@@ -2,12 +2,58 @@
 
 namespace Zotlabs\Web;
 
+/**
+ * Base controller class for Modules.
+ *
+ * Modules should extend this class, and override the methods needed. Emtpy
+ * default implementations allow Modules to only override the methods they
+ * need.
+ *
+ * The methods defined by this class is invoked in order:
+ *
+ *   - init()
+ *   - post() -- only for POST requests
+ *   - get()
+ *
+ * Modules which emit other serialisations besides HTML (XML,JSON, etc.) should
+ * do so within the module `init` and/or `post` functions and then invoke
+ * `killme()` to terminate further processing.
+ */
+abstract class Controller {
 
-class Controller {
+	/**
+	 * Initialize request processing.
+	 *
+	 * This method is called before any other request processing, and
+	 * regardless of the request method. The theme is not yet loaded when
+	 * this method is invoked.
+	 */
+	public function init() {
+	}
 
-	function init() {}
-	function post() {}
-	function get() {}
+	/**
+	 * Process POST requests.
+	 *
+	 * This method is called if the incoming request is a POST request. It is
+	 * invoked after the theme has been loaded. This method should not normally
+	 * render HTML output, as processing will fall through to the GET processing
+	 * if this method completes without error or stopping processing in other
+	 * ways.
+	 */
+	public function post() {
+	}
 
+	/**
+	 * Process GET requests or the body part of POST requests.
+	 *
+	 * This method is called directly for GET requests, and immediately after the
+	 * `post()` method for POST requests.
+	 *
+	 * It will return the module content as a HTML string.
+	 *
+	 * @return string HTML content for the module.
+	 */
+	public function get() {
+		return '';
+	}
 }
-
diff --git a/Zotlabs/Web/Router.php b/Zotlabs/Web/Router.php
index f2604b95d..122e7ff73 100644
--- a/Zotlabs/Web/Router.php
+++ b/Zotlabs/Web/Router.php
@@ -37,6 +37,7 @@ class Router {
 
 	private $modname = '';
 	private $controller = null;
+	private bool $module_loaded = false;
 
 	/**
 	 * @brief Router constructor.
@@ -62,7 +63,7 @@ class Router {
 						include_once($route[0]);
 						if(class_exists($modname)) {
 							$this->controller = new $modname;
-							App::$module_loaded = true;
+							$this->module_loaded = true;
 						}
 					}
 				}
@@ -70,15 +71,15 @@ class Router {
 
 			// legacy plugins - this can be removed when they have all been converted
 
-			if(! (App::$module_loaded)) {
+			if(! ($this->module_loaded)) {
 				if(is_array(App::$plugins) && in_array($module, App::$plugins) && file_exists("addon/{$module}/{$module}.php")) {
 					include_once("addon/{$module}/{$module}.php");
 					if(class_exists($modname)) {
 						$this->controller = new $modname;
-						App::$module_loaded = true;
+						$this->module_loaded = true;
 					}
 					elseif(function_exists($module . '_module')) {
-						App::$module_loaded = true;
+						$this->module_loaded = true;
 					}
 				}
 			}
@@ -88,40 +89,40 @@ class Router {
 			 * Otherwise, look for the standard program module
 			 */
 
-			if(! (App::$module_loaded)) {
+			if(! ($this->module_loaded)) {
 				try {
 					$filename = 'Zotlabs/SiteModule/'. ucfirst($module). '.php';
 					if(file_exists($filename)) {
 						// This won't be picked up by the autoloader, so load it explicitly
 						require_once($filename);
 						$this->controller = new $modname;
-						App::$module_loaded = true;
+						$this->module_loaded = true;
 					}
 					else {
 						$filename = 'Zotlabs/Module/'. ucfirst($module). '.php';
 						if(file_exists($filename)) {
 							$this->controller = new $modname;
-							App::$module_loaded = true;
+							$this->module_loaded = true;
 						}
 					}
-					if(! App::$module_loaded)
+					if(! $this->module_loaded)
 						throw new Exception('Module not found');
 				}
 				catch(Exception $e) {
 					if(file_exists("mod/site/{$module}.php")) {
 						include_once("mod/site/{$module}.php");
-						App::$module_loaded = true;
+						$this->module_loaded = true;
 					}
 					elseif(file_exists("mod/{$module}.php")) {
 						include_once("mod/{$module}.php");
-						App::$module_loaded = true;
+						$this->module_loaded = true;
 					}
 				}
 			}
 
 			$x = [
 					'module' => $module,
-					'installed' => App::$module_loaded,
+					'installed' => $this->module_loaded,
 					'controller' => $this->controller
 			];
 			/**
@@ -138,7 +139,7 @@ class Router {
 			 */
 			call_hooks('module_loaded', $x);
 			if($x['installed']) {
-				App::$module_loaded = true;
+				$this->module_loaded = true;
 				$this->controller = $x['controller'];
 			}
 
@@ -146,7 +147,7 @@ class Router {
 			 * The URL provided does not resolve to a valid module.
 	 		 */
 
-			if(! (App::$module_loaded)) {
+			if(! ($this->module_loaded)) {
 
 				// undo the setting of a letsencrypt acme-challenge rewrite rule
 				// which blocks access to our .well-known routes.
@@ -162,7 +163,7 @@ class Router {
 
 				$x = [
 					'module' => $module,
-					'installed' => App::$module_loaded,
+					'installed' => $this->module_loaded,
 					'controller' => $this->controller
 				];
 				call_hooks('page_not_found',$x);
@@ -189,7 +190,7 @@ class Router {
 
 				// pretend this is a module so it will initialise the theme
 				App::$module = '404';
-				App::$module_loaded = true;
+				$this->module_loaded = true;
 				App::$error = true;
 			}
 		}
@@ -205,7 +206,7 @@ class Router {
 		 * Call module functions
 		 */
 
-		if(App::$module_loaded) {
+		if($this->module_loaded) {
 
 			App::$page['page_title'] = App::$module;
 			$placeholder = '';
diff --git a/Zotlabs/Web/WebServer.php b/Zotlabs/Web/WebServer.php
index f43ae10a4..6f8a4b956 100644
--- a/Zotlabs/Web/WebServer.php
+++ b/Zotlabs/Web/WebServer.php
@@ -13,11 +13,11 @@ class WebServer {
 
 		require_once('boot.php');
 
-		sys_boot();
+		$installed = sys_boot();
 
 
 		\App::$language = get_best_language();
-		load_translation_table(\App::$language,\App::$install);
+		load_translation_table(\App::$language, !$installed);
 
 
 		/**
@@ -56,7 +56,7 @@ class WebServer {
 			load_translation_table(\App::$language);
 		}
 
-		if((x($_GET,'zid')) && (! \App::$install)) {
+		if (x($_GET,'zid') && $installed) {
 			\App::$query_string = strip_zids(\App::$query_string);
 			if(! local_channel()) {
 				if (!isset($_SESSION['my_address']) || $_SESSION['my_address'] != $_GET['zid']) {
@@ -69,14 +69,14 @@ class WebServer {
 			}
 		}
 
-		if((x($_GET,'zat')) && (! \App::$install)) {
+		if (x($_GET,'zat') && $installed) {
 			\App::$query_string = strip_zats(\App::$query_string);
 			if(! local_channel()) {
 				zat_init();
 			}
 		}
 
-		if((x($_REQUEST,'owt')) && (! \App::$install)) {
+		if (x($_REQUEST,'owt') && $installed) {
 			$token = $_REQUEST['owt'];
 			\App::$query_string = strip_query_param(\App::$query_string,'owt');
 			owt_init($token);
@@ -85,7 +85,7 @@ class WebServer {
 		if((x($_SESSION, 'authenticated')) || (x($_POST, 'auth-params')) || (\App::$module === 'login'))
 			require('include/auth.php');
 
-		if(\App::$install) {
+		if (!$installed) {
 			/* Allow an exception for the view module so that pcss will be interpreted during installation */
 			if(\App::$module != 'view')
 				\App::$module = 'setup';
diff --git a/boot.php b/boot.php
index dcdcdda01..862079276 100644
--- a/boot.php
+++ b/boot.php
@@ -602,8 +602,19 @@ define('DBTYPE_MYSQL', 0);
 define('DBTYPE_POSTGRES', 1);
 
 
-function sys_boot() {
-
+/**
+ * Boot the app.
+ *
+ * Detects if the system is installed, and if it is, reads the basic configuration
+ * in `.htconfig`, conects to the database, and loads the system configuration stored
+ * in the db.
+ *
+ * As a side effect it also sets the App::$install flag to true if the system is _not_
+ * installed yet.
+ *
+ * @return True if the system is installed, false otherwise.
+ */
+function sys_boot(): bool {
 
 	// our central App object
 
@@ -686,6 +697,8 @@ function sys_boot() {
 		 */
 		call_hooks('init_1');
 	}
+
+	return !App::$install;
 }
 
 
@@ -766,7 +779,6 @@ class App {
 	public static $langsave;
 	public static $rtl = false;
 	public static $plugins_admin;
-	public static $module_loaded = false;
 	public static $query_string;
 	public static $page;
 	public static $profile;