feat: Fluent setters, getters, allow logging to be disabled

Add in fluent setters for the class dependencies. Add getters for the class dependencies. Add method to disable logging even if a logger is provided. Change logging levels for most debug calls to info. Refactor request sending to remove duplicated code. Add in class name to logging messages, and add timestamp and other class details to logging context. Refactor getContext to only throw CannotGetContextException and CannotCreateContextExceptions.
brandon14 · Nov 1, 2023 · 6d9c524 · 6d9c524
1 parent 102eeff
commit 6d9c524
Show file tree

Hide file tree

Showing 17 changed files with 725 additions and 115 deletions.
diff --git a/TODO.md b/TODO.md
@@ -3,3 +3,6 @@
 - Fix Psalm configs.
 - Fix CI workflow.
 - Get docs built using doctum and publish on Github.
+- Enhance exceptions thrown and logging.
+- Write tests to more completely test logging.
+- Set up PHPStan.
diff --git a/composer.json b/composer.json
@@ -50,6 +50,7 @@
         "pestphp/pest": "^1.23.1",
         "pestphp/pest-plugin-parallel": "^1.2",
         "phpmd/phpmd": "^2.14",
+        "phpstan/phpstan": "^1.10",
         "roave/security-advisories": "dev-latest",
         "squizlabs/php_codesniffer": "^3.7",
         "symfony/thanks": "^1.2",
@@ -62,6 +63,7 @@
         "analyze:psalm": "psalm",
         "analyze:stats": "@composer run-script analyze:psalm -- --stats",
         "analyze:insights": "phpinsights",
+        "analyze:phpstan": "phpstan analyse",
         "composer:validate": "@composer validate --no-check-all --strict",
         "lint:phpcs:check": "phpcs ./",
         "lint:phpcs:fix": "phpcbf ./",

diff --git a/phpmd.xml.dist b/phpmd.xml.dist
@@ -10,18 +10,12 @@
 
     <rule ref="rulesets/cleancode.xml">
         <exclude name="StaticAccess"/>
-        <exclude name="BooleanArgumentFlag"/>
     </rule>
     <rule ref="rulesets/cleancode.xml/StaticAccess">
         <properties>
             <property name="ignorepattern" value="/^create.*/i" />
         </properties>
     </rule>
-    <rule ref="rulesets/cleancode.xml/BooleanArgumentFlag">
-        <properties>
-            <property name="ignorepattern" value="/^runCommand.*/i" />
-        </properties>
-    </rule>
     <rule ref="rulesets/codesize.xml">
         <exclude name="TooManyPublicMethods"/>
         <exclude name="ExcessiveParameterList"/>
@@ -42,7 +36,7 @@
     </rule>
     <rule ref="rulesets/design.xml/CouplingBetweenObjects">
         <properties>
-            <property name="maximum" value="20" />
+            <property name="maximum" value="25" />
         </properties>
     </rule>
     <rule ref="rulesets/naming.xml">

diff --git a/phpstan.neon.dist b/phpstan.neon.dist
@@ -0,0 +1,5 @@
+parameters:
+    level: 9
+    paths:
+        - src
+        - tests
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
@@ -12,11 +12,6 @@
             <directory suffix="Test.php">./tests</directory>
         </testsuite>
     </testsuites>
-    <source>
-        <include>
-            <directory suffix=".php">./src</directory>
-        </include>
-    </source>
     <coverage processUncoveredFiles="true">
         <include>
             <directory suffix=".php">./src</directory>

diff --git a/psalm.xml.dist b/psalm.xml.dist
@@ -1,6 +1,9 @@
 <?xml version="1.0"?>
 <psalm xmlns="https://getpsalm.org/schema/config"
-       checkForThrowsDocblock="true">
+       checkForThrowsDocblock="true"
+       findUnusedBaselineEntry="true"
+       findUnusedCode="true"
+>
 
     <projectFiles>
         <directory name="src" />

diff --git a/src/Context/FossabotChannel.php b/src/Context/FossabotChannel.php
@@ -107,17 +107,17 @@ private function __construct(
     public static function createFromBody(array $body): FossabotChannelInterface
     {
         return new self(
-            $body['id'] ?? null,
-            $body['login'] ?? null,
-            $body['display_name'] ?? null,
-            $body['avatar'] ?? null,
-            $body['slug'] ?? null,
-            $body['broadcaster_type'] ?? null,
-            $body['provider'] ?? null,
-            $body['provider_id'] ?? null,
+            $body['id'],
+            $body['login'],
+            $body['display_name'],
+            $body['avatar'],
+            $body['slug'],
+            $body['broadcaster_type'],
+            $body['provider'],
+            $body['provider_id'],
             new DateTimeImmutable($body['created_at']),
             new DateTimeImmutable($body['stream_timestamp']),
-            $body['is_live'] ?? null,
+            $body['is_live'],
         );
     }
 

diff --git a/src/Context/FossabotDataModel.php b/src/Context/FossabotDataModel.php
@@ -131,14 +131,6 @@ public function __unserialize(array $data): void
         $this->data = $data;
     }
 
-    /**
-     * {@inheritDoc}
-     */
-    public function __toString(): string
-    {
-        return $this->toString();
-    }
-
     /**
      * @param string $name Offset name
      */
@@ -200,6 +192,14 @@ public function toString(): string
         return $this->toJson();
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public function __toString(): string
+    {
+        return $this->toString();
+    }
+
     /**
      * {@inheritDoc}
      */

diff --git a/src/Context/FossabotMessage.php b/src/Context/FossabotMessage.php
@@ -74,10 +74,10 @@ private function __construct(
     public static function createFromBody(array $body): FossabotMessageInterface
     {
         return new self(
-            $body['id'] ?? null,
-            $body['content'] ?? null,
-            $body['provider'] ?? null,
-            FossabotUser::createFromBody($body['user'] ?? null),
+            $body['id'],
+            $body['content'],
+            $body['provider'],
+            FossabotUser::createFromBody($body['user']),
         );
     }
 

diff --git a/src/Context/FossabotRole.php b/src/Context/FossabotRole.php
@@ -68,9 +68,9 @@ private function __construct(string $id, string $name, string $type)
     public static function createFromBody(array $body): FossabotRoleInterface
     {
         return new self(
-            $body['id'] ?? null,
-            $body['name'] ?? null,
-            $body['type'] ?? null,
+            $body['id'],
+            $body['name'],
+            $body['type'],
         );
     }
 

diff --git a/src/Context/FossabotUser.php b/src/Context/FossabotUser.php
@@ -76,9 +76,9 @@ public static function createFromBody(array $body): FossabotUserInterface
         }
 
         return new self(
-            $body['provider_id'] ?? null,
-            $body['login'] ?? null,
-            $body['display_name'] ?? null,
+            $body['provider_id'],
+            $body['login'],
+            $body['display_name'],
             $roles,
         );
     }

diff --git a/src/Contracts/Exceptions/NoValidLoggerProvidedException.php b/src/Contracts/Exceptions/NoValidLoggerProvidedException.php
@@ -0,0 +1,43 @@
+<?php
+
+/**
+ * This file is part of the brandon14/fossabot-commander package.
+ *
+ * MIT License
+ *
+ * Copyright (c) 2023 Brandon Clothier
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ */
+
+declare(strict_types=1);
+
+namespace Brandon14\FossabotCommander\Contracts\Exceptions;
+
+/**
+ * Exception thrown when enabling logging for the {@link \Brandon14\FossabotCommander\Contracts\FossabotCommander} class
+ * when no {@link \Psr\Log\LoggerInterface} has been provided.
+ *
+ * @author Brandon Clothier <brandon14125@gmail.com>
+ */
+final class NoValidLoggerProvidedException extends FossabotCommanderException
+{
+    // Intentionally left blank.
+}
diff --git a/src/Contracts/Exceptions/RateLimitException.php b/src/Contracts/Exceptions/RateLimitException.php
@@ -31,10 +31,11 @@
 
 namespace Brandon14\FossabotCommander\Contracts\Exceptions;
 
-use Exception;
 use Throwable;
 use DateTimeImmutable;
 
+use function date_create_immutable;
+
 /**
  * Exception thrown when making a Fossabot API call and it results in a rate limit throttled response (429).
  *
@@ -68,8 +69,6 @@ final class RateLimitException extends FossabotApiException
      * @param int            $resetsAt     Time when rate limit bucket is refilled
      * @param array|null     $body         Parsed HTTP body from Fossabot API exception
      * @param Throwable|null $previous     Previous exception
-     *
-     * @throws Exception
      */
     public function __construct(
         string $fossabotCode,
@@ -83,7 +82,15 @@ public function __construct(
     ) {
         $this->total = $total;
         $this->remaining = $remaining;
-        $this->resetsAt = (new DateTimeImmutable())->setTimestamp($resetsAt);
+
+        // This should never happen.
+        // @codeCoverageIgnoreStart
+        try {
+            $this->resetsAt = (new DateTimeImmutable())->setTimestamp($resetsAt);
+        } catch (Throwable $exception) {
+            $this->resetsAt = date_create_immutable()->setTimestamp($resetsAt);
+        }
+        // @codeCoverageIgnoreEnd
 
         parent::__construct(
             $fossabotCode,

diff --git a/src/Contracts/FossabotCommander.php b/src/Contracts/FossabotCommander.php
@@ -31,6 +31,10 @@
 
 namespace Brandon14\FossabotCommander\Contracts;
 
+use Psr\Log\LoggerInterface;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\RequestFactoryInterface;
+
 /**
  * Main class to invoke a given {@link \Brandon14\FossabotCommander\Contracts\FossabotCommand} instance.
  *
@@ -40,6 +44,92 @@
  */
 interface FossabotCommander
 {
+    /**
+     * Get {@link \Psr\Http\Client\ClientInterface} instance.
+     *
+     * @return \Psr\Http\Client\ClientInterface PSR HTTP client instance
+     */
+    public function getHttpClient(): ClientInterface;
+
+    /**
+     * Set a new {@link \Psr\Http\Client\ClientInterface} instance.
+     *
+     * @param \Psr\Http\Client\ClientInterface $httpClient PSR HTTP client interface
+     *
+     * @return $this
+     */
+    public function setHttpClient(ClientInterface $httpClient): self;
+
+    /**
+     * Get {@link \Psr\Http\Message\RequestFactoryInterface} instance.
+     *
+     * @return \Psr\Http\Message\RequestFactoryInterface Request factory instance
+     */
+    public function getRequestFactory(): RequestFactoryInterface;
+
+    /**
+     * Set a new {@link \Psr\Http\Message\RequestFactoryInterface} instance.
+     *
+     * @param \Psr\Http\Message\RequestFactoryInterface $requestFactory PSR request factory instance
+     *
+     * @return $this
+     */
+    public function setRequestFactory(RequestFactoryInterface $requestFactory): self;
+
+    /**
+     * Get {@link \Psr\Log\LoggerInterface} instance.
+     *
+     * @return \Psr\Log\LoggerInterface|null Logger instance
+     */
+    public function getLogger(): ?LoggerInterface;
+
+    /**
+     * Fluent setter for setting a new {@link \Psr\Log\LoggerInterface} instance.
+     *
+     * @param \Psr\Log\LoggerInterface|null $logger PSR logger instance
+     *
+     * @throws \Brandon14\FossabotCommander\Contracts\Exceptions\NoValidLoggerProvidedException
+     *
+     * @return $this
+     */
+    public function setLog(?LoggerInterface $logger): self;
+
+    /**
+     * Enable logging. Will throw an {@link \Brandon14\FossabotCommander\Contracts\Exceptions\NoValidLoggerProvidedException}
+     * when enabling this without providing a valid {@link \Psr\Log\LoggerInterface} instance.
+     *
+     * @throws \Brandon14\FossabotCommander\Contracts\Exceptions\NoValidLoggerProvidedException
+     *
+     * @return $this
+     */
+    public function enableLogging(): self;
+
+    /**
+     * Disables logging for the {@link \Brandon14\FossabotCommander\Contracts\FossabotCommander} instance.
+     */
+    public function disableLogging(): self;
+
+    /**
+     * Sets whether to log or not for the {@link \Brandon14\FossabotCommander\Contracts\FossabotCommander} instance.
+     * If enabling, and no valid PSR logging is provided, it will throw an exception.
+     *
+     * @SuppressWarnings(PHPMD.BooleanArgumentFlag)
+     *
+     * @param bool $logging Whether to enable logging or not
+     *
+     * @throws \Brandon14\FossabotCommander\Contracts\Exceptions\NoValidLoggerProvidedException
+     */
+    public function setLogging(bool $logging): self;
+
+    /**
+     * Gets the configured logging setting.
+     *
+     * @SuppressWarnings(PHPMD.BooleanGetMethodName)
+     *
+     * @return bool Logging
+     */
+    public function getLogging(): bool;
+
     /**
      * Will execute a given {@link \Brandon14\FossabotCommander\Contracts\FossabotCommand} instance. If this method
      * throws a {@link \Brandon14\FossabotCommander\Contracts\Exceptions\CannotValidateRequestException}, then it was
@@ -54,6 +144,8 @@ interface FossabotCommander
      *
      * @see https://docs.fossabot.com/variables/customapi#list-of-common-headers
      *
+     * @SuppressWarnings(PHPMD.BooleanArgumentFlag)
+     *
      * @param \Brandon14\FossabotCommander\Contracts\FossabotCommand $command        Fossabot command instance
      * @param string                                                 $customApiToken Fossabot API token to validate and
      *                                                                               get data from
@@ -62,9 +154,7 @@ interface FossabotCommander
      *                                                                               command
      *
      * @throws \Brandon14\FossabotCommander\Contracts\Exceptions\RateLimitException
-     * @throws \Brandon14\FossabotCommander\Contracts\Exceptions\JsonParsingException
      * @throws \Brandon14\FossabotCommander\Contracts\Exceptions\CannotGetContextException
-     * @throws \Brandon14\FossabotCommander\Contracts\Exceptions\FossabotCommanderException
      * @throws \Brandon14\FossabotCommander\Contracts\Exceptions\CannotCreateContextException
      * @throws \Brandon14\FossabotCommander\Contracts\Exceptions\CannotValidateRequestException
      *
@@ -75,4 +165,9 @@ public function runCommand(
         string $customApiToken,
         bool $getContext = true
     ): string;
+
+    /**
+     * Gets general class information used for providing additional logging context.
+     */
+    public function getLoggingContext(): array;
 }