Merge branch 'cleanup'

Author: lkrms

.prettyphp

@@ -4,7 +4,6 @@
         "src",
         "tests/3rdparty",
         "tests/fixtures",
-        "tests/legacy",
         "tests/stubs",
         "tests/unit",
         "tests/bootstrap.php",

docs/Benchmarks.md

@@ -6,12 +6,12 @@ Unscientific tests that have informed various decisions.
 
 e.g. when waiting for a `proc_open()` process to terminate:
 
-| Statement        | CPU time  | % of elapsed time |
-| ---------------- | --------- | ----------------- |
-| none             | 9984.34ms | 99.84%            |
-| `usleep(1)`      | 1234.08ms | 12.34%            |
-| `usleep(10)`     | 232.06ms  | 2.32%             |
-| `usleep(100)`    | 94.29ms   | 0.94%             |
-| `usleep(1000)`   | 25.15ms   | 0.25%             |
-| `usleep(10000)`  | 6.00ms    | 0.06%             |
-| `usleep(100000)` | 2.34ms    | 0.02%             |
+| Statement           | CPU time   | % of elapsed time |
+| ------------------- | ---------- | ----------------- |
+| none                | 9984.34ms  | 99.84%            |
+| `usleep(1)`         | 1234.08ms  | 12.34%            |
+| `usleep(10)`        | 232.06ms   | 2.32%             |
+| `usleep(100)`       | 94.29ms    | 0.94%             |
+| `usleep(1000)`      | 25.15ms    | 0.25%             |
+| **`usleep(10000)`** | **6.00ms** | **0.06%**         |
+| `usleep(100000)`    | 2.34ms     | 0.02%             |

docs/Http.md

@@ -0,0 +1,85 @@
+# HTTP
+
+## Form data
+
+There are several methods in [salient/http][] and [salient/curler][] (see the
+[list below][methods]) where data received via `mixed[] $query` and/or
+`mixed[]|object $data` parameters is encoded as HTML form data before it is
+applied to an HTTP message.
+
+`true` and `false` are encoded as `1` and `0` respectively.
+
+Keys other than `list` keys are preserved by default, but form data flags can be
+used to modify this behaviour, e.g. via [Curler::withFormDataFlags()][].
+
+`DateTimeInterface` instances are converted to ISO-8601 strings unless a date
+formatter is given, e.g. via [Curler::withDateFormatter()][].
+
+Before recursion, other objects are processed as follows:
+
+1. `Arrayable`: replaced with return value of [toArray()][]
+2. `JsonSerializable`: serialized with [Json::encode()][] and deserialized with
+   [Json::objectAsArray()][]
+3. `Jsonable`: replaced with return value of [toJson()][] after it is
+   deserialized with [Json::objectAsArray()][]
+4. `Traversable`: passed to `iterator_to_array()` and replaced with its return
+   value
+5. `object` with at least one public property: replaced with an array that maps
+   public property names to values
+6. `Stringable`: cast to `string`
+
+> Internally, [FormDataEncoder][] instances are used to recurse into query and
+> body data.
+>
+> If given, a callback is applied to objects other than `DateTimeInterface`
+> instances. It must return one of the following:
+>
+> - `null` to skip the value
+> - `false` to process the value as if no callback had been given
+> - the value as a `string`
+> - an `array` to recurse into
+> - an `object` to return without encoding
+>
+> If a `DateTimeInterface` is returned, it is converted to a string as above.
+
+### Methods that encode HTTP message data
+
+#### `Http`
+
+- [HttpUtil::mergeQuery()][]
+- [HttpUtil::replaceQuery()][]
+- [Stream::fromData()][]
+
+#### `Curler`
+
+- [Curler::replaceQuery()][]
+- [Curler][] request methods: `head()`, `get()`, `post()`, `put()`, `patch()`,
+  `delete()`
+- Paginated variants: `getP()`, `postP()`, `putP()`, `patchP()`, `deleteP()`
+- Raw variants (`$query` only): `postR()`, `putR()`, `patchR()`, `deleteR()`
+
+[Curler]: https://salient-labs.github.io/toolkit/Salient.Curler.Curler.html
+[Curler::replaceQuery()]:
+  https://salient-labs.github.io/toolkit/Salient.Curler.Curler.html#_replaceQuery
+[Curler::withDateFormatter()]:
+  https://salient-labs.github.io/toolkit/Salient.Curler.Curler.html#_withDateFormatter
+[Curler::withFormDataFlags()]:
+  https://salient-labs.github.io/toolkit/Salient.Curler.Curler.html#_withFormDataFlags
+[FormDataEncoder]: ../src/Toolkit/Http/Internal/FormDataEncoder.php
+[HttpUtil::mergeQuery()]:
+  https://salient-labs.github.io/toolkit/Salient.Http.HttpUtil.html#_mergeQuery
+[HttpUtil::replaceQuery()]:
+  https://salient-labs.github.io/toolkit/Salient.Http.HttpUtil.html#_replaceQuery
+[Json::encode()]:
+  https://salient-labs.github.io/toolkit/Salient.Utility.Json.html#_encode
+[Json::objectAsArray()]:
+  https://salient-labs.github.io/toolkit/Salient.Utility.Json.html#_objectAsArray
+[methods]: #methods-that-encode-http-message-data
+[salient/curler]: https://packagist.org/packages/salient/curler
+[salient/http]: https://packagist.org/packages/salient/http
+[Stream::fromData()]:
+  https://salient-labs.github.io/toolkit/Salient.Http.Message.Stream.html#_fromData
+[toArray()]:
+  https://salient-labs.github.io/toolkit/Salient.Contract.Core.Arrayable.html#_toArray
+[toJson()]:
+  https://salient-labs.github.io/toolkit/Salient.Contract.Core.Jsonable.html#_toJson

phpstan-baseline-7.4.neon

@@ -31,7 +31,7 @@
     'Cache' => ['Cache', true, true, '2025-02-23: code review finalised'],
     'Console' => ['Console', true, true, '2025-03-28: code review finalised except `Formatter` rewrite'],
     'Container' => ['Container', true, true, '2025-03-11: code review finalised except `Container` rewrite sans Dice'],
-    'Http' => ['HTTP', null, null, null],
+    'Http' => ['HTTP', null, true, null],
     'Db' => ['Db', null, null, null],
     'Cli' => ['CLI', null, null, null],
     'Sync' => ['Sync', null, null, null],

phpstan-baseline-8.3.neon

@@ -0,0 +1,50 @@
+<?php declare(strict_types=1);
+
+namespace Salient\Cli;
+
+use Salient\Cli\Exception\CliInvalidArgumentsException;
+use Salient\Utility\AbstractUtility;
+use Salient\Utility\File;
+use Salient\Utility\Json;
+use JsonException;
+
+/**
+ * @api
+ */
+final class CliUtil extends AbstractUtility
+{
+    /**
+     * Get data from a user-supplied JSON file
+     *
+     * If `$filename` is `"-"`, JSON is read from `STDIN`.
+     *
+     * @return mixed[]|object
+     */
+    public static function getJson(string $filename, bool $associative = true)
+    {
+        $json = File::getContents($filename === '-' ? 'php://stdin' : $filename);
+
+        try {
+            $json = $associative
+                ? Json::objectAsArray($json)
+                : Json::parse($json);
+        } catch (JsonException $ex) {
+            $message = $ex->getMessage();
+            throw new CliInvalidArgumentsException(
+                $filename === '-'
+                    ? sprintf('invalid JSON: %s', $message)
+                    : sprintf("invalid JSON in '%s': %s", $filename, $message)
+            );
+        }
+
+        if (!is_array($json) && ($associative || !is_object($json))) {
+            throw new CliInvalidArgumentsException(
+                $filename === '-'
+                    ? 'invalid payload'
+                    : sprintf('invalid payload: %s', $filename)
+            );
+        }
+
+        return $json;
+    }
+}

scripts/check-coverage.php

@@ -0,0 +1,25 @@
+<?php declare(strict_types=1);
+
+namespace Salient\Collection;
+
+/**
+ * @api
+ *
+ * @template TKey of array-key
+ * @template TValue
+ */
+trait ArrayableCollectionTrait
+{
+    /** @use HasItems<TKey,TValue> */
+    use HasItems;
+
+    /**
+     * @inheritDoc
+     */
+    public function toArray(bool $preserveKeys = true): array
+    {
+        return $preserveKeys
+            ? $this->Items
+            : array_values($this->Items);
+    }
+}

src/Toolkit/Cli/CliUtil.php

@@ -11,11 +11,13 @@
  * @template TKey of array-key
  * @template TValue
  *
- * @implements CollectionInterface<TKey,TValue>
+ * @implements CollectionInterface<TKey,TValue,mixed[]>
  * @implements IteratorAggregate<TKey,TValue>
  */
 class Collection implements CollectionInterface, IteratorAggregate
 {
     /** @use CollectionTrait<TKey,TValue,static<TKey|int,TValue>> */
     use CollectionTrait;
+    /** @use RecursiveArrayableCollectionTrait<TKey,TValue> */
+    use RecursiveArrayableCollectionTrait;
 }