Merging develop into master for deployment.

classes/acl.php

@@ -3,6 +3,9 @@
  * @author: KentProjects <[email protected]>
  * @license: Copyright KentProjects
  * @link: http://kentprojects.com
+ *
+ * Class ACL
+ * This is the glorious ACL class that ensures a user can and can't do some action.
  */
 final class ACL implements Countable
 {
@@ -11,13 +14,33 @@ final class ACL implements Countable
 	const UPDATE = "acl:update";
 	const DELETE = "acl:delete";
 
+	/**
+	 * A base template for each set of ACLs.
+	 * @var array
+	 */
 	protected static $template = array("create" => 0, "read" => 0, "update" => 0, "delete" => 0);
 
+	/**
+	 * The current list of ACLs.
+	 * @var array
+	 */
 	protected $acl;
+	/**
+	 * The current user we're handling ACLs for.
+	 * @var Model_User
+	 */
 	protected $user;
 
+	/**
+	 * Build a new ACLs object.
+	 *
+	 * @param Model_User $user
+	 */
 	public function __construct(Model_User $user = null)
 	{
+		/**
+		 * If we don't have user, just return, because it will just return false for everything.
+		 */
 		if (empty($user))
 		{
 			return;
@@ -28,41 +51,8 @@ public function __construct(Model_User $user = null)
 	}
 
 	/**
-	 * @param string $entity
-	 * @return array
-	 */
-	public function get($entity)
-	{
-		if (empty($this->user))
-		{
-			return array();
-		}
-
-		$values = static::$template;
-
-		if (empty($this->acl))
-		{
-			return $values;
-		}
-
-		$range = explode("/", $entity);
-		$rangeString = "";
-
-		foreach ($range as $i => $piece)
-		{
-			$rangeString .= ($i == 0 ? "" : "/") . $piece;
-			$values = array_merge($values, $this->checkMatch($rangeString));
-		}
-
-		foreach ($values as $key => $value)
-		{
-			$values[$key] = boolval($value);
-		}
-
-		return $values;
-	}
-
-	/**
+	 * Check that a particular entity is a match.
+	 *
 	 * @param string $entry
 	 * @return array
 	 */
@@ -79,21 +69,34 @@ protected function checkMatch($entry)
 	}
 
 	/**
+	 * Count the number of ACLs.
 	 * @return int
 	 */
 	public function count()
 	{
 		return empty($this->acl) ? 0 : count($this->acl);
 	}
 
+	/**
+	 * Remove a particular ACL from this list.
+	 * @param string $entity
+	 * @return void
+	 */
 	public function delete($entity)
 	{
 		unset($this->acl[$entity]);
 		ksort($this->acl);
 	}
 
+	/**
+	 * Build the list of ACLs for the current user.
+	 * @return void
+	 */
 	public function fetch()
 	{
+		/**
+		 * If we were not passed a user, then stop.
+		 */
 		if (empty($this->user))
 		{
 			return;
@@ -115,6 +118,53 @@ public function fetch()
 	}
 
 	/**
+	 * Get the permissions for a particular entity.
+	 * This "recursively" splits the entity to ensure that all global variants are handled.
+	 *
+	 * Thus,
+	 *   group
+	 *   group/1
+	 *
+	 *   project
+	 *   project/22
+	 *
+	 * @param string $entity
+	 * @return array
+	 */
+	public function get($entity)
+	{
+		if (empty($this->user))
+		{
+			return array();
+		}
+
+		$values = static::$template;
+
+		if (empty($this->acl))
+		{
+			return $values;
+		}
+
+		$range = explode("/", $entity);
+		$rangeString = "";
+
+		foreach ($range as $i => $piece)
+		{
+			$rangeString .= ($i == 0 ? "" : "/") . $piece;
+			$values = array_merge($values, $this->checkMatch($rangeString));
+		}
+
+		foreach ($values as $key => $value)
+		{
+			$values[$key] = boolval($value);
+		}
+
+		return $values;
+	}
+
+	/**
+	 * Return the current user in question.
+	 *
 	 * @return Model_User
 	 */
 	public function getUser()
@@ -181,6 +231,9 @@ public function set($entity, $create = false, $read = false, $update = false, $d
 	}
 
 	/**
+	 * Validate a particular entity and action.
+	 * This is mostly used in the controllers when validating a user's permission to do a certain action.
+	 *
 	 * @param string $entity
 	 * @param string $action
 	 * @throws InvalidArgumentException

classes/auth.php

@@ -3,6 +3,9 @@
  * @author: KentProjects <[email protected]>
  * @license: Copyright KentProjects
  * @link: http://kentprojects.com
+ *
+ * Class Auth
+ * Handles the API authentication.
  */
 final class Auth
 {
@@ -45,6 +48,10 @@ public function __construct(Request_Internal &$request, Response &$response, $le
 
 		if ($this->level !== self::NONE)
 		{
+			/**
+			 * This code runs when authentication is required.
+			 * If something seems wrong, then the API will reject the request.
+			 */
 			if ($this->request->query("key", null) === null)
 			{
 				throw new HttpStatusException(400, "Missing application key.");
@@ -116,6 +123,10 @@ function (&$v)
 		}
 		else
 		{
+			/**
+			 * If this endpoint does not require authentication, and we have the relevant query string values, then we
+			 * may as well authenticate the request.
+			 */
 			if ($this->request->query("key", null) !== null)
 			{
 				$this->application = Model_Application::getByKey($this->request->query("key"));

classes/controller.php

@@ -3,6 +3,9 @@
  * @author: KentProjects <[email protected]>
  * @license: Copyright KentProjects
  * @link: http://kentprojects.com
+ *
+ * Class Controller
+ * This represents a basic controller that takes requests in and returns responses out.
  */
 abstract class Controller
 {
@@ -53,6 +56,7 @@ public function __construct(Request_Internal &$request, Response &$response)
 
 	/**
 	 * To be run BEFORE the main action.
+	 * @return void
 	 */
 	public function before()
 	{
@@ -61,6 +65,7 @@ public function before()
 
 	/**
 	 * To be run AFTER the main action.
+	 * @return void
 	 */
 	public function after()
 	{
@@ -77,6 +82,9 @@ public function after()
 	}
 
 	/**
+	 * This is our custom render function that goes through each result, ensuring it's in a format that JSON-encode
+	 * will accept.
+	 *
 	 * @param mixed $body
 	 * @return mixed
 	 */