feat: type hints & docs

Author: SamJUK

Console/Command/Flush.php

@@ -1,4 +1,6 @@
-<?php declare(strict_types=1);
+<?php
+
+declare(strict_types=1);
 
 namespace SamJUK\CacheDebounce\Console\Command;
 

Cron/Flush.php

@@ -1,4 +1,6 @@
-<?php declare(strict_types=1);
+<?php
+
+declare(strict_types=1);
 
 namespace SamJUK\CacheDebounce\Cron;
 
@@ -15,8 +17,8 @@ public function __construct(
         $this->cacheDebouncedEntries = $cacheDebouncedEntries;
     }
 
-    public function execute()
+    public function execute() : void
     {
-        return $this->cacheDebouncedEntries->flush();
+        $this->cacheDebouncedEntries->flush();
     }
 }

Model/Config.php

@@ -1,4 +1,6 @@
-<?php declare(strict_types=1);
+<?php
+
+declare(strict_types=1);
 
 namespace SamJUK\CacheDebounce\Model;
 
@@ -7,39 +9,55 @@
 class Config
 {
     private const XML_PATH_GENERAL_ENABLED = 'samjuk_cache_debounce/general/enabled';
-    private const XML_PATH_CRON_FLUSH = 'samjuk_cache_debounce/cron/flush';
 
+    /** @var bool $shouldDebouncePurgeRequest */
     private $shouldDebouncePurgeRequest = true;
 
+    /** @var ScopeConfigInterface $scopeConfig */
     private $scopeConfig;
-    
+
     public function __construct(
         ScopeConfigInterface $scopeConfig
     ) {
         $this->scopeConfig = $scopeConfig;
     }
 
-    public function isModuleEnabled()
+    /**
+     * Check if the module feature flag is enabled
+     */
+    public function isModuleEnabled() : bool
     {
         return $this->getFlag(self::XML_PATH_GENERAL_ENABLED);
     }
 
-    public function shouldDebouncePurgeRequest()
+    /**
+     * Check if we should debounce this purge request
+     */
+    public function shouldDebouncePurgeRequest() : bool
     {
         return $this->isModuleEnabled() && $this->shouldDebouncePurgeRequest;
     }
 
-    public function setShouldDebouncePurgeRequest($state)
+    /**
+     * Set flag to allow skipping the debounce (for flush workflows)
+     */
+    public function setShouldDebouncePurgeRequest(bool $state) : void
     {
         $this->shouldDebouncePurgeRequest = $state;
     }
 
-    private function getFlag($path, $scope = 'default', $scopeCode = null)
+    /**
+     * Fetch a system config flag
+     */
+    private function getFlag(string $path, ?string $scope = 'default', ?string $scopeCode = null) : bool
     {
         return (bool)$this->scopeConfig->isSetFlag($path, $scope, $scopeCode);
     }
 
-    private function getValue($path, $scope = 'default', $scopeCode = null)
+    /**
+     * Fetch a system config value
+     */
+    private function getValue(string $path, ?string $scope = 'default', ?string $scopeCode = null)
     {
         return $this->scopeConfig->getValue($path, $scope, $scopeCode);
     }

Model/Entries.php

@@ -1,4 +1,6 @@
-<?php declare(strict_types=1);
+<?php
+
+declare(strict_types=1);
 
 namespace SamJUK\CacheDebounce\Model;
 
@@ -9,10 +11,19 @@
 
 class Entries
 {
+    /** @var string $tableName */
     private $tableName;
+
+    /** @var ResourceConnection $resourceConnection */
     private $resourceConnection;
+
+    /** @var PurgeCache $purgeCache */
     private $purgeCache;
+
+    /** @var Config $config */
     private $config;
+
+    /** @var LoggerInterface $logger */
     private $logger;
 
     public function __construct(
@@ -28,20 +39,29 @@ public function __construct(
         $this->tableName = $resourceConnection->getTableName('samjuk_cache_debounce');
     }
 
-    public function add($tags)
+    /**
+     * Add new tags to the purge queue
+     */
+    public function add(array $tags) : void
     {
         $this->resourceConnection->getConnection()
             ->insertArray($this->tableName, ['tag'], $tags);
     }
 
-    public function get()
+    /**
+     * Get all tags from the purge queue
+     */
+    public function get() : array
     {
         $connection = $this->resourceConnection->getConnection();
         $query = $connection->select()->from($this->tableName, 'tag')->distinct();
         return $connection->fetchCol($query);
     }
 
-    public function flush()
+    /**
+     * Purge all queued tags, and clear the queue
+     */
+    public function flush() : void
     {
         $tags = $this->get();
         if (count($tags) > 0) {

Plugin/PurgeCache.php

@@ -1,4 +1,6 @@
-<?php declare(strict_types=1);
+<?php
+
+declare(strict_types=1);
 
 namespace SamJUK\CacheDebounce\Plugin;
 
@@ -8,8 +10,10 @@
 
 class PurgeCache
 {
+    /** @var Config $config **/
     private $config;
 
+    /** @var CacheDebounceEntries $cacheDebouncedEntries */
     private $cacheDebouncedEntries;
 
     public function __construct(
@@ -21,12 +25,14 @@ public function __construct(
     }
 
     /**
+     * Prevent flushing varnish now, and push the tag into a queue to flush later, if required.
+     *
      * @param \Magento\CacheInvalidate\Model\PurgeCache $subject
      * @param callable $proceed
      * @param array|string $tags
      * @return bool
      */
-    public function aroundSendPurgeRequest(Subject $subject, callable $proceed, $tags)
+    public function aroundSendPurgeRequest(Subject $subject, callable $proceed, $tags) : bool
     {
         if (!$this->config->shouldDebouncePurgeRequest()) {
             return $proceed($tags);

Test/Unit/Plugin/PurgeCacheTest.php

@@ -41,7 +41,8 @@ public function testPluginSkipsDebouncePurgeRequest()
             ->willReturn(false);
 
         $purgeCacheModel->expects($this->once())
-            ->method('sendPurgeRequest');
+            ->method('sendPurgeRequest')
+            ->willReturn(true);
 
         $purgeCachePlugin->aroundSendPurgeRequest(
             $purgeCacheModel,