Merge branch 'cleanup'

Author: lkrms

CHANGELOG.md

@@ -12,6 +12,94 @@ The format is based on [Keep a Changelog][], and this project adheres to
 [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
 
+## [v0.21.18] - 2023-12-29
+
+### Added
+
+- Add `File::guessIndentation()`
+- Add `File::isSeekable()`
+- Add `Str::toStream()`
+- Add `Sys::getUserId()`
+
+### Changed
+
+- Refactor `File::realpath()`
+  - Remove file descriptor handling
+  - **Throw an exception if the file doesn't exist**
+  - Resolve Phar URIs when a Phar is not running
+- Refactor `File::relativeToParent()`
+  - Require `$parentDir`
+  - Add `$fallback` (`null` by default) and return it if `$filename` does not belong to `$parentDir`
+- Refactor `File::writeCsv()`
+  - **Make `$resource` a required parameter**
+  - **Swap `$data` and `$resource` parameters**
+  - **Change return type to `void`**
+  - Remove UTF-16LE filters applied to streams provided by the caller
+  - Apply `Arr::toScalars()` to each row of data
+- Refactor `Sys::getProgramBasename()`
+  - Only remove the first matched `$suffix`
+- Rename `Stream::fromContents()` to `Stream::fromString()`
+- Rename environment variable `CONSOLE_OUTPUT` to `CONSOLE_TARGET`
+- Add optional `$null` parameter to `Arr::toScalars()`
+- Adopt `Str::lower()` and `Str::upper()` for case comparison
+- Make `File::fputcsv()` public
+
+### Fixed
+
+- Fix `File::realpath()` issue where `//../` segments in Phar URIs are not resolved correctly
+- Fix `ErrorHandler::silencePath()` issue where files and directories that start with the same name as a silenced file are inadvertently silenced
+
+## [v0.21.17] - 2023-12-25
+
+### Added
+
+- Add `Arr::flatten()`
+- Add `HttpFactory` (implements PSR-17 factory interfaces)
+
+### Changed
+
+- **Return `null` instead of `false` when `FluentIteratorInterface::nextWithValue()` finds no matching value**
+- Pass value AND key to `FluentIteratorInterface::forEach()` callback
+- In `HttpRequest`, preserve the original case of the HTTP method
+- In `HttpHeaders`, throw an exception when a header with no values is given
+- In `Uri`, do not resolve dot segments if the URI is a relative reference
+- In `Arr::toScalars()`, preserve `null` values
+- In `Arr::trim()`, remove keys from the array if removing empty values
+- Optionally preserve keys in `Arr::unique()`
+- Rename `Arr::sameValues()` to `same()`
+- Accept `iterable` where possible in `Arr` methods
+- Add `Arr::keyOffset()`, deprecating `Convert::arrayKeyToOffset()`
+- Add `Arr::toMap()`, deprecating `Convert::listToMap()`
+- Add `Arr::toScalars()`, deprecating `Convert::toScalarArray()`
+- Add `Get::array()`, deprecating `Convert::iterableToArray()`
+
+### Deprecated
+
+- Deprecate (see above):
+  - `Convert::arrayKeyToOffset()`
+  - `Convert::listToMap()`
+  - `Convert::toScalarArray()`
+  - `Convert::iterableToArray()`
+
+### Removed
+
+- Remove unused/redundant methods:
+  - `Arr::forEach()`
+  - `Convert::columnsToUnique()`
+  - `Convert::iterableToItem()`
+  - `Convert::iterableToIterator()`
+  - `Convert::scalarToString()`
+  - `Convert::stringsToUnique()`
+  - `Convert::stringsToUniqueList()`
+  - `Convert::valueAtKey()`
+  - `Convert::walkRecursive()`
+  - `FluentIteratorInterface::forEachWhile()`
+  - `FluentIteratorTrait::forEachWhile()`
+
+### Fixed
+
+- Fix bug in `Arr::sortDesc()` where keys are not preserved correctly
+
 ## [v0.21.16] - 2023-12-21
 
 ### Fixed
@@ -1159,6 +1247,8 @@ The format is based on [Keep a Changelog][], and this project adheres to
 
 - Allow `CliOption` value names to contain arbitrary characters
 
+[v0.21.18]: https://github.com/lkrms/php-util/compare/v0.21.17...v0.21.18
+[v0.21.17]: https://github.com/lkrms/php-util/compare/v0.21.16...v0.21.17
 [v0.21.16]: https://github.com/lkrms/php-util/compare/v0.21.15...v0.21.16
 [v0.21.15]: https://github.com/lkrms/php-util/compare/v0.21.14...v0.21.15
 [v0.21.14]: https://github.com/lkrms/php-util/compare/v0.21.13...v0.21.14

src/Container/Application.php

@@ -428,7 +428,7 @@ final public function startCache()
 
         if (Cache::isLoaded()) {
             $file = Cache::getFilename();
-            if (File::is($cacheDb, $file)) {
+            if (File::same($cacheDb, $file)) {
                 return $this;
             }
             throw new LogicException(sprintf('Cache store already started: %s', $file));
@@ -455,7 +455,7 @@ final public function resumeCache()
     final public function stopCache()
     {
         if (!Cache::isLoaded() ||
-                !File::is($this->getCacheDb(false), Cache::getFilename())) {
+                !File::same($this->getCacheDb(false), Cache::getFilename())) {
             return $this;
         }
         Cache::close();
@@ -496,7 +496,7 @@ final public function startSync(?string $command = null, ?array $arguments = nul
 
         if (Sync::isLoaded()) {
             $file = Sync::getFilename();
-            if (File::is($syncDb, $file)) {
+            if (File::same($syncDb, $file)) {
                 return $this;
             }
             throw new LogicException(sprintf('Entity store already started: %s', $file));
@@ -536,7 +536,7 @@ final public function syncNamespace(string $prefix, string $uri, string $namespa
     final public function stopSync()
     {
         if (!Sync::isLoaded() ||
-                !File::is($this->getSyncDb(false), Sync::getFilename())) {
+                !File::same($this->getSyncDb(false), Sync::getFilename())) {
             return $this;
         }
         Sync::close();

src/Utility/File.php

@@ -126,18 +126,30 @@ public static function tell($stream, $uri = null): int
     }
 
     /**
-     * Get the file status of a stream
+     * Get the status of a file or stream
      *
+     * @see stat()
      * @see fstat()
-     * @param resource $stream
+     * @param Stringable|string|resource $resource
      * @param Stringable|string|null $uri
      * @return int[]
      * @throws FilesystemErrorException on failure.
      */
-    public static function stat($stream, $uri = null): array
+    public static function stat($resource, $uri = null): array
     {
-        $result = @fstat($stream);
-        return self::throwOnFailure($result, 'Error getting file status of stream: %s', $uri, $stream);
+        if (is_resource($resource)) {
+            self::assertResourceIsStream($resource);
+            $result = @fstat($resource);
+            return self::throwOnFailure($result, 'Error getting status of stream: %s', $uri, $resource);
+        }
+
+        if (!Test::isStringable($resource)) {
+            throw new InvalidArgumentTypeException(1, 'resource', 'Stringable|string|resource', $resource);
+        }
+
+        $resource = (string) $resource;
+        $result = @stat($resource);
+        return self::throwOnFailure($result, 'Error getting file status: %s', $resource);
     }
 
     /**
@@ -181,8 +193,7 @@ public static function closePipe($pipe, ?string $command = null): int
     }
 
     /**
-     * Get the entire contents of a file or the remaining contents of an open
-     * stream
+     * Get the entire contents of a file or the remaining contents of a stream
      *
      * @see file_get_contents()
      * @see stream_get_contents()
@@ -233,7 +244,7 @@ public static function find(): RecursiveFilesystemIterator
     }
 
     /**
-     * Get the end-of-line sequence used in a file
+     * Get the end-of-line sequence used in a file or stream
      *
      * Recognised line endings are LF (`"\n"`), CRLF (`"\r\n"`) and CR (`"\r"`).
      *
@@ -247,17 +258,7 @@ public static function find(): RecursiveFilesystemIterator
      */
     public static function getEol($resource, $uri = null): ?string
     {
-        $close = false;
-        if (is_resource($resource)) {
-            self::assertResourceIsStream($resource);
-            $handle = $resource;
-        } elseif (Test::isStringable($resource)) {
-            $uri = (string) $resource;
-            $handle = self::open($uri, 'r');
-            $close = true;
-        } else {
-            throw new InvalidArgumentTypeException(1, 'resource', 'Stringable|string|resource', $resource);
-        }
+        $handle = self::getStream($resource, 'r', $close, $uri);
 
         $line = fgets($handle);
 
@@ -283,7 +284,7 @@ public static function getEol($resource, $uri = null): ?string
     }
 
     /**
-     * Guess the indentation used in a file
+     * Guess the indentation used in a file or stream
      *
      * Derived from VS Code's `indentationGuesser`.
      *
@@ -298,17 +299,7 @@ public static function guessIndentation(
         bool $alwaysGuessTabSize = false,
         $uri = null
     ): Indentation {
-        $close = false;
-        if (is_resource($resource)) {
-            self::assertResourceIsStream($resource);
-            $handle = $resource;
-        } elseif (Test::isStringable($resource)) {
-            $uri = (string) $resource;
-            $handle = self::open($uri, 'r');
-            $close = true;
-        } else {
-            throw new InvalidArgumentTypeException(1, 'resource', 'Stringable|string|resource', $resource);
-        }
+        $handle = self::getStream($resource, 'r', $close, $uri);
 
         $lines = 0;
         $linesWithTabs = 0;
@@ -401,8 +392,7 @@ public static function guessIndentation(
                     $lineSpaces - 1 < strlen($_prevLine) &&
                     $_line[$lineSpaces] !== ' ' &&
                     $_prevLine[$lineSpaces - 1] === ' ' &&
-                    $_prevLine[-1] === ',' &&
-                    !(
+                    $_prevLine[-1] === ',' && !(
                         $default &&
                         $default->InsertSpaces &&
                         $default->TabSize === $diffSpaces
@@ -450,14 +440,16 @@ public static function guessIndentation(
     /**
      * True if two paths refer to the same filesystem entry
      */
-    public static function is(string $filename1, string $filename2): bool
+    public static function same(string $filename1, string $filename2): bool
     {
         if (!file_exists($filename1) || !file_exists($filename2)) {
             return false;
         }
-        $inode = fileinode($filename1);
-        return $inode !== false &&
-            fileinode($filename2) === $inode;
+        $stat1 = self::stat($filename1);
+        $stat2 = self::stat($filename2);
+        return
+            $stat1['dev'] === $stat2['dev'] &&
+            $stat1['ino'] === $stat2['ino'];
     }
 
     /**
@@ -814,17 +806,7 @@ public static function writeCsv(
         bool $bom = true,
         $uri = null
     ): void {
-        $close = false;
-        if (is_resource($resource)) {
-            self::assertResourceIsStream($resource);
-            $handle = $resource;
-        } elseif (Test::isStringable($resource)) {
-            $uri = (string) $resource;
-            $handle = self::open($uri, 'wb');
-            $close = true;
-        } else {
-            throw new InvalidArgumentTypeException(1, 'resource', 'Stringable|string|resource', $resource);
-        }
+        $handle = self::getStream($resource, 'wb', $close, $uri);
 
         if ($utf16le) {
             if (!extension_loaded('iconv')) {
@@ -900,6 +882,28 @@ public static function fputcsv(
         );
     }
 
+    /**
+     * @param Stringable|string|resource $resource
+     * @param Stringable|string|null $uri
+     * @param-out bool $close
+     * @param-out Stringable|string|null $uri
+     * @return resource
+     */
+    private static function getStream($resource, string $mode, ?bool &$close, &$uri)
+    {
+        $close = false;
+        if (is_resource($resource)) {
+            self::assertResourceIsStream($resource);
+            return $resource;
+        }
+        if (Test::isStringable($resource)) {
+            $uri = (string) $resource;
+            $close = true;
+            return self::open($uri, $mode);
+        }
+        throw new InvalidArgumentTypeException(1, 'resource', 'Stringable|string|resource', $resource);
+    }
+
     /**
      * @param resource $resource
      */

src/Utility/Test.php

@@ -100,12 +100,12 @@ public static function isAbsolutePath(string $path): bool
     }
 
     /**
-     * @deprecated Use {@see File::is()} instead
+     * @deprecated Use {@see File::same()} instead
      * @codeCoverageIgnore
      */
     public static function areSameFile(string $path1, string $path2): bool
     {
-        return File::is($path1, $path2);
+        return File::same($path1, $path2);
     }
 
     /**

tests/fixtures/Utility/File/broken_symlink

@@ -0,0 +1 @@
+does_not_exist

tests/fixtures/Utility/File/file_symlink

@@ -0,0 +1 @@
+dir/file

tests/legacy/file

@@ -31,7 +31,7 @@ print_r([
     'STDOUT' => File::getStreamUri(\STDOUT),
     'STDERR' => File::getStreamUri(\STDERR),
     'areSame' => array_map(
-        function ($f) { return array_merge($f, [File::is($f[0], $f[1])]); },
+        function ($f) { return array_merge($f, [File::same($f[0], $f[1])]); },
         $compare
     )
 ]);