From e576b05078adccd9d978b5ddf64f3766832e6576 Mon Sep 17 00:00:00 2001
From: Flavio Copes <copesc@gmail.com>
Date: Wed, 27 Jan 2016 15:57:39 +0100
Subject: [PATCH] :art: Add `use` statements. Add docblocks. Improve code
 readability and type hints

---
 system/src/Grav/Common/Browser.php  |  3 +
 system/src/Grav/Common/Cache.php    | 23 +++----
 system/src/Grav/Common/Composer.php |  5 ++
 system/src/Grav/Common/Debugger.php | 93 ++++++++++++++++++++++++++---
 system/src/Grav/Common/Getters.php  |  2 +-
 system/src/Grav/Common/Grav.php     | 32 ++++++++--
 6 files changed, 133 insertions(+), 25 deletions(-)

diff --git a/system/src/Grav/Common/Browser.php b/system/src/Grav/Common/Browser.php
index f39ac1539..cf29ae62d 100644
--- a/system/src/Grav/Common/Browser.php
+++ b/system/src/Grav/Common/Browser.php
@@ -13,6 +13,9 @@ class Browser
 {
     protected $useragent = [];
 
+    /**
+     * Browser constructor.
+     */
     public function __construct()
     {
         try {
diff --git a/system/src/Grav/Common/Cache.php b/system/src/Grav/Common/Cache.php
index f7a6d4bae..d3da1cc4a 100644
--- a/system/src/Grav/Common/Cache.php
+++ b/system/src/Grav/Common/Cache.php
@@ -1,7 +1,7 @@
 <?php
 namespace Grav\Common;
 
-use \Doctrine\Common\Cache\Cache as DoctrineCache;
+use \Doctrine\Common\Cache as DoctrineCache;
 use Grav\Common\Config\Config;
 use Grav\Common\Filesystem\Folder;
 
@@ -31,10 +31,11 @@ class Cache extends Getters
     protected $lifetime;
     protected $now;
 
+    /** @var Config $config */
     protected $config;
 
     /**
-     * @var DoctrineCache
+     * @var DoctrineCache\CacheProvider
      */
     protected $driver;
 
@@ -79,7 +80,7 @@ class Cache extends Getters
     /**
      * Constructor
      *
-     * @params Grav $grav
+     * @param Grav $grav
      */
     public function __construct(Grav $grav)
     {
@@ -127,7 +128,7 @@ class Cache extends Getters
      * If there is no config option for $driver in the config, or it's set to 'auto', it will
      * pick the best option based on which cache extensions are installed.
      *
-     * @return DoctrineCacheDriver  The cache driver to use
+     * @return DoctrineCache\CacheProvider  The cache driver to use
      */
     public function getCacheDriver()
     {
@@ -152,26 +153,26 @@ class Cache extends Getters
 
         switch ($driver_name) {
             case 'apc':
-                $driver = new \Doctrine\Common\Cache\ApcCache();
+                $driver = new DoctrineCache\ApcCache();
                 break;
 
             case 'apcu':
-                $driver = new \Doctrine\Common\Cache\ApcuCache();
+                $driver = new DoctrineCache\ApcuCache();
                 break;
 
             case 'wincache':
-                $driver = new \Doctrine\Common\Cache\WinCacheCache();
+                $driver = new DoctrineCache\WinCacheCache();
                 break;
 
             case 'xcache':
-                $driver = new \Doctrine\Common\Cache\XcacheCache();
+                $driver = new DoctrineCache\XcacheCache();
                 break;
 
             case 'memcache':
                 $memcache = new \Memcache();
                 $memcache->connect($this->config->get('system.cache.memcache.server','localhost'),
                                    $this->config->get('system.cache.memcache.port', 11211));
-                $driver = new \Doctrine\Common\Cache\MemcacheCache();
+                $driver = new DoctrineCache\MemcacheCache();
                 $driver->setMemcache($memcache);
                 break;
 
@@ -180,12 +181,12 @@ class Cache extends Getters
                 $redis->connect($this->config->get('system.cache.redis.server','localhost'),
                                 $this->config->get('system.cache.redis.port', 6379));
 
-                $driver = new \Doctrine\Common\Cache\RedisCache();
+                $driver = new DoctrineCache\RedisCache();
                 $driver->setRedis($redis);
                 break;
 
             default:
-                $driver = new \Doctrine\Common\Cache\FilesystemCache($this->cache_dir);
+                $driver = new DoctrineCache\FilesystemCache($this->cache_dir);
                 break;
         }
 
diff --git a/system/src/Grav/Common/Composer.php b/system/src/Grav/Common/Composer.php
index 5efde8912..804bc4c15 100644
--- a/system/src/Grav/Common/Composer.php
+++ b/system/src/Grav/Common/Composer.php
@@ -35,6 +35,11 @@ class Composer
         return $path;
     }
 
+    /**
+     * Return the composer executable file path
+     *
+     * @return string
+     */
     public static function getComposerExecutor()
     {
         $executor = PHP_BINARY . ' ';
diff --git a/system/src/Grav/Common/Debugger.php b/system/src/Grav/Common/Debugger.php
index 64824ff69..3a91ca502 100644
--- a/system/src/Grav/Common/Debugger.php
+++ b/system/src/Grav/Common/Debugger.php
@@ -1,8 +1,10 @@
 <?php
 namespace Grav\Common;
 
+use DebugBar\DataCollector\ConfigCollector;
 use DebugBar\JavascriptRenderer;
 use DebugBar\StandardDebugBar;
+use Grav\Common\Config\Config;
 
 /**
  * Class Debugger
@@ -10,45 +12,76 @@ use DebugBar\StandardDebugBar;
  */
 class Debugger
 {
+    /** @var Grav $grav*/
     protected $grav;
-    protected $debugbar;
+
+    /** @var Config $config */
+    protected $config;
+
+    /** @var JavascriptRenderer $renderer */
     protected $renderer;
+
+    /** @var StandardDebugBar $debugbar */
+    protected $debugbar;
+
     protected $enabled;
 
     protected $timers = [];
 
+    /**
+     * Debugger constructor.
+     */
     public function __construct()
     {
         $this->debugbar = new StandardDebugBar();
         $this->debugbar['time']->addMeasure('Loading', $this->debugbar['time']->getRequestStartTime(), microtime(true));
     }
 
+    /**
+     * Initialize the debugger
+     *
+     * @return $this
+     * @throws \DebugBar\DebugBarException
+     */
     public function init()
     {
         $this->grav = Grav::instance();
+        $this->config = $this->grav['config'];
 
         if ($this->enabled()) {
-            $this->debugbar->addCollector(new \DebugBar\DataCollector\ConfigCollector((array)$this->grav['config']->get('system'), 'Config'));
-            $this->debugbar->addCollector(new \DebugBar\DataCollector\ConfigCollector((array)$this->grav['config']->get('plugins'), 'Plugins'));
+            $this->debugbar->addCollector(new ConfigCollector((array)$this->config->get('system'), 'Config'));
+            $this->debugbar->addCollector(new ConfigCollector((array)$this->config->get('plugins'), 'Plugins'));
         }
         return $this;
     }
 
+    /**
+     * Set/get the enabled state of the debugger
+     *
+     * @param bool $state If null, the method returns the enabled value. If set, the method sets the enabled state
+     * @return null
+     */
     public function enabled($state = null)
     {
         if (isset($state)) {
             $this->enabled = $state;
         } else {
             if (!isset($this->enabled)) {
-                $this->enabled = $this->grav['config']->get('system.debugger.enabled');
+                $this->enabled = $this->config->get('system.debugger.enabled');
             }
         }
         return $this->enabled;
     }
 
+    /**
+     * Add the debugger assets to the Grav Assets
+     *
+     * @return $this
+     */
     public function addAssets()
     {
         if ($this->enabled()) {
+            /** @var Assets $assets */
             $assets = $this->grav['assets'];
 
             // Add jquery library
@@ -72,17 +105,36 @@ class Debugger
         return $this;
     }
 
+    /**
+     * Adds a data collector
+     *
+     * @param $collector
+     * @return $this
+     * @throws \DebugBar\DebugBarException
+     */
     public function addCollector($collector)
     {
         $this->debugbar->addCollector($collector);
         return $this;
     }
 
+    /**
+     * Returns a data collector
+     *
+     * @param $collector
+     * @return \DebugBar\DataCollector\DataCollectorInterface
+     * @throws \DebugBar\DebugBarException
+     */
     public function getCollector($collector)
     {
         return $this->debugbar->getCollector($collector);
     }
 
+    /**
+     * Displays the debug bar
+     *
+     * @return $this
+     */
     public function render()
     {
         if ($this->enabled()) {
@@ -91,31 +143,58 @@ class Debugger
         return $this;
     }
 
+    /**
+     * Sends the data through the HTTP headers
+     *
+     * @return $this
+     */
     public function sendDataInHeaders()
     {
         $this->debugbar->sendDataInHeaders();
         return $this;
     }
 
+    /**
+     * Start a timer with an associated name and description
+     *
+     * @param $name
+     * @param string|null $description
+     *
+     * @return $this
+     */
     public function startTimer($name, $description = null)
     {
-        if ($name[0] == '_' || $this->grav['config']->get('system.debugger.enabled')) {
+        if ($name[0] == '_' || $this->config->get('system.debugger.enabled')) {
             $this->debugbar['time']->startMeasure($name, $description);
             $this->timers[] = $name;
         }
         return $this;
     }
 
+    /**
+     * Stop the named timer
+     *
+     * @param string $name
+     * @return $this
+     */
     public function stopTimer($name)
     {
-        if (in_array($name, $this->timers) && ($name[0] == '_' || $this->grav['config']->get('system.debugger.enabled'))) {
+        if (in_array($name, $this->timers) && ($name[0] == '_' || $this->config->get('system.debugger.enabled'))) {
             $this->debugbar['time']->stopMeasure($name);
         }
 
         return $this;
     }
 
-
+    /**
+     * Dump variables into the Messages tab of the Debug Bar
+     *
+     * @param $message
+     * @param string $label
+     * @param bool $isString
+     *
+     * @return $this
+     */
     public function addMessage($message, $label = 'info', $isString = true)
     {
         if ($this->enabled()) {
diff --git a/system/src/Grav/Common/Getters.php b/system/src/Grav/Common/Getters.php
index 857dccaba..5e2372a34 100644
--- a/system/src/Grav/Common/Getters.php
+++ b/system/src/Grav/Common/Getters.php
@@ -140,7 +140,7 @@ abstract class Getters implements \ArrayAccess, \Countable
             return $this->{$var};
         } else {
             $properties = (array) $this;
-            $list = array();
+            $list = [];
             foreach ($properties as $property => $value) {
                 if ($property[0] != "\0") $list[$property] = $value;
             }
diff --git a/system/src/Grav/Common/Grav.php b/system/src/Grav/Common/Grav.php
index 1642211d2..df3e2d99f 100644
--- a/system/src/Grav/Common/Grav.php
+++ b/system/src/Grav/Common/Grav.php
@@ -1,8 +1,10 @@
 <?php
 namespace Grav\Common;
 
+use Grav\Common\Config\Config;
 use Grav\Common\Language\Language;
 use Grav\Common\Page\Medium\ImageMedium;
+use Grav\Common\Page\Page;
 use Grav\Common\Page\Pages;
 use Grav\Common\Service\ConfigServiceProvider;
 use Grav\Common\Service\ErrorServiceProvider;
@@ -34,7 +36,13 @@ class Grav extends Container
      */
     protected static $instance;
 
-    public static function instance(array $values = array())
+    /**
+     * Return the Grav instance. Create it if it's not already instanced
+     *
+     * @param array $values
+     * @return Grav
+     */
+    public static function instance(array $values = [])
     {
         if (!self::$instance) {
             self::$instance = static::load($values);
@@ -51,6 +59,12 @@ class Grav extends Container
         return self::$instance;
     }
 
+    /**
+     * Initialize and return a Grav instance
+     *
+     * @param array $values
+     * @return static
+     */
     protected static function load(array $values)
     {
         $container = new static($values);
@@ -98,7 +112,7 @@ class Grav extends Container
         };
 
         $container['pages'] = function ($c) {
-            return new Page\Pages($c);
+            return new Pages($c);
         };
 
         $container['assets'] = new Assets();
@@ -178,6 +192,9 @@ class Grav extends Container
         return $container;
     }
 
+    /**
+     * Process a request
+     */
     public function process()
     {
         /** @var Debugger $debugger */
@@ -304,10 +321,13 @@ class Grav extends Container
         if ($uri->isExternal($route)) {
             $url = $route;
         } else {
-            if ($this['config']->get('system.pages.redirect_trailing_slash', true))
-                $url = rtrim($uri->rootUrl(), '/') .'/'. trim($route, '/'); // Remove trailing slash
-            else
-                $url = rtrim($uri->rootUrl(), '/') .'/'. ltrim($route, '/'); // Support trailing slash default routes
+            $url = rtrim($uri->rootUrl(), '/') .'/';
+
+            if ($this['config']->get('system.pages.redirect_trailing_slash', true)) {
+                $url .= trim($route, '/'); // Remove trailing slash
+            } else {
+                $url .= ltrim($route, '/'); // Support trailing slash default routes
+            }
         }
 
         header("Location: {$url}", true, $code);