Merge pull request #3758 from Spuds/Mydevelopment

Continued refresh

index.php

@@ -79,12 +79,8 @@ function elk_main()
 {
 	global $modSettings, $context;
 
-	// A safer way to work with our form globals
-	// @todo Use dependency injection
-	$_req = HttpReq::instance();
-
 	// What shall we do?
-	$dispatcher = new ElkArte\SiteDispatcher($_req);
+	$dispatcher = new ElkArte\SiteDispatcher( HttpReq::instance());
 
 	if ($dispatcher->needSecurity())
 	{
@@ -131,7 +127,7 @@ function elk_main()
 			// Track forum statistics and hits...?
 			if (!empty($modSettings['hitStats']))
 			{
-				trackStats(array('hits' => '+'));
+				trackStats(['hits' => '+']);
 			}
 		}
 

sources/ElkArte/AbstractController.php

@@ -14,10 +14,14 @@
 namespace ElkArte;
 
 /**
- * Abstract base class for controllers.
+ * AbstractController class
  *
- * - Requires a default action handler, action_index().
- * - Defines an empty implementation for pre_dispatch() method.
+ * This class serves as a base class for all controllers in the application.
+ * It provides common functionality and methods that can be used by its subclasses.
+ *
+ *  - Requires a default action handler, action_index().
+ *  - Provides a constructor that loads in HttpReq.  Controllers should use a pre_dispatch class which is called
+ *    by the dispatcher before any other action method.
  */
 abstract class AbstractController
 {
@@ -34,7 +38,9 @@ abstract class AbstractController
 	protected $user;
 
 	/**
-	 * @param EventManager $eventManager
+	 * Constructor for the class.
+	 *
+	 * @param object $eventManager The event manager object.
 	 */
 	public function __construct($eventManager)
 	{
@@ -44,6 +50,31 @@ public function __construct($eventManager)
 		$this->_events = $eventManager;
 	}
 
+	/**
+	 * Default action handler.
+	 *
+	 * What it does:
+	 *
+	 * - This will be called by the dispatcher in many cases.
+	 * - It may set up a menu, sub-dispatch at its turn to the method matching ?sa= parameter
+	 * or simply forward the request to a known default method.
+	 */
+	abstract public function action_index();
+
+	/**
+	 * Called before any other action method in this class.
+	 *
+	 * What it does:
+	 *
+	 * - Allows for initializations, such as default values or loading templates or language files.
+	 */
+	public function pre_dispatch()
+	{
+		// By default, do nothing.
+		// Sub-classes may implement their prerequisite loading,
+		// such as load the template, load the language(s) file(s)
+	}
+
 	/**
 	 * Standard method to add an "home" button when using a custom action as forum index.
 	 *
@@ -53,14 +84,14 @@ public static function addForumButton(&$buttons)
 	{
 		global $scripturl, $txt, $modSettings;
 
-		$buttons = array_merge(array(
-			'base' => array(
+		$buttons = array_merge([
+			'base' => [
 				'title' => $txt['home'],
 				'href' => $scripturl,
 				'data-icon' => 'i-home',
 				'show' => true,
 				'action_hook' => true,
-			)), $buttons);
+			]], $buttons);
 
 		$buttons['home']['href'] = getUrl('action', $modSettings['default_forum_action']);
 		$buttons['home']['data-icon'] = 'i-comment-blank';
@@ -78,10 +109,17 @@ public static function fixCurrentAction(&$current_action)
 			$current_action = 'base';
 		}
 
-		if (!empty($_REQUEST['action']) && $_REQUEST['action'] === 'forum')
+		if (empty($_REQUEST['action']))
+		{
+			return;
+		}
+
+		if ($_REQUEST['action'] !== 'forum')
 		{
-			$current_action = 'home';
+			return;
 		}
+
+		$current_action = 'home';
 	}
 
 	/**
@@ -91,37 +129,35 @@ public static function fixCurrentAction(&$current_action)
 	 */
 	public static function canFrontPage()
 	{
-		return in_array('ElkArte\\FrontpageInterface', class_implements(get_called_class()), true);
+		return in_array(FrontpageInterface::class, class_implements(static::class), true);
 	}
 
 	/**
-	 * {@inheritdoc }
+	 * Used to define the parameters the controller may need for the front page
+	 * action to work
+	 *
+	 * - e.g. specify a topic ID or a board listing
 	 */
 	public static function frontPageOptions()
 	{
 		return [];
 	}
 
 	/**
-	 * {@inheritdoc }
+	 * Used to validate any parameters the controller may need for the front page
+	 * action to work
+	 *
+	 * - e.g. specify a topic ID
+	 * - should return true or false based on if its able to show the front page
 	 */
 	public static function validateFrontPageOptions($post)
 	{
 		return true;
 	}
 
 	/**
-	 * Sets the $this->user property to the current user
-	 *
-	 * @param ValuesContainer $user
-	 */
-	public function setUser($user)
-	{
-		$this->user = $user;
-	}
-
-	/**
-	 * Tells if the controller requires the security framework to be loaded.
+	 * Tells if the controller requires the security framework to be loaded. This is called
+	 * immediately after the controller is initialized.
 	 *
 	 * @param string $action the function name of the current action
 	 *
@@ -179,7 +215,7 @@ public function getHook()
 	public function getModuleClass()
 	{
 		// Use the base controller name for the hook, ie post
-		$module_class = explode('\\', trim(get_class($this), '\\'));
+		$module_class = explode('\\', trim(static::class, '\\'));
 		$module_class = end($module_class);
 
 		return ucfirst($module_class);
@@ -219,7 +255,7 @@ protected function _loadModules()
 	{
 		global $modSettings;
 
-		$classes = array();
+		$classes = [];
 		$setting_key = 'modules_' . $this->getHook();
 		$namespace = '\\ElkArte\\Modules\\';
 
@@ -244,32 +280,6 @@ protected function _loadModules()
 		return $classes;
 	}
 
-	/**
-	 * Default action handler.
-	 *
-	 * What it does:
-	 *
-	 * - This will be called by the dispatcher in many cases.
-	 * - It may set up a menu, sub-dispatch at its turn to the method matching ?sa= parameter
-	 * or simply forward the request to a known default method.
-	 */
-	abstract public function action_index();
-
-	/**
-	 * Called before any other action method in this class.
-	 *
-	 * What it does:
-	 *
-	 * - Allows for initializations, such as default values or
-	 * loading templates or language files.
-	 */
-	public function pre_dispatch()
-	{
-		// By default, do nothing.
-		// Sub-classes may implement their prerequisite loading,
-		// such as load the template, load the language(s) file(s)
-	}
-
 	/**
 	 * An odd function that allows events to request dependencies from properties
 	 * of the class.  Used by the EventManager to allow registered events to access
@@ -297,27 +307,23 @@ public function provideDependencies($dep, &$dependencies)
 	}
 
 	/**
-	 * @return ValuesContainer
+	 * Returns the user object.
+	 *
+	 * @return ValuesContainer the user object.
 	 */
 	public function getUser(): ValuesContainer
 	{
 		return $this->user;
 	}
 
 	/**
-	 * Shortcut to register an array of names as events triggered at a certain
-	 * position in the code.
+	 * Sets the $this->user property to the current user
 	 *
-	 * @param string $name - Name of the trigger where the events will be executed.
-	 * @param string $method - The method that will be executed.
-	 * @param string[] $to_register - An array of classes to register.
+	 * @param ValuesContainer $user
 	 */
-	protected function _registerEvent($name, $method, $to_register)
+	public function setUser($user)
 	{
-		foreach ($to_register as $class)
-		{
-			$this->_events->register($name, array($name, array($class, $method, 0)));
-		}
+		$this->user = $user;
 	}
 
 	/**
@@ -341,4 +347,19 @@ public function getApi()
 
 		return $api;
 	}
+
+	/**
+	 * Shortcut to register an array of names as events triggered at a certain position in the code.
+	 *
+	 * @param string $name - Name of the trigger where the events will be executed.
+	 * @param string $method - The method that will be executed.
+	 * @param string[] $to_register - An array of classes to register.
+	 */
+	protected function _registerEvent($name, $method, $to_register)
+	{
+		foreach ($to_register as $class)
+		{
+			$this->_events->register($name, array($name, array($class, $method, 0)));
+		}
+	}
 }

sources/ElkArte/AbstractModel.php

@@ -1,8 +1,7 @@
 <?php
 
 /**
- * Most of the "models" require some common stuff (like a constructor).
- * Here it is.
+ * Most of the "models" require some common stuff (like a constructor). Here it is.
  *
  * @package   ElkArte Forum
  * @copyright ElkArte Forum contributors
@@ -14,23 +13,27 @@
 
 namespace ElkArte;
 
+use ElkArte\Database\QueryInterface;
+
 /**
  * Class AbstractModel
  *
- * Abstract base class for models.
+ * This is an abstract base class for models in the application.
+ * It provides a database object, modSettings object, and request values object.
+ * Child classes can extend this class to inherit these properties and methods.
  */
 abstract class AbstractModel
 {
-	/** @var \ElkArte\Database\QueryInterface The database object */
+	/** @var QueryInterface The database object */
 	protected $_db;
 
-	/** @var \ElkArte\UserInfo The current user data */
+	/** @var UserInfo The current user data */
 	protected $user;
 
 	/** @var object The modSettings */
 	protected $_modSettings = [];
 
-	/** @var \ElkArte\HttpReq The request values */
+	/** @var HttpReq The request values */
 	protected $_req;
 
 	/**
@@ -45,7 +48,7 @@ public function __construct($db = null, $user = null)
 
 		$this->_db = $db ?: database();
 		$this->user = $user;
-		$this->_modSettings = new ValuesContainer($modSettings ?: array());
+		$this->_modSettings = new ValuesContainer($modSettings ?: []);
 		$this->_req = HttpReq::instance();
 	}
 }