phpcs

Author: TomHAnderson

.gitignore

@@ -1,3 +1,4 @@
 /vendor/
 composer.lock
 /.idea/
+/.phpcs-cache

phpcs.xml.dist

@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<ruleset>
+    <arg name="basepath" value="."/>
+    <arg name="extensions" value="php"/>
+    <arg name="parallel" value="80"/>
+    <arg name="cache" value=".phpcs-cache"/>
+    <arg name="colors"/>
+
+    <!-- Ignore warnings, show progress of the run and show sniff names -->
+    <arg value="nps"/>
+
+    <!-- Directories to be checked -->
+    <file>src</file>
+
+    <exclude-pattern>src/Entity/*</exclude-pattern>
+
+    <!-- Include full Doctrine Coding Standard -->
+    <rule ref="Doctrine">
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousExceptionNaming.SuperfluousSuffix"/>
+        <exclude name="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming.SuperfluousSuffix"/>
+    </rule>
+</ruleset>

src/ApiProblem.php

@@ -4,14 +4,15 @@
 
 namespace ApiSkeletons\Laravel\ApiProblem;
 
-use Exception;
 use ApiSkeletons\Laravel\ApiProblem\Exception\InvalidArgumentException;
 use ApiSkeletons\Laravel\ApiProblem\Exception\ProblemExceptionInterface;
+use Exception;
 use Throwable;
 
 use function array_key_exists;
 use function array_keys;
 use function array_merge;
+use function assert;
 use function count;
 use function get_class;
 use function in_array;
@@ -33,45 +34,37 @@ class ApiProblem
     /**
      * Additional details to include in report.
      *
-     * @var array
+     * @var string[]
      */
-    protected $additionalDetails = [];
+    protected array $additionalDetails = [];
 
     /**
      * URL describing the problem type; defaults to HTTP status codes.
-     *
-     * @var string
      */
-    protected $type = 'http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html';
+    protected string $type = 'http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html';
 
     /**
      * Description of the specific problem.
-     *
-     * @var string|Exception|Throwable
      */
-    protected $detail = '';
+    protected string|Throwable|Throwable $detail = '';
 
     /**
      * Whether or not to include a stack trace and previous
      * exceptions when an exception is provided for the detail.
-     *
-     * @var bool
      */
-    protected $detailIncludesStackTrace = false;
+    protected bool $detailIncludesStackTrace = false;
 
     /**
      * HTTP status for the error.
-     *
-     * @var int
      */
-    protected $status;
+    protected int $status;
 
     /**
      * Normalized property names for overloading.
      *
-     * @var array
+     * @var string[]
      */
-    protected $normalizedProperties = [
+    protected array $normalizedProperties = [
         'type'   => 'type',
         'status' => 'status',
         'title'  => 'title',
@@ -81,9 +74,9 @@ class ApiProblem
     /**
      * Status titles for common problems.
      *
-     * @var array
+     * @var string[]
      */
-    protected $problemStatusTitles = [
+    protected array $problemStatusTitles = [
         // CLIENT ERROR
         400 => 'Bad Request',
         401 => 'Unauthorized',
@@ -127,32 +120,28 @@ class ApiProblem
 
     /**
      * Title of the error.
-     *
-     * @var string
      */
-    protected $title;
+    protected string $title;
 
     /**
      * Create an instance using the provided information. If nothing is
      * provided for the type field, the class default will be used;
      * if the status matches any known, the title field will be selected
      * from $problemStatusTitles as a result.
      *
-     * @param int|string $status
-     * @param string|Exception|Throwable $detail
-     * @param string $type
-     * @param string $title
-     * @param array  $additional
+     * @param string[] $additional
      */
-    public function __construct($status, $detail, $type = null, $title = null, array $additional = [])
+    public function __construct(int|string $status, string|Throwable|Throwable $detail, ?string $type = null, ?string $title = null, array $additional = [])
     {
         if ($detail instanceof ProblemExceptionInterface) {
-            if (null === $type) {
+            if ($type === null) {
                 $type = $detail->getType();
             }
-            if (null === $title) {
+
+            if ($title === null) {
                 $title = $detail->getTitle();
             }
+
             if (empty($additional)) {
                 $additional = $detail->getAdditionalDetails();
             }
@@ -171,7 +160,7 @@ public function __construct($status, $detail, $type = null, $title = null, array
         $this->detail = $detail;
         $this->title  = $title;
 
-        if (null !== $type) {
+        if ($type !== null) {
             $this->type = $type;
         }
 
@@ -181,11 +170,9 @@ public function __construct($status, $detail, $type = null, $title = null, array
     /**
      * Retrieve properties.
      *
-     * @param string $name
-     * @return mixed
      * @throws InvalidArgumentException
      */
-    public function __get($name)
+    public function __get(string $name): mixed
     {
         $normalized = strtolower($name);
         if (in_array($normalized, array_keys($this->normalizedProperties))) {
@@ -211,28 +198,26 @@ public function __get($name)
     /**
      * Cast to an array.
      *
-     * @return array
+     * @return string[]
      */
-    public function toArray()
+    public function toArray(): array
     {
         $problem = [
             'type'   => $this->type,
             'title'  => $this->getTitle(),
             'status' => $this->getStatus(),
             'detail' => $this->getDetail(),
         ];
+
         // Required fields should always overwrite additional fields
         return array_merge($this->additionalDetails, $problem);
     }
 
     /**
      * Set the flag indicating whether an exception detail should include a
      * stack trace and previous exception information.
-     *
-     * @param bool $flag
-     * @return ApiProblem
      */
-    public function setDetailIncludesStackTrace($flag)
+    public function setDetailIncludesStackTrace(bool $flag): ApiProblem
     {
         $this->detailIncludesStackTrace = (bool) $flag;
 
@@ -244,10 +229,8 @@ public function setDetailIncludesStackTrace($flag)
      *
      * If an exception was provided, creates the detail message from it;
      * otherwise, detail as provided is used.
-     *
-     * @return string
      */
-    protected function getDetail()
+    protected function getDetail(): string
     {
         if ($this->detail instanceof Throwable || $this->detail instanceof Exception) {
             return $this->createDetailFromException();
@@ -281,17 +264,15 @@ protected function getStatus(): int
      * string 'Unknown'.
      *
      * Otherwise, use the title provided.
-     *
-     * @return string
      */
-    protected function getTitle()
+    protected function getTitle(): string
     {
-        if (null !== $this->title) {
+        if ($this->title !== null) {
             return $this->title;
         }
 
         if (
-            null === $this->title
+            $this->title === null
             && $this->type === 'http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html'
             && array_key_exists($this->getStatus(), $this->problemStatusTitles)
         ) {
@@ -302,7 +283,7 @@ protected function getTitle()
             return get_class($this->detail);
         }
 
-        if (null === $this->title) {
+        if ($this->title === null) {
             return 'Unknown';
         }
 
@@ -311,13 +292,11 @@ protected function getTitle()
 
     /**
      * Create detail message from an exception.
-     *
-     * @return string
      */
-    protected function createDetailFromException()
+    protected function createDetailFromException(): string
     {
-        /** @var Exception|Throwable $e */
         $e = $this->detail;
+        assert($e instanceof Exception || $e instanceof Throwable);
 
         if (! $this->detailIncludesStackTrace) {
             return $e->getMessage();
@@ -336,6 +315,7 @@ protected function createDetailFromException()
             ];
             $e          = $e->getPrevious();
         }
+
         if (count($previous)) {
             $this->additionalDetails['exception_stack'] = $previous;
         }
@@ -345,13 +325,11 @@ protected function createDetailFromException()
 
     /**
      * Create HTTP status from an exception.
-     *
-     * @return int|string
      */
-    protected function createStatusFromException()
+    protected function createStatusFromException(): int|string
     {
-        /** @var Exception|Throwable $e */
-        $e      = $this->detail;
+        $e = $this->detail;
+        assert($e instanceof Exception || $e instanceof Throwable);
         $status = $e->getCode();
 
         if ($status) {

src/Exception/ProblemExceptionInterface.php

@@ -11,18 +11,9 @@
  */
 interface ProblemExceptionInterface
 {
-    /**
-     * @return null|array|Traversable
-     */
-    public function getAdditionalDetails();
+    public function getAdditionalDetails(): array|Traversable|null;
 
-    /**
-     * @return string
-     */
-    public function getType();
+    public function getType(): string;
 
-    /**
-     * @return string
-     */
-    public function getTitle();
+    public function getTitle(): string;
 }