Continue utility class cleanup

- Optionally preserve keys in `Arr::unique()`
- Add `Arr::toScalars()`, deprecating `Convert::toScalarArray()`
- Add `Arr::keyOffset()`, deprecating `Convert::arrayKeyToOffset()`
- Remove unused/redundant methods:
  - `Convert::stringsToUnique()`
  - `Convert::stringsToUniqueList()`
  - `Convert::walkRecursive()`
  - `Convert::columnsToUnique()`
  - `Arr::forEach()`

Also:
- Add import statements for built-in classes used in code and DocBlocks

Author: lkrms

.php-cs-fixer.dist.php

@@ -23,6 +23,7 @@
         'no_superfluous_phpdoc_tags' => ['allow_mixed' => true],
         'no_unneeded_import_alias' => true,
         'no_unused_imports' => true,
+        'phpdoc_no_useless_inheritdoc' => true,
         'single_import_per_statement' => true,
         'yoda_style' => ['equal' => false, 'identical' => false],
     ])

src/Console/Target/StreamTarget.php

@@ -7,6 +7,7 @@
 use Lkrms\Utility\Date;
 use Lkrms\Utility\File;
 use DateTime;
+use DateTimeZone;
 use LogicException;
 
 /**
@@ -30,7 +31,7 @@ final class StreamTarget extends ConsoleTarget
     private $Timestamp = '[d M y H:i:s.vO] ';
 
     /**
-     * @var \DateTimeZone|null
+     * @var DateTimeZone|null
      */
     private $Timezone;
 
@@ -66,7 +67,7 @@ final class StreamTarget extends ConsoleTarget
      * @param bool|null $addTimestamp If `null`, timestamps are added if
      * `$stream` is not STDOUT or STDERR.
      * @param string|null $timestamp Default: `[d M y H:i:s.vO] `
-     * @param \DateTimeZone|string|null $timezone Default: as per
+     * @param DateTimeZone|string|null $timezone Default: as per
      * `date_default_timezone_set` or INI setting `date.timezone`
      */
     public function __construct(
@@ -140,7 +141,7 @@ public function reopen(string $path = null)
      * @param bool|null $addTimestamp If `null`, timestamps will be added unless
      * `$path` is STDOUT, STDERR, or a TTY
      * @param string|null $timestamp Default: `[d M y H:i:s.vO] `
-     * @param \DateTimeZone|string|null $timezone Default: as per
+     * @param DateTimeZone|string|null $timezone Default: as per
      * `date_default_timezone_set` or INI setting `date.timezone`
      */
     public static function fromPath(

src/Contract/IFacade.php

@@ -3,6 +3,7 @@
 namespace Lkrms\Contract;
 
 use Lkrms\Concept\Facade;
+use LogicException;
 
 /**
  * Provides a static interface to an instance of an underlying class
@@ -29,8 +30,7 @@ public static function isLoaded(): bool;
      * facade is passed to {@see ReceivesFacade::setFacade()}.
      *
      * @return TClass
-     * @throws \RuntimeException if an underlying instance has already been
-     * loaded.
+     * @throws LogicException if an underlying instance has already been loaded.
      */
     public static function load();
 
@@ -44,11 +44,8 @@ public static function unload(): void;
     /**
      * Get the underlying instance
      *
-     * If an underlying instance has not been loaded, the facade may either:
-     *
-     * 1. call {@see IFacade::load()} and pass the instance it returns to the
-     *    caller (preferred), or
-     * 2. throw a `RuntimeException`.
+     * If an underlying instance has not been loaded, the facade should return
+     * an instance from {@see IFacade::load()}.
      *
      * @return TClass
      */

src/Contract/IProvider.php

@@ -3,6 +3,7 @@
 namespace Lkrms\Contract;
 
 use Lkrms\Exception\MethodNotImplementedException;
+use Stringable;
 
 /**
  * Services objects on behalf of a backend
@@ -58,7 +59,7 @@ public function getContext(?IContainer $container = null): IProviderContext;
      * - values that aren't unique to the connected data source
      * - case-insensitive values (unless normalised first)
      *
-     * @return array<int|float|string|bool|\Stringable|null>
+     * @return array<int|float|string|bool|Stringable|null>
      */
     public function getBackendIdentifier(): array;
 

src/Curler/Curler.php

@@ -34,6 +34,7 @@
 use Lkrms\Utility\Convert;
 use Lkrms\Utility\Env;
 use Lkrms\Utility\Package;
+use CurlHandle;
 use DateTimeInterface;
 use Generator;
 use LogicException;
@@ -385,7 +386,7 @@ final class Curler implements IReadable, IWritable, Buildable
     protected $ObjectAsArray = true;
 
     /**
-     * @var \CurlHandle|resource|null
+     * @var CurlHandle|resource|null
      */
     private $Handle;
 
@@ -417,7 +418,7 @@ final class Curler implements IReadable, IWritable, Buildable
     private static $DefaultUserAgent;
 
     /**
-     * @var \CurlHandle|resource|null
+     * @var CurlHandle|resource|null
      */
     private static $SharedHandle;
 

src/Iterator/Concern/FluentIteratorTrait.php

@@ -15,8 +15,7 @@
 trait FluentIteratorTrait
 {
     /**
-     * @return array<TKey,TValue>|list<TValue>
-     * @phpstan-return ($preserveKeys is true ? array<TKey,TValue> : list<TValue>)
+     * @return ($preserveKeys is true ? array<TKey,TValue> : list<TValue>)
      */
     public function toArray(bool $preserveKeys = true): array
     {

src/Iterator/Contract/FluentIteratorInterface.php

@@ -19,8 +19,7 @@ interface FluentIteratorInterface extends Arrayable, Traversable
     /**
      * Copy the elements of the iterator to an array
      *
-     * @return array<TKey,TValue>|list<TValue>
-     * @phpstan-return ($preserveKeys is true ? array<TKey,TValue> : list<TValue>)
+     * @return ($preserveKeys is true ? array<TKey,TValue> : list<TValue>)
      */
     public function toArray(bool $preserveKeys = true): array;
 

src/Support/IntrospectionClass.php

@@ -14,6 +14,7 @@
 use Lkrms\Support\Catalog\NormaliserFlag;
 use Lkrms\Support\Catalog\RelationshipType;
 use Lkrms\Utility\Reflect;
+use Closure;
 use DateTimeInterface;
 use ReflectionClass;
 use ReflectionMethod;
@@ -268,75 +269,75 @@ class IntrospectionClass
     /**
      * Normalises property names
      *
-     * @var (\Closure(string $name, bool $greedy=, string...$hints): string)|null
+     * @var (Closure(string $name, bool $greedy=, string...$hints): string)|null
      */
     public $Normaliser;
 
     /**
      * Normalises property names with $greedy = false
      *
-     * @var (\Closure(string): string)|null
+     * @var (Closure(string): string)|null
      */
     public $GentleNormaliser;
 
     /**
      * Normalises property names with $hints = $this->NormalisedProperties
      *
-     * @var (\Closure(string): string)|null
+     * @var (Closure(string): string)|null
      */
     public $CarefulNormaliser;
 
     /**
      * Signature => closure
      *
-     * @var array<string,\Closure>
+     * @var array<string,Closure>
      */
     public $CreateFromSignatureClosures = [];
 
     /**
      * Signature => (int) $strict => closure
      *
-     * @var array<string,array<int,\Closure>>
+     * @var array<string,array<int,Closure>>
      */
     public $CreateProviderlessFromSignatureClosures = [];
 
     /**
      * Signature => (int) $strict => closure
      *
-     * @var array<string,array<int,\Closure>>
+     * @var array<string,array<int,Closure>>
      */
     public $CreateProvidableFromSignatureClosures = [];
 
     /**
      * (int) $strict => closure
      *
-     * @var array<int,\Closure>
+     * @var array<int,Closure>
      */
     public $CreateProviderlessFromClosures = [];
 
     /**
      * (int) $strict => closure
      *
-     * @var array<int,\Closure>
+     * @var array<int,Closure>
      */
     public $CreateProvidableFromClosures = [];
 
     /**
      * Normalised property name => action => closure
      *
-     * @var array<string,array<string,\Closure>>
+     * @var array<string,array<string,Closure>>
      */
     public $PropertyActionClosures = [];
 
     /**
-     * @var \Closure|null
+     * @var Closure|null
      */
     public $GetNameClosure;
 
     /**
      * Rules signature => closure
      *
-     * @var array<string,\Closure>
+     * @var array<string,Closure>
      */
     public $SerializeClosures = [];
 
@@ -367,7 +368,7 @@ public function __construct(string $class)
             if ($class->implementsInterface(ReturnsNormaliser::class)) {
                 $this->Normaliser = $class->getMethod('normaliser')->invoke(null);
             } else {
-                $this->Normaliser = \Closure::fromCallable([$className, 'normalise']);
+                $this->Normaliser = Closure::fromCallable([$className, 'normalise']);
             }
             $this->GentleNormaliser = fn(string $name): string => ($this->Normaliser)($name, false);
             $this->CarefulNormaliser = fn(string $name): string => ($this->Normaliser)($name, true, ...$this->NormalisedKeys);

src/Sync/Support/SyncEntityFuzzyResolver.php

@@ -11,6 +11,7 @@
 use Lkrms\Sync\Contract\ISyncEntityResolver;
 use Lkrms\Utility\Compute;
 use Lkrms\Utility\Convert;
+use Closure;
 use LogicException;
 
 /**
@@ -36,7 +37,7 @@ final class SyncEntityFuzzyResolver implements ISyncEntityResolver
     private $EntityProvider;
 
     /**
-     * @var string|\Closure(TEntity): (string|null)
+     * @var string|Closure(TEntity): (string|null)
      */
     private $NameProperty;
 

src/Sync/Support/SyncErrorCollection.php

@@ -7,7 +7,6 @@
 use Lkrms\Console\ConsoleFormatter as Formatter;
 use Lkrms\Sync\Catalog\SyncErrorType as ErrorType;
 use Lkrms\Utility\Arr;
-use Lkrms\Utility\Convert;
 use JsonSerializable;
 
 /**
@@ -64,7 +63,7 @@ public function toString(bool $withMarkup = false): string
         $lines = [];
         $separator = "\n  ";
         foreach ($summary as $error) {
-            $values = Convert::toScalarArray($error['meta']['values']);
+            $values = Arr::toScalars($error['meta']['values']);
 
             if ($withMarkup) {
                 foreach ($values as &$value) {