feat: Upgrade PHPStan level to 5 for stricter type checking

feat: Enhance Generator contract with additional methods for better configuration and generation control

feat: Update Presenter contract to enforce type safety in formatting method

feat: Improve exception handling with detailed messages for invalid running number types and max number limits

feat: Implement ConfigurationException and NumberGenerationException for better error management

test: Add comprehensive tests for edge cases, concurrency, and configuration validation in RunningNumber generation

Author: nasrulhazim

docs/06-upgrade-guide.md

@@ -2,7 +2,7 @@ includes:
     - phpstan-baseline.neon
 
 parameters:
-    level: 4
+    level: 5
     paths:
         - src
         - config

phpstan.neon.dist

@@ -2,11 +2,87 @@
 
 namespace CleaniqueCoders\RunningNumber\Contracts;
 
+/**
+ * Contract for running number generators
+ */
 interface Generator
 {
-    public static function make(): Generator;
+    /**
+     * Create a new generator instance
+     */
+    public static function make(): self;
 
-    public function formatter(Presenter $presenter): Generator;
+    /**
+     * Set a custom formatter for the running number
+     *
+     * @param  Presenter  $presenter  The presenter to format the output
+     */
+    public function formatter(Presenter $presenter): self;
 
+    /**
+     * Set the type of running number to generate
+     *
+     * @param  string  $type  The running number type
+     */
+    public function type(string $type): self;
+
+    /**
+     * Set the scope for the running number sequence
+     *
+     * @param  string|null  $scope  The scope identifier
+     */
+    public function scope(?string $scope): self;
+
+    /**
+     * Set the starting number for new sequences
+     *
+     * @param  int  $number  The starting number
+     */
+    public function startFrom(int $number): self;
+
+    /**
+     * Set the maximum number limit
+     *
+     * @param  int  $number  The maximum number
+     */
+    public function maxNumber(int $number): self;
+
+    /**
+     * Control case transformation of the type prefix
+     *
+     * @param  bool  $value  Whether to convert to uppercase
+     */
+    public function toUpperCase(bool $value): self;
+
+    /**
+     * Generate the next running number
+     *
+     * @return string The formatted running number
+     *
+     * @throws \CleaniqueCoders\RunningNumber\Exceptions\InvalidRunningNumberTypeException
+     * @throws \CleaniqueCoders\RunningNumber\Exceptions\MaxNumberReachedException
+     * @throws \CleaniqueCoders\RunningNumber\Exceptions\NumberGenerationException
+     */
     public function generate(): string;
+
+    /**
+     * Preview the next running number without incrementing
+     *
+     * @return string The formatted preview
+     *
+     * @throws \CleaniqueCoders\RunningNumber\Exceptions\InvalidRunningNumberTypeException
+     */
+    public function preview(): string;
+
+    /**
+     * Generate multiple running numbers at once
+     *
+     * @param  int  $count  The number of running numbers to generate
+     * @return array<int, string> Array of formatted running numbers
+     *
+     * @throws \CleaniqueCoders\RunningNumber\Exceptions\InvalidRunningNumberTypeException
+     * @throws \CleaniqueCoders\RunningNumber\Exceptions\MaxNumberReachedException
+     * @throws \CleaniqueCoders\RunningNumber\Exceptions\NumberGenerationException
+     */
+    public function generateBatch(int $count): array;
 }

src/Contracts/Generator.php

@@ -2,7 +2,17 @@
 
 namespace CleaniqueCoders\RunningNumber\Contracts;
 
+/**
+ * Contract for running number formatters/presenters
+ */
 interface Presenter
 {
-    public function format($type, $number): string;
+    /**
+     * Format the running number
+     *
+     * @param  string  $type  The running number type/prefix
+     * @param  int  $number  The sequence number
+     * @return string The formatted running number
+     */
+    public function format(string $type, int $number): string;
 }

src/Contracts/Presenter.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace CleaniqueCoders\RunningNumber\Exceptions;
+
+use Exception;
+
+/**
+ * Exception thrown when configuration is invalid
+ */
+class ConfigurationException extends Exception
+{
+    /**
+     * Create a new ConfigurationException instance
+     *
+     * @param  string  $message  The error message
+     * @param  int  $code  The error code
+     * @param  \Throwable|null  $previous  The previous exception
+     */
+    public function __construct(string $message = 'Invalid configuration', int $code = 0, ?\Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+}

src/Exceptions/ConfigurationException.php

@@ -4,7 +4,23 @@
 
 use Exception;
 
+/**
+ * Exception thrown when an invalid or unsupported running number type is used
+ *
+ * This occurs when attempting to generate a running number with a type
+ * that is not configured in the running-number.types array.
+ */
 class InvalidRunningNumberTypeException extends Exception
 {
-    //
+    /**
+     * Create a new InvalidRunningNumberTypeException instance
+     *
+     * @param  string  $message  The error message
+     * @param  int  $code  The error code
+     * @param  \Throwable|null  $previous  The previous exception
+     */
+    public function __construct(string $message = 'Invalid running number type', int $code = 0, ?\Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
 }

src/Exceptions/InvalidRunningNumberTypeException.php

@@ -4,10 +4,24 @@
 
 use Exception;
 
+/**
+ * Exception thrown when the maximum number limit is reached
+ *
+ * This occurs when attempting to generate a number that would exceed
+ * the configured maximum limit for a running number type.
+ */
 class MaxNumberReachedException extends Exception
 {
+    /**
+     * Create a new MaxNumberReachedException instance
+     *
+     * @param  string  $type  The running number type
+     * @param  int  $maxNumber  The maximum number limit
+     */
     public function __construct(string $type, int $maxNumber)
     {
-        parent::__construct("Maximum number {$maxNumber} reached for type {$type}");
+        parent::__construct(
+            sprintf('Maximum number %d reached for running number type "%s"', $maxNumber, $type)
+        );
     }
 }

src/Exceptions/MaxNumberReachedException.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace CleaniqueCoders\RunningNumber\Exceptions;
+
+use Exception;
+
+/**
+ * Exception thrown when number generation fails
+ */
+class NumberGenerationException extends Exception
+{
+    /**
+     * Create a new NumberGenerationException instance
+     *
+     * @param  string  $message  The error message
+     * @param  int  $code  The error code
+     * @param  \Throwable|null  $previous  The previous exception
+     */
+    public function __construct(string $message = 'Failed to generate running number', int $code = 0, ?\Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+}