Merge branch 'route-apidoc-fixes' into 'dev'

Zotlabs\Extend\Route: API docs and visibility/type fixes

See merge request hubzilla/core!2273

Zotlabs/Extend/Route.php

@@ -1,12 +1,71 @@
 <?php
+/*
+ * SPDX-FileCopyrightText: 2018 The Hubzilla Community
+ * SPDX-FileContributor: Zotlabs
+ * SPDX-FileContributor: Mario <mario@mariovavti.com>
+ * SPDX-FileContributor: Harald Eilertsen <haraldei@anduin.net>
+ *
+ * SPDX-License-Identifier: MIT
+ */
 
 namespace Zotlabs\Extend;
 
 use Zotlabs\Lib\Config;
 
+/**
+ * Class for managing routes.
+ *
+ * Routes connect a URL path to a module that will handle requests to that
+ * path.
+ *
+ * For example by registering a route like this:
+ *
+ * ```php
+ * Route::register(
+ *     __DIR__ . '/Mod_Myroute.php',
+ *     'myroute'
+ * );
+ * ```
+ *
+ * Hubzilla will direct requests to the '/myroute' URL path to the 'Myroute'
+ * controller located in the '/Mod_Myroute.php' file in the same directory as
+ * the file this code was called from.
+ *
+ * Routes are stored persistently, so this function will typically be called from
+ * the `<addon>_load()` function if called from an addon. Accordingly, the route must
+ * be unregistered when no longer needed, like this:
+ *
+ * ```php
+ * Route::unregister(
+ *     __DIR__ . '/Mod_Myroute.php',
+ *     'myroute'
+ * );
+ * ```
+ *
+ * This will typically be called from the `<addon>_unload()` function in an addon.
+ */
 class Route {
 
-	static function register($file,$modname) {
+	/**
+	 * Register a new route.
+	 *
+	 * Example:
+	 * ```php
+	 * Route::register(
+	 *     __DIR__ . '/Mod_Myroute.php',
+	 *     'myroute'
+	 * );
+	 * ```
+	 *
+	 * The route is stored persistently, and must be unregistered when no longer needed.
+	 *
+	 * @param string $file      The file containing the controller for handling requests to this route.
+	 * @param string $modname   The name of the module (URL path).
+	 *
+	 * @see {@link Zotlabs::Extend::Route.unregister() unregister()}
+	 * @see {@link Zotlabs::Extend::Route.unregister_by_file() unregister_by_file()}
+	 */
+	public static function register(string $file, string $modname): void {
 		$rt = self::get();
 
 		foreach ($rt as $r) {
@@ -19,7 +78,24 @@ class Route {
 		self::set($rt);
 	}
 
-	static function unregister($file,$modname) {
+	/**
+	 * Unregister a route.
+	 *
+	 * Example:
+	 * ```php
+	 * Route::unregister(
+	 *     __DIR__ . '/Mod_Myroute.php',
+	 *     'myroute'
+	 * );
+	 * ```
+	 *
+	 * @param string $file      The file containing the controller for handling requests to this route.
+	 * @param string $modname   The name of the module (URL path).
+	 *
+	 * @see {@link Zotlabs::Extend::Route.register() register()}
+	 * @see {@link Zotlabs::Extend::Route.unregister_by_file() unregister_by_file()}
+	 */
+	public static function unregister(string $file, string $modname): void {
 		$rt = self::get();
 		if($rt) {
 			$n = [];
@@ -32,7 +108,23 @@ class Route {
 		}
 	}
 
-	static function unregister_by_file($file) {
+	/**
+	 * Unregister all routes by source file.
+	 *
+	 * Removes all persistently stored routes with hanclers in the
+	 * given source file.
+	 *
+	 * Example:
+	 * ```php
+	 * Route::unregister_by_file(__DIR__ . '/Mod_Myroute.php');
+	 * ```
+	 *
+	 * @param string $file      The file containing the controllers to remove.
+	 *
+	 * @see {@link Zotlabs::Extend::Route.register() register()}
+	 * @see {@link Zotlabs::Extend::Route.unregister() unregister()}
+	 */
+	public static function unregister_by_file(string $file): void {
 		$rt = self::get();
 		if($rt) {
 			$n = [];
@@ -45,11 +137,18 @@ class Route {
 		}
 	}
 
-	static function get() {
+	/**
+	 * Get an array of all defined routes.
+	 *
+	 * @return An array of routes, where each entry is an array
+	 *               containing two elements, the file, and the module
+	 *               name.
+	 */
+	public static function get(): array {
 		return Config::Get('system','routes',[]);
 	}
 
-	static function set($r) {
+	private static function set(array $r): mixed {
 		return Config::Set('system','routes',$r);
 	}
 }