From 5adc6c94f3b6f67476af09c949a37900aad18a86 Mon Sep 17 00:00:00 2001
From: Marc Beinder <50760632+onairmarc@users.noreply.github.com>
Date: Wed, 6 Nov 2024 09:21:17 -0600
Subject: [PATCH] Add Deprecations (#27)

Co-authored-by: onairmarc <onairmarc@users.noreply.github.com>
---
 .git-blame-ignore-revs                        |  1 +
 .../DirectoryNotFoundException.php            |  4 ++--
 .../FileNotFoundException.php                 |  4 ++--
 .../ImproperBooleanReturnedException.php      |  2 +-
 src/Exceptions/NotImplementedException.php    |  2 +-
 src/ObjectHelpers/arr_helpers.php             |  2 ++
 src/ObjectHelpers/dir_helpers.php             | 19 ++++++++++++++++---
 src/ObjectHelpers/file_helpers.php            | 12 ++++++++++--
 src/ObjectHelpers/num_helpers.php             |  1 +
 src/ObjectHelpers/php_function_helpers.php    |  2 --
 src/ObjectHelpers/str_helpers.php             | 13 +++++++++++--
 src/ObjectHelpers/val_helpers.php             |  3 ++-
 src/Objects/Arr.php                           | 19 +++++++++++--------
 src/Objects/Directory.php                     |  6 +-----
 src/Objects/File.php                          |  6 +-----
 src/Objects/Json.php                          |  6 +-----
 src/Objects/Number.php                        |  6 +-----
 src/Objects/Php.php                           |  6 +-----
 src/Objects/Str.php                           |  6 +-----
 src/Objects/Url.php                           |  6 +-----
 src/Objects/Value.php                         |  2 --
 21 files changed, 67 insertions(+), 61 deletions(-)

diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
index 1a4c313..9aecb23 100644
--- a/.git-blame-ignore-revs
+++ b/.git-blame-ignore-revs
@@ -13,3 +13,4 @@ c10c3ac2613e54de290a9135afe024036174ef20
 aef6f8b59ab2ff054b1a823efe242e0cb0cd1164
 d521d82e9b14a5f411f3492529800c6b39f17740
 11b88b5f8641574fc93d2a4f443aeaf819381c91
+f74b50a0c5a93e2042dd0899f67dc0d77d9f37b2
diff --git a/src/Exceptions/FilesystemExceptions/DirectoryNotFoundException.php b/src/Exceptions/FilesystemExceptions/DirectoryNotFoundException.php
index a7d2fd6..4ed60b2 100644
--- a/src/Exceptions/FilesystemExceptions/DirectoryNotFoundException.php
+++ b/src/Exceptions/FilesystemExceptions/DirectoryNotFoundException.php
@@ -10,9 +10,9 @@ class DirectoryNotFoundException extends BaseException
     public function __construct(?string $path = null)
     {
         if (is_null($path)) {
-            $msg = str_concat_space('Unable to locate directory on line', $this->line, 'in', $this->file);
+            $msg = "Unable to locate directory on line {$this->line} in {$this->file}";
         } else {
-            $msg = str_concat_space('Unable to locate directory', $path, 'on line', $this->line, 'in', $this->file);
+            $msg = "Unable to locate directory {$path} on line {$this->line} in {$this->file}";
         }
 
         parent::__construct($msg, ExitCode::RESOURCE_UNAVAILABLE, $this->getPrevious());
diff --git a/src/Exceptions/FilesystemExceptions/FileNotFoundException.php b/src/Exceptions/FilesystemExceptions/FileNotFoundException.php
index 6160bd8..c9ca923 100644
--- a/src/Exceptions/FilesystemExceptions/FileNotFoundException.php
+++ b/src/Exceptions/FilesystemExceptions/FileNotFoundException.php
@@ -10,9 +10,9 @@ class FileNotFoundException extends BaseException
     public function __construct(?string $path = null)
     {
         if (is_null($path)) {
-            $msg = str_concat_space('Unable to locate file on line', $this->line, 'in', $this->file);
+            $msg = "Unable to locate file on line {$this->line} in {$this->file}";
         } else {
-            $msg = str_concat_space('Unable to locate file', $path, 'on line', $this->line, 'in', $this->file);
+            $msg = "Unable to locate file {$path} on line {$this->line} in {$this->file}";
         }
 
         parent::__construct($msg, ExitCode::RESOURCE_UNAVAILABLE, $this->getPrevious());
diff --git a/src/Exceptions/ImproperBooleanReturnedException.php b/src/Exceptions/ImproperBooleanReturnedException.php
index 3cb026c..7c502c4 100644
--- a/src/Exceptions/ImproperBooleanReturnedException.php
+++ b/src/Exceptions/ImproperBooleanReturnedException.php
@@ -16,7 +16,7 @@ public function __construct(bool $expected = true)
             $actual = 'true';
         }
 
-        $msg = str_concat_space('Improper boolean returned. Expected', $expect, 'but got', $actual);
+        $msg = "Improper boolean returned. Expected {$expect} but got {$actual}";
 
         parent::__construct($msg, ExitCode::DATA_ERROR, $this->getPrevious());
     }
diff --git a/src/Exceptions/NotImplementedException.php b/src/Exceptions/NotImplementedException.php
index 3f704bd..94ce1f3 100644
--- a/src/Exceptions/NotImplementedException.php
+++ b/src/Exceptions/NotImplementedException.php
@@ -8,7 +8,7 @@ class NotImplementedException extends BaseException
 {
     public function __construct()
     {
-        $msg = str_concat_space('Method is not implemented on line', $this->line, 'in', $this->file);
+        $msg = "Method is not implemented on line {$this->line} in {$this->file}";
 
         parent::__construct($msg, ExitCode::RESOURCE_UNAVAILABLE, $this->getPrevious());
     }
diff --git a/src/ObjectHelpers/arr_helpers.php b/src/ObjectHelpers/arr_helpers.php
index 39c7654..0fb129d 100644
--- a/src/ObjectHelpers/arr_helpers.php
+++ b/src/ObjectHelpers/arr_helpers.php
@@ -6,6 +6,8 @@
 if (!function_exists('arr_to_short_syntax')) {
     /**
      * @throws ArgumentNullException
+     *
+     * @deprecated No Replacement
      */
     function arr_to_short_syntax(array|string $value): array|string
     {
diff --git a/src/ObjectHelpers/dir_helpers.php b/src/ObjectHelpers/dir_helpers.php
index 88c819e..67c1631 100644
--- a/src/ObjectHelpers/dir_helpers.php
+++ b/src/ObjectHelpers/dir_helpers.php
@@ -3,6 +3,7 @@
 use EncoreDigitalGroup\StdLib\Objects\Directory;
 
 if (!function_exists('dir_current')) {
+    /** @deprecated */
     function dir_current(): string
     {
         return Directory::current();
@@ -10,7 +11,11 @@ function dir_current(): string
 }
 
 if (!function_exists('dir_hash')) {
-    /** @experimental */
+    /**
+     * @experimental
+     *
+     * @deprecated
+     * */
     function dir_hash(string $dir): string
     {
         return Directory::hash($dir);
@@ -18,7 +23,11 @@ function dir_hash(string $dir): string
 }
 
 if (!function_exists('dir_scan')) {
-    /** @experimental */
+    /**
+     * @experimental
+     *
+     * @deprecated
+     */
     function dir_scan(string $dir): array
     {
         return Directory::scan($dir);
@@ -26,7 +35,11 @@ function dir_scan(string $dir): array
 }
 
 if (!function_exists('dir_scan_recursive')) {
-    /** @experimental */
+    /**
+     * @experimental
+     *
+     * @deprecated
+     */
     function dir_scan_recursive(string $path): array
     {
         return Directory::scanRecursive($path);
diff --git a/src/ObjectHelpers/file_helpers.php b/src/ObjectHelpers/file_helpers.php
index 09abdc0..0e80b70 100644
--- a/src/ObjectHelpers/file_helpers.php
+++ b/src/ObjectHelpers/file_helpers.php
@@ -12,7 +12,11 @@ function file_save_contents(string $path, mixed $data): void
 }
 
 if (!function_exists('file_copy')) {
-    /** @throws FileNotFoundException */
+    /**
+     * @throws FileNotFoundException
+     *
+     * @deprecated
+     */
     function file_copy(string $source, string $destination): void
     {
         File::copy($source, $destination);
@@ -20,7 +24,11 @@ function file_copy(string $source, string $destination): void
 }
 
 if (!function_exists('file_delete')) {
-    /** @throws FileNotFoundException */
+    /**
+     * @throws FileNotFoundException
+     *
+     * @deprecated
+     */
     function file_delete(string $path): void
     {
         File::delete($path);
diff --git a/src/ObjectHelpers/num_helpers.php b/src/ObjectHelpers/num_helpers.php
index 4c4fe5d..fd7e48c 100644
--- a/src/ObjectHelpers/num_helpers.php
+++ b/src/ObjectHelpers/num_helpers.php
@@ -3,6 +3,7 @@
 use EncoreDigitalGroup\StdLib\Objects\Number;
 
 if (!function_exists('num_to_int')) {
+    /** @deprecated */
     function num_to_int(mixed $value): int
     {
         return Number::toInt($value);
diff --git a/src/ObjectHelpers/php_function_helpers.php b/src/ObjectHelpers/php_function_helpers.php
index 10f3223..c2a5e82 100644
--- a/src/ObjectHelpers/php_function_helpers.php
+++ b/src/ObjectHelpers/php_function_helpers.php
@@ -2,8 +2,6 @@
 
 if (!function_exists('get_type')) {
     /**
-     * @noinspection PhpMissingReturnTypeInspection
-     *
      * @phpstan-ignore-next-line
      */
     function get_type(mixed $value): string
diff --git a/src/ObjectHelpers/str_helpers.php b/src/ObjectHelpers/str_helpers.php
index 242e889..b035469 100644
--- a/src/ObjectHelpers/str_helpers.php
+++ b/src/ObjectHelpers/str_helpers.php
@@ -17,7 +17,11 @@ function str_camel(string $string): string
 }
 
 if (!function_exists('str_concat')) {
-    /**@param array<string, string> ...$str */
+    /**
+     * @param  array<string, string>  ...$str
+     *
+     * @deprecated
+     */
     function str_concat(mixed ...$str): string
     {
         return Str::concat($str);
@@ -25,7 +29,11 @@ function str_concat(mixed ...$str): string
 }
 
 if (!function_exists('str_concat_space')) {
-    /**@param array<string, string> ...$str */
+    /**
+     * @param  array<string, string>  ...$str
+     *
+     * @deprecated
+     */
     function str_concat_space(mixed ...$str): string
     {
         return Str::concatSpace($str); //@phpstan-ignore-line
@@ -70,6 +78,7 @@ function str_lower(?string $str = null): ?string
 }
 
 if (!function_exists('str_max_length')) {
+    /** @deprecated use str_limit() instead. */
     function str_max_length(string $str, ?int $length = null): string
     {
         return Str::maxLength($str, $length);
diff --git a/src/ObjectHelpers/val_helpers.php b/src/ObjectHelpers/val_helpers.php
index 8f8c903..558f047 100644
--- a/src/ObjectHelpers/val_helpers.php
+++ b/src/ObjectHelpers/val_helpers.php
@@ -1,6 +1,7 @@
 <?php
 
 if (!function_exists('not_null')) {
+    /** @deprecated */
     function not_null(mixed $value): bool
     {
         return !is_null($value);
@@ -8,7 +9,7 @@ function not_null(mixed $value): bool
 }
 
 if (!function_exists('val_not_null')) {
-    /** @deprecated Use not_null() instead. */
+    /** @deprecated */
     function val_not_null(mixed $value): bool
     {
         return not_null($value);
diff --git a/src/Objects/Arr.php b/src/Objects/Arr.php
index 070cae7..ba4a906 100644
--- a/src/Objects/Arr.php
+++ b/src/Objects/Arr.php
@@ -2,18 +2,20 @@
 
 namespace EncoreDigitalGroup\StdLib\Objects;
 
-use EncoreDigitalGroup\StdLib\Exceptions\ArgumentNullException;
+use EncoreDigitalGroup\StdLib\Exceptions\NullExceptions\ArgumentNullException;
 use Illuminate\Support\Arr as ArraySupport;
 use TypeError;
 
-/**
- * @api
- *
- * @internal
- */
+/** @api */
 class Arr extends ArraySupport
 {
+    /** @deprecated use Arr::toShort() instead. */
     public static function convertToShortSyntax(array|string $code): array|string
+    {
+        return static::toShort($code);
+    }
+
+    public static function toShort(array|string $code): array|string
     {
         // Regular expression to match long array syntax
         $pattern = '/array\s*\(([^()]*(?:(?R)[^()]*)*)\)/m';
@@ -22,13 +24,14 @@ public static function convertToShortSyntax(array|string $code): array|string
         $callback = function ($matches): string {
             // Recursively convert nested arrays
             $innerArray = $matches[1];
-            $convertedInnerArray = self::convertToShortSyntax($innerArray);
+            $convertedInnerArray = self::toShort($innerArray);
 
             // Handle proper formatting of nested arrays
             $convertedInnerArray = preg_replace('/\n\s*/', ' ', $convertedInnerArray);
 
             if (!is_string($convertedInnerArray)) {
-                throw new TypeError(str_concat_space('Expected string, got ', get_type($convertedInnerArray)));
+                $type = get_type($convertedInnerArray);
+                throw new TypeError("Expected string, got {$type}");
             }
 
             return "[\n    " . $convertedInnerArray . "\n]";
diff --git a/src/Objects/Directory.php b/src/Objects/Directory.php
index 286d052..ab31544 100644
--- a/src/Objects/Directory.php
+++ b/src/Objects/Directory.php
@@ -7,11 +7,7 @@
 use RecursiveDirectoryIterator;
 use RecursiveIteratorIterator;
 
-/**
- * @api
- *
- * @internal
- */
+/** @api */
 class Directory
 {
     /**
diff --git a/src/Objects/File.php b/src/Objects/File.php
index 1ec0759..5ad64a3 100644
--- a/src/Objects/File.php
+++ b/src/Objects/File.php
@@ -4,11 +4,7 @@
 
 use EncoreDigitalGroup\StdLib\Exceptions\FileNotFoundException;
 
-/**
- * @api
- *
- * @internal
- */
+/** @api */
 class File
 {
     /**
diff --git a/src/Objects/Json.php b/src/Objects/Json.php
index 29f4069..ace1aa0 100644
--- a/src/Objects/Json.php
+++ b/src/Objects/Json.php
@@ -2,11 +2,7 @@
 
 namespace EncoreDigitalGroup\StdLib\Objects;
 
-/**
- * @api
- *
- * @internal
- */
+/** @api */
 class Json
 {
     /**
diff --git a/src/Objects/Number.php b/src/Objects/Number.php
index 7c13558..2e4cfd0 100644
--- a/src/Objects/Number.php
+++ b/src/Objects/Number.php
@@ -4,11 +4,7 @@
 
 use Illuminate\Support\Number as NumberSupport;
 
-/**
- * @api
- *
- * @internal
- */
+/** @api */
 class Number extends NumberSupport
 {
     /**
diff --git a/src/Objects/Php.php b/src/Objects/Php.php
index dba706b..691ac70 100644
--- a/src/Objects/Php.php
+++ b/src/Objects/Php.php
@@ -2,11 +2,7 @@
 
 namespace EncoreDigitalGroup\StdLib\Objects;
 
-/**
- * @api
- *
- * @internal
- */
+/** @api */
 class Php
 {
     /**
diff --git a/src/Objects/Str.php b/src/Objects/Str.php
index 1963592..b9db137 100644
--- a/src/Objects/Str.php
+++ b/src/Objects/Str.php
@@ -10,11 +10,7 @@
 
 use Illuminate\Support\Str as StringSupport;
 
-/**
- * @api
- *
- * @internal
- */
+/** @api */
 class Str extends StringSupport
 {
     /**@param array<string, string> ...$str */
diff --git a/src/Objects/Url.php b/src/Objects/Url.php
index cf3ebf1..7186539 100644
--- a/src/Objects/Url.php
+++ b/src/Objects/Url.php
@@ -2,11 +2,7 @@
 
 namespace EncoreDigitalGroup\StdLib\Objects;
 
-/**
- * @api
- *
- * @internal
- */
+/** @api */
 class Url
 {
     public static function encode(mixed $data): string
diff --git a/src/Objects/Value.php b/src/Objects/Value.php
index 030c07e..e770a00 100644
--- a/src/Objects/Value.php
+++ b/src/Objects/Value.php
@@ -8,8 +8,6 @@
  * @api
  *
  * @deprecated
- *
- * @internal
  */
 #[Deprecated]
 class Value