From 271dc2939c95653e416008984dbbfd49853de4c4 Mon Sep 17 00:00:00 2001
From: Sam Lee <cable8mm@gmail.com>
Date: Mon, 24 Feb 2025 16:50:17 +0900
Subject: [PATCH] Add `BoxCode` class

---
 README.md             | 12 ++++++
 src/BoxCode.php       | 97 +++++++++++++++++++++++++++++++++++++++++++
 tests/BoxCodeTest.php | 42 +++++++++++++++++++
 3 files changed, 151 insertions(+)
 create mode 100644 src/BoxCode.php
 create mode 100644 tests/BoxCodeTest.php

diff --git a/README.md b/README.md
index ce2dddf..9d885d6 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@ We have provided the API Documentation on the web. For more information, please
 - [x] Option Good code parser(No code, it matched by name)
 - [x] Receipt code parser
 - [x] Location code parser
+- [x] Box code parser
 
 ## Install
 
@@ -212,6 +213,17 @@ print LocationCode::of(warehouse: 'AUK', rack: 'R3', shelf: 'S32'); //` Stringab
 //=> AUK-R3-S32
 ```
 
+### Box Code
+
+```php
+print BoxCode::of(code: 123, prefix: 'PO');     //=> PO123
+print BoxCode::of([
+    'code' => 123, 'prefix' => 'PO'
+    ])->boxCode();                              //=> PO123
+print BoxCode::of(123)->boxCode();              //=> 123
+print BoxCode::of(123, prefix: 'PO');           //=> PO123
+```
+
 ## Formatting
 
 ```sh
diff --git a/src/BoxCode.php b/src/BoxCode.php
new file mode 100644
index 0000000..7018526
--- /dev/null
+++ b/src/BoxCode.php
@@ -0,0 +1,97 @@
+<?php
+
+namespace Cable8mm\GoodCode;
+
+use Stringable;
+
+/**
+ * This class represents a box code identified by code and prefix. The box code is generated from these properties.
+ *
+ * @author Samgu Lee <cable8mm@gmail.com>
+ *
+ * @since  2025-02-24
+ */
+class BoxCode implements Stringable
+{
+    /**
+     * Code representing the box
+     *
+     * @example BO123
+     */
+    private string $boxCode;
+
+    private function __construct(
+        /**
+         * Box code
+         *
+         * @example 123
+         */
+        private string|int $code,
+        /**
+         * Prefix
+         *
+         * @example BO
+         */
+        private ?string $prefix = null
+    ) {
+        $this->boxCode = $prefix.$code;
+    }
+
+    /**
+     * Get the box code.
+     *
+     * @return string The method returns the box code
+     *
+     * @example print BoxCode::of(123, prefix: 'BO')->boxCode();    => 'BO123'
+     * @example print BoxCode::of(123, prefix: 'BO');               => 'BO123'
+     */
+    public function boxCode(): string
+    {
+        return $this->boxCode;
+    }
+
+    /**
+     * Create a new box code instance.
+     *
+     * @param  string|int  $code  The box code
+     * @param  string|null  $prefix  Prefix for the box code
+     * @return self Provides fluent interface
+     *
+     * @throws \InvalidArgumentException
+     */
+    public static function of(
+        string|int|array $code,
+        ?string $prefix = null
+    ): self {
+        if (is_array($code)) {
+            $disallowedKeys = array_diff_key($code, array_flip(['code', 'prefix']));
+
+            if (! empty($disallowedKeys)) {
+                throw new \InvalidArgumentException('Invalid key(s): '.implode(', ', array_keys($disallowedKeys)));
+            }
+
+            return new self(
+                code: $code['code'],
+                prefix: $code['prefix'] ?? null
+            );
+        }
+
+        return new self(
+            code: $code,
+            prefix: $prefix
+        );
+    }
+
+    /**
+     * Get the string representation of the box code.
+     *
+     * @return string The magic method returns the box code
+     *
+     * @example print BoxCode::of('1') => 'A1'
+     * @example print BoxCode::of('1', prefix: 'BO') => 'BO1'
+     */
+    public function __toString(): string
+    {
+        return $this->boxCode;
+    }
+}
diff --git a/tests/BoxCodeTest.php b/tests/BoxCodeTest.php
new file mode 100644
index 0000000..84294e4
--- /dev/null
+++ b/tests/BoxCodeTest.php
@@ -0,0 +1,42 @@
+<?php
+
+namespace Cable8mm\GoodCode\Tests;
+
+use Cable8mm\GoodCode\BoxCode;
+use PHPUnit\Framework\TestCase;
+
+class BoxCodeTest extends TestCase
+{
+    public function test_full_box_code()
+    {
+        $this->assertEquals('PO123', BoxCode::of(
+            123,
+            prefix: 'PO'
+        )->boxCode());
+
+        $this->assertEquals('PO123', BoxCode::of([
+            'code' => 123,
+            'prefix' => 'PO',
+        ]));
+    }
+
+    public function test_box_code_without_prefix()
+    {
+        $this->assertEquals('123', BoxCode::of(
+            123
+        )->boxCode());
+
+        $this->assertEquals('123', BoxCode::of([
+            'code' => 123,
+        ]));
+    }
+
+    public function test_location_code_with_empty()
+    {
+        $this->expectException(\InvalidArgumentException::class);
+
+        BoxCode::of([
+            'wrong' => 'key',
+        ]);
+    }
+}