Add Deprecations (#27)

onairmarc · web-flow · commit 5adc6c94f3b6 · 2024-11-06T09:21:17.000-06:00
Co-authored-by: onairmarc &lt;onairmarc@users.noreply.github.com&gt;
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -3,30 +3,43 @@
 use EncoreDigitalGroup\StdLib\Objects\Directory;
 
 if (!function_exists('dir_current')) {
+    /** @deprecated */
     function dir_current(): string
     {
         return Directory::current();
     }
 }
 
 if (!function_exists('dir_hash')) {
-    /** @experimental */
+    /**
+     * @experimental
+     *
+     * @deprecated
+     * */
     function dir_hash(string $dir): string
     {
         return Directory::hash($dir);
     }
 }
 
 if (!function_exists('dir_scan')) {
-    /** @experimental */
+    /**
+     * @experimental
+     *
+     * @deprecated
+     */
     function dir_scan(string $dir): array
     {
         return Directory::scan($dir);
     }
 }
 
 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
@@ -12,15 +12,23 @@ 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);
     }
 }
 
 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
@@ -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
@@ -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
@@ -17,15 +17,23 @@ 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);
     }
 }
 
 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
@@ -1,14 +1,15 @@
 <?php
 
 if (!function_exists('not_null')) {
+    /** @deprecated */
     function not_null(mixed $value): bool
     {
         return !is_null($value);
     }
 }
 
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -8,8 +8,6 @@
  * @api
  *
  * @deprecated
- *
- * @internal
  */
 #[Deprecated]
 class Value

Original file line number	Diff line number	Diff line change
`@@ -10,9 +10,9 @@ class DirectoryNotFoundException extends BaseException`
`10`	`10`	`public function __construct(?string $path = null)`
`11`	`11`	`{`
`12`	`12`	`if (is_null($path)) {`
`13`		`- $msg = str_concat_space('Unable to locate directory on line', $this->line, 'in', $this->file);`
	`13`	`+ $msg = "Unable to locate directory on line {$this->line} in {$this->file}";`
`14`	`14`	`} else {`
`15`		`- $msg = str_concat_space('Unable to locate directory', $path, 'on line', $this->line, 'in', $this->file);`
	`15`	`+ $msg = "Unable to locate directory {$path} on line {$this->line} in {$this->file}";`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`parent::__construct($msg, ExitCode::RESOURCE_UNAVAILABLE, $this->getPrevious());`
Original file line number	Diff line number	Diff line change
`@@ -10,9 +10,9 @@ class FileNotFoundException extends BaseException`
`10`	`10`	`public function __construct(?string $path = null)`
`11`	`11`	`{`
`12`	`12`	`if (is_null($path)) {`
`13`		`- $msg = str_concat_space('Unable to locate file on line', $this->line, 'in', $this->file);`
	`13`	`+ $msg = "Unable to locate file on line {$this->line} in {$this->file}";`
`14`	`14`	`} else {`
`15`		`- $msg = str_concat_space('Unable to locate file', $path, 'on line', $this->line, 'in', $this->file);`
	`15`	`+ $msg = "Unable to locate file {$path} on line {$this->line} in {$this->file}";`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`parent::__construct($msg, ExitCode::RESOURCE_UNAVAILABLE, $this->getPrevious());`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ public function __construct(bool $expected = true)`
`16`	`16`	`$actual = 'true';`
`17`	`17`	`}`
`18`	`18`
`19`		`- $msg = str_concat_space('Improper boolean returned. Expected', $expect, 'but got', $actual);`
	`19`	`+ $msg = "Improper boolean returned. Expected {$expect} but got {$actual}";`
`20`	`20`
`21`	`21`	`parent::__construct($msg, ExitCode::DATA_ERROR, $this->getPrevious());`
`22`	`22`	`}`
Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@ class NotImplementedException extends BaseException`
`8`	`8`	`{`
`9`	`9`	`public function __construct()`
`10`	`10`	`{`
`11`		`- $msg = str_concat_space('Method is not implemented on line', $this->line, 'in', $this->file);`
	`11`	`+ $msg = "Method is not implemented on line {$this->line} in {$this->file}";`
`12`	`12`
`13`	`13`	`parent::__construct($msg, ExitCode::RESOURCE_UNAVAILABLE, $this->getPrevious());`
`14`	`14`	`}`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,8 @@`
`6`	`6`	`if (!function_exists('arr_to_short_syntax')) {`
`7`	`7`	`/**`
`8`	`8`	`* @throws ArgumentNullException`
	`9`	`+ *`
	`10`	`+ * @deprecated No Replacement`
`9`	`11`	`*/`
`10`	`12`	`function arr_to_short_syntax(array\|string $value): array\|string`
`11`	`13`	`{`
Original file line number	Diff line number	Diff line change
`@@ -3,30 +3,43 @@`
`3`	`3`	`use EncoreDigitalGroup\StdLib\Objects\Directory;`
`4`	`4`
`5`	`5`	`if (!function_exists('dir_current')) {`
	`6`	`+ /** @deprecated */`
`6`	`7`	`function dir_current(): string`
`7`	`8`	`{`
`8`	`9`	`return Directory::current();`
`9`	`10`	`}`
`10`	`11`	`}`
`11`	`12`
`12`	`13`	`if (!function_exists('dir_hash')) {`
`13`		`- /** @experimental */`
	`14`	`+ /**`
	`15`	`+ * @experimental`
	`16`	`+ *`
	`17`	`+ * @deprecated`
	`18`	`+ * */`
`14`	`19`	`function dir_hash(string $dir): string`
`15`	`20`	`{`
`16`	`21`	`return Directory::hash($dir);`
`17`	`22`	`}`
`18`	`23`	`}`
`19`	`24`
`20`	`25`	`if (!function_exists('dir_scan')) {`
`21`		`- /** @experimental */`
	`26`	`+ /**`
	`27`	`+ * @experimental`
	`28`	`+ *`
	`29`	`+ * @deprecated`
	`30`	`+ */`
`22`	`31`	`function dir_scan(string $dir): array`
`23`	`32`	`{`
`24`	`33`	`return Directory::scan($dir);`
`25`	`34`	`}`
`26`	`35`	`}`
`27`	`36`
`28`	`37`	`if (!function_exists('dir_scan_recursive')) {`
`29`		`- /** @experimental */`
	`38`	`+ /**`
	`39`	`+ * @experimental`
	`40`	`+ *`
	`41`	`+ * @deprecated`
	`42`	`+ */`
`30`	`43`	`function dir_scan_recursive(string $path): array`
`31`	`44`	`{`
`32`	`45`	`return Directory::scanRecursive($path);`
Original file line number	Diff line number	Diff line change
`@@ -12,15 +12,23 @@ function file_save_contents(string $path, mixed $data): void`
`12`	`12`	`}`
`13`	`13`
`14`	`14`	`if (!function_exists('file_copy')) {`
`15`		`- /** @throws FileNotFoundException */`
	`15`	`+ /**`
	`16`	`+ * @throws FileNotFoundException`
	`17`	`+ *`
	`18`	`+ * @deprecated`
	`19`	`+ */`
`16`	`20`	`function file_copy(string $source, string $destination): void`
`17`	`21`	`{`
`18`	`22`	`File::copy($source, $destination);`
`19`	`23`	`}`
`20`	`24`	`}`
`21`	`25`
`22`	`26`	`if (!function_exists('file_delete')) {`
`23`		`- /** @throws FileNotFoundException */`
	`27`	`+ /**`
	`28`	`+ * @throws FileNotFoundException`
	`29`	`+ *`
	`30`	`+ * @deprecated`
	`31`	`+ */`
`24`	`32`	`function file_delete(string $path): void`
`25`	`33`	`{`
`26`	`34`	`File::delete($path);`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@`
`3`	`3`	`use EncoreDigitalGroup\StdLib\Objects\Number;`
`4`	`4`
`5`	`5`	`if (!function_exists('num_to_int')) {`
	`6`	`+ /** @deprecated */`
`6`	`7`	`function num_to_int(mixed $value): int`
`7`	`8`	`{`
`8`	`9`	`return Number::toInt($value);`