Core: Review HasMutator methods

lkrms · lkrms · commit 1d5caa55c92d · 2024-09-16T13:27:04.000+10:00
- Rename `withPropertyValue()` -&gt; `with()`
- Rename `withoutProperty()` -&gt; `without()`
- Make methods private for better safety by default
- Remove `clone()`
diff --git a/src/Toolkit/Cli/CliHelpStyle.php b/src/Toolkit/Cli/CliHelpStyle.php
@@ -213,7 +213,7 @@ public function getVisibility(): int
      */
     public function withCollapseSynopsis(bool $value = true)
     {
-        return $this->withPropertyValue('CollapseSynopsis', $value);
+        return $this->with('CollapseSynopsis', $value);
     }
 
     public function prepareHelp(string $text, string $indent = ''): string
diff --git a/src/Toolkit/Collection/ImmutableCollectionTrait.php b/src/Toolkit/Collection/ImmutableCollectionTrait.php
@@ -38,6 +38,6 @@ trait ImmutableCollectionTrait
      */
     protected function maybeClone()
     {
-        return $this->clone();
+        return clone $this;
     }
 }
diff --git a/src/Toolkit/Collection/ImmutableListTrait.php b/src/Toolkit/Collection/ImmutableListTrait.php
@@ -37,6 +37,6 @@ trait ImmutableListTrait
      */
     protected function maybeClone()
     {
-        return $this->clone();
+        return clone $this;
     }
 }
diff --git a/src/Toolkit/Console/ConsoleFormatter.php b/src/Toolkit/Console/ConsoleFormatter.php
@@ -189,15 +189,15 @@ public function withSpinnerState(?array &$state)
      */
     public function withUnescape(bool $value = true)
     {
-        return $this->withPropertyValue('TagFormats', $this->TagFormats->withUnescape($value));
+        return $this->with('TagFormats', $this->TagFormats->withUnescape($value));
     }
 
     /**
      * @inheritDoc
      */
     public function withWrapAfterApply(bool $value = true)
     {
-        return $this->withPropertyValue('TagFormats', $this->TagFormats->withWrapAfterApply($value));
+        return $this->with('TagFormats', $this->TagFormats->withWrapAfterApply($value));
     }
 
     /**
diff --git a/src/Toolkit/Console/Support/ConsoleMessageAttributes.php b/src/Toolkit/Console/Support/ConsoleMessageAttributes.php
@@ -74,22 +74,22 @@ public function __construct(
      */
     public function withIsMsg1(bool $value = true)
     {
-        return $this->withPropertyValue('IsMsg1', $value);
+        return $this->with('IsMsg1', $value);
     }
 
     /**
      * @return static
      */
     public function withIsMsg2(bool $value = true)
     {
-        return $this->withPropertyValue('IsMsg2', $value);
+        return $this->with('IsMsg2', $value);
     }
 
     /**
      * @return static
      */
     public function withIsPrefix(bool $value = true)
     {
-        return $this->withPropertyValue('IsPrefix', $value);
+        return $this->with('IsPrefix', $value);
     }
 }
diff --git a/src/Toolkit/Console/Support/ConsoleTagFormats.php b/src/Toolkit/Console/Support/ConsoleTagFormats.php
@@ -38,15 +38,15 @@ public function __construct(
      */
     public function withUnescape(bool $value = true)
     {
-        return $this->withPropertyValue('Unescape', $value);
+        return $this->with('Unescape', $value);
     }
 
     /**
      * @return static
      */
     public function withWrapAfterApply(bool $value = true)
     {
-        return $this->withPropertyValue('WrapAfterApply', $value);
+        return $this->with('WrapAfterApply', $value);
     }
 
     /**
@@ -73,7 +73,7 @@ public function getWrapAfterApply(): bool
      */
     public function withFormat($tag, Format $format)
     {
-        return $this->withPropertyValue('Formats', Arr::set($this->Formats, $tag, $format));
+        return $this->with('Formats', Arr::set($this->Formats, $tag, $format));
     }
 
     /**
diff --git a/src/Toolkit/Core/Concern/HasMutator.php b/src/Toolkit/Core/Concern/HasMutator.php
@@ -6,27 +6,20 @@
 use ReflectionProperty;
 
 /**
+ * @api
+ *
  * @phpstan-require-implements Immutable
  */
 trait HasMutator
 {
     /**
-     * Clone the object
-     *
-     * @return static
-     */
-    protected function clone()
-    {
-        return clone $this;
-    }
-
-    /**
-     * Apply a value to a clone of the object if the current value differs
+     * Get a copy of the object with a value assigned to a property if its
+     * current value differs, otherwise return the object
      *
      * @param mixed $value
      * @return static
      */
-    protected function withPropertyValue(string $property, $value)
+    private function with(string $property, $value)
     {
         if ((
             isset($this->$property)
@@ -35,18 +28,18 @@ protected function withPropertyValue(string $property, $value)
             return $this;
         }
 
-        $clone = $this->clone();
+        $clone = clone $this;
         $clone->$property = $value;
         return $clone;
     }
 
     /**
-     * Remove a property from a clone of the object if it is currently set or
-     * initialized
+     * Get a copy of the object where a property is unset if it is currently
+     * set, otherwise return the object
      *
      * @return static
      */
-    protected function withoutProperty(string $property)
+    private function without(string $property)
     {
         if (
             !isset($this->$property)
@@ -55,7 +48,7 @@ protected function withoutProperty(string $property)
             return $this;
         }
 
-        $clone = $this->clone();
+        $clone = clone $this;
         unset($clone->$property);
         return $clone;
     }
diff --git a/src/Toolkit/Core/Pipeline.php b/src/Toolkit/Core/Pipeline.php
@@ -34,9 +34,7 @@ final class Pipeline implements
     StreamPipelineInterface
 {
     use HasChainableMethods;
-    use HasMutator {
-        withPropertyValue as with;
-    }
+    use HasMutator;
 
     private bool $HasPayload = false;
     private bool $HasStream;
diff --git a/src/Toolkit/Core/ProviderContext.php b/src/Toolkit/Core/ProviderContext.php
@@ -72,15 +72,15 @@ final public function getProvider(): ProviderInterface
      */
     final public function withContainer(ContainerInterface $container)
     {
-        return $this->withPropertyValue('Container', $container);
+        return $this->with('Container', $container);
     }
 
     /**
      * @inheritDoc
      */
     final public function push($entity)
     {
-        $clone = $this->clone();
+        $clone = clone $this;
         $clone->Stack[] = $entity;
 
         if ($entity instanceof HasId) {
@@ -110,23 +110,23 @@ final public function withValue(string $name, $value)
             }
         }
 
-        return $this->withPropertyValue('Values', $values);
+        return $this->with('Values', $values);
     }
 
     /**
      * @inheritDoc
      */
     final public function withParent(?Treeable $parent)
     {
-        return $this->withPropertyValue('Parent', $parent);
+        return $this->with('Parent', $parent);
     }
 
     /**
      * @inheritDoc
      */
     final public function withConformity($conformity)
     {
-        return $this->withPropertyValue('Conformity', $conformity);
+        return $this->with('Conformity', $conformity);
     }
 
     /**
diff --git a/src/Toolkit/Curler/Curler.php b/src/Toolkit/Curler/Curler.php
@@ -74,6 +74,11 @@
  */
 class Curler implements CurlerInterface, Buildable
 {
+    /** @use HasBuilder<CurlerBuilder> */
+    use HasBuilder;
+    use HasHttpHeaders;
+    use HasMutator;
+
     /**
      * Limit input strings to 2MiB
      *
@@ -88,14 +93,6 @@ class Curler implements CurlerInterface, Buildable
         Method::DELETE => true,
     ];
 
-    /** @use HasBuilder<CurlerBuilder> */
-    use HasBuilder;
-    use HasHttpHeaders;
-    use HasMutator {
-        HasMutator::withPropertyValue as with;
-        HasMutator::withoutProperty as without;
-    }
-
     protected Uri $Uri;
     protected HttpHeadersInterface $Headers;
     protected ?AccessTokenInterface $AccessToken;
diff --git a/src/Toolkit/Http/AbstractHttpMessage.php b/src/Toolkit/Http/AbstractHttpMessage.php
@@ -23,9 +23,7 @@
 abstract class AbstractHttpMessage implements HttpMessageInterface
 {
     use HasHttpHeaders;
-    use HasMutator {
-        HasMutator::withPropertyValue as with;
-    }
+    use HasMutator;
 
     protected string $ProtocolVersion;
     protected HttpHeadersInterface $Headers;
diff --git a/src/Toolkit/Http/HasHttpHeaders.php b/src/Toolkit/Http/HasHttpHeaders.php
@@ -7,9 +7,7 @@
 
 trait HasHttpHeaders
 {
-    use HasMutator {
-        withPropertyValue as with;
-    }
+    use HasMutator;
 
     protected HttpHeadersInterface $Headers;
 
diff --git a/src/Toolkit/Http/HttpHeaders.php b/src/Toolkit/Http/HttpHeaders.php
@@ -36,9 +36,7 @@ class HttpHeaders implements HttpHeadersInterface
     use ReadableCollectionTrait;
     /** @use ImmutableArrayAccessTrait<string,string[]> */
     use ImmutableArrayAccessTrait;
-    use HasMutator {
-        withPropertyValue as with;
-    }
+    use HasMutator;
 
     private const HTTP_HEADER_FIELD_NAME = '/^[-0-9a-z!#$%&\'*+.^_`|~]++$/iD';
     private const HTTP_HEADER_FIELD_VALUE = '/^([\x21-\x7e\x80-\xff]++(?:\h++[\x21-\x7e\x80-\xff]++)*+)?$/D';
@@ -891,7 +889,7 @@ protected function replaceHeaders(?array $headers, array $index)
     {
         $headers ??= $this->getIndexHeaders($index);
 
-        $clone = $this->clone();
+        $clone = clone $this;
         $clone->Headers = $headers;
         $clone->Index = $clone->filterIndex($index);
         $clone->Items = $clone->doGetHeaders();
diff --git a/src/Toolkit/Http/HttpMultipartStreamPart.php b/src/Toolkit/Http/HttpMultipartStreamPart.php
@@ -22,9 +22,7 @@
  */
 class HttpMultipartStreamPart implements HttpMultipartStreamPartInterface
 {
-    use HasMutator {
-        withPropertyValue as with;
-    }
+    use HasMutator;
 
     protected ?string $Name;
     protected ?string $Filename;
diff --git a/src/Toolkit/Http/HttpRequest.php b/src/Toolkit/Http/HttpRequest.php
@@ -11,6 +11,7 @@
 use Salient\Contract\Http\HttpHeader;
 use Salient\Contract\Http\HttpRequestInterface;
 use Salient\Contract\Http\HttpRequestMethod as Method;
+use Salient\Core\Concern\HasMutator;
 use Salient\Utility\Exception\InvalidArgumentTypeException;
 use Salient\Utility\Regex;
 use InvalidArgumentException;
@@ -23,6 +24,8 @@
  */
 class HttpRequest extends AbstractHttpMessage implements HttpRequestInterface
 {
+    use HasMutator;
+
     private const TOKEN = '/^[-0-9a-z!#$%&\'*+.^_`|~]++$/iD';
 
     protected string $Method;
diff --git a/src/Toolkit/Http/HttpResponse.php b/src/Toolkit/Http/HttpResponse.php
@@ -8,6 +8,7 @@
 use Salient\Contract\Core\Arrayable;
 use Salient\Contract\Http\HttpHeader;
 use Salient\Contract\Http\HttpResponseInterface;
+use Salient\Core\Concern\HasMutator;
 use Salient\Utility\Exception\InvalidArgumentTypeException;
 use Salient\Utility\Arr;
 use Salient\Utility\Str;
@@ -20,6 +21,8 @@
  */
 class HttpResponse extends AbstractHttpMessage implements HttpResponseInterface
 {
+    use HasMutator;
+
     protected const STATUS_CODE = [
         100 => 'Continue',
         101 => 'Switching Protocols',
diff --git a/src/Toolkit/Http/HttpServer.php b/src/Toolkit/Http/HttpServer.php
@@ -22,9 +22,7 @@
  */
 class HttpServer implements Immutable
 {
-    use HasMutator {
-        withPropertyValue as with;
-    }
+    use HasMutator;
 
     protected string $Host;
     protected int $Port;
diff --git a/src/Toolkit/Http/HttpServerRequest.php b/src/Toolkit/Http/HttpServerRequest.php
@@ -8,6 +8,7 @@
 use Psr\Http\Message\UriInterface as PsrUriInterface;
 use Salient\Contract\Core\Arrayable;
 use Salient\Contract\Http\HttpServerRequestInterface;
+use Salient\Core\Concern\HasMutator;
 use Salient\Utility\Exception\InvalidArgumentTypeException;
 use Stringable;
 
@@ -18,6 +19,8 @@
  */
 class HttpServerRequest extends HttpRequest implements HttpServerRequestInterface
 {
+    use HasMutator;
+
     /** @var mixed[] */
     protected array $ServerParams;
     /** @var mixed[] */
diff --git a/src/Toolkit/Http/Uri.php b/src/Toolkit/Http/Uri.php
@@ -19,9 +19,7 @@
  */
 class Uri implements UriInterface
 {
-    use HasMutator {
-        withPropertyValue as with;
-    }
+    use HasMutator;
 
     /**
      * Replace empty HTTP and HTTPS paths with "/"
diff --git a/src/Toolkit/PHPDoc/Tag/AbstractTag.php b/src/Toolkit/PHPDoc/Tag/AbstractTag.php
@@ -15,10 +15,7 @@
  */
 abstract class AbstractTag implements Immutable
 {
-    use HasMutator {
-        withPropertyValue as with;
-        withoutProperty as without;
-    }
+    use HasMutator;
 
     protected string $Tag;
     protected string $Name;
diff --git a/src/Toolkit/PHPDoc/Tag/TemplateTag.php b/src/Toolkit/PHPDoc/Tag/TemplateTag.php
@@ -2,13 +2,16 @@
 
 namespace Salient\PHPDoc\Tag;
 
+use Salient\Core\Concern\HasMutator;
 use Stringable;
 
 /**
  * A "@template" tag
  */
 class TemplateTag extends AbstractTag implements Stringable
 {
+    use HasMutator;
+
     /** @var "covariant"|"contravariant"|null */
     protected ?string $Variance;
 
diff --git a/src/Toolkit/PHPDoc/Tag/VarTag.php b/src/Toolkit/PHPDoc/Tag/VarTag.php
diff --git a/src/Toolkit/Sync/AbstractSyncDefinition.php b/src/Toolkit/Sync/AbstractSyncDefinition.php
diff --git a/src/Toolkit/Sync/Http/HttpSyncDefinition.php b/src/Toolkit/Sync/Http/HttpSyncDefinition.php
diff --git a/src/Toolkit/Sync/Support/SyncContext.php b/src/Toolkit/Sync/Support/SyncContext.php
diff --git a/src/Toolkit/Sync/SyncError.php b/src/Toolkit/Sync/SyncError.php
diff --git a/src/Toolkit/Sync/SyncSerializeRules.php b/src/Toolkit/Sync/SyncSerializeRules.php
diff --git a/tests/fixtures/Toolkit/Core/Concern/HasMutator/MyImmutableClass.php b/tests/fixtures/Toolkit/Core/Concern/HasMutator/MyImmutableClass.php
diff --git a/tests/unit/Toolkit/Core/Concern/HasMutatorTest.php b/tests/unit/Toolkit/Core/Concern/HasMutatorTest.php

Original file line number	Diff line number	Diff line change
`@@ -213,7 +213,7 @@ public function getVisibility(): int`
`213`	`213`	`*/`
`214`	`214`	`public function withCollapseSynopsis(bool $value = true)`
`215`	`215`	`{`
`216`		`- return $this->withPropertyValue('CollapseSynopsis', $value);`
	`216`	`+ return $this->with('CollapseSynopsis', $value);`
`217`	`217`	`}`
`218`	`218`
`219`	`219`	`public function prepareHelp(string $text, string $indent = ''): string`
Original file line number	Diff line number	Diff line change
`@@ -38,6 +38,6 @@ trait ImmutableCollectionTrait`
`38`	`38`	`*/`
`39`	`39`	`protected function maybeClone()`
`40`	`40`	`{`
`41`		`- return $this->clone();`
	`41`	`+ return clone $this;`
`42`	`42`	`}`
`43`	`43`	`}`
Original file line number	Diff line number	Diff line change
`@@ -37,6 +37,6 @@ trait ImmutableListTrait`
`37`	`37`	`*/`
`38`	`38`	`protected function maybeClone()`
`39`	`39`	`{`
`40`		`- return $this->clone();`
	`40`	`+ return clone $this;`
`41`	`41`	`}`
`42`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -189,15 +189,15 @@ public function withSpinnerState(?array &$state)`
`189`	`189`	`*/`
`190`	`190`	`public function withUnescape(bool $value = true)`
`191`	`191`	`{`
`192`		`- return $this->withPropertyValue('TagFormats', $this->TagFormats->withUnescape($value));`
	`192`	`+ return $this->with('TagFormats', $this->TagFormats->withUnescape($value));`
`193`	`193`	`}`
`194`	`194`
`195`	`195`	`/**`
`196`	`196`	`* @inheritDoc`
`197`	`197`	`*/`
`198`	`198`	`public function withWrapAfterApply(bool $value = true)`
`199`	`199`	`{`
`200`		`- return $this->withPropertyValue('TagFormats', $this->TagFormats->withWrapAfterApply($value));`
	`200`	`+ return $this->with('TagFormats', $this->TagFormats->withWrapAfterApply($value));`
`201`	`201`	`}`
`202`	`202`
`203`	`203`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -74,22 +74,22 @@ public function __construct(`
`74`	`74`	`*/`
`75`	`75`	`public function withIsMsg1(bool $value = true)`
`76`	`76`	`{`
`77`		`- return $this->withPropertyValue('IsMsg1', $value);`
	`77`	`+ return $this->with('IsMsg1', $value);`
`78`	`78`	`}`
`79`	`79`
`80`	`80`	`/**`
`81`	`81`	`* @return static`
`82`	`82`	`*/`
`83`	`83`	`public function withIsMsg2(bool $value = true)`
`84`	`84`	`{`
`85`		`- return $this->withPropertyValue('IsMsg2', $value);`
	`85`	`+ return $this->with('IsMsg2', $value);`
`86`	`86`	`}`
`87`	`87`
`88`	`88`	`/**`
`89`	`89`	`* @return static`
`90`	`90`	`*/`
`91`	`91`	`public function withIsPrefix(bool $value = true)`
`92`	`92`	`{`
`93`		`- return $this->withPropertyValue('IsPrefix', $value);`
	`93`	`+ return $this->with('IsPrefix', $value);`
`94`	`94`	`}`
`95`	`95`	`}`
Original file line number	Diff line number	Diff line change
`@@ -38,15 +38,15 @@ public function __construct(`
`38`	`38`	`*/`
`39`	`39`	`public function withUnescape(bool $value = true)`
`40`	`40`	`{`
`41`		`- return $this->withPropertyValue('Unescape', $value);`
	`41`	`+ return $this->with('Unescape', $value);`
`42`	`42`	`}`
`43`	`43`
`44`	`44`	`/**`
`45`	`45`	`* @return static`
`46`	`46`	`*/`
`47`	`47`	`public function withWrapAfterApply(bool $value = true)`
`48`	`48`	`{`
`49`		`- return $this->withPropertyValue('WrapAfterApply', $value);`
	`49`	`+ return $this->with('WrapAfterApply', $value);`
`50`	`50`	`}`
`51`	`51`
`52`	`52`	`/**`
`@@ -73,7 +73,7 @@ public function getWrapAfterApply(): bool`
`73`	`73`	`*/`
`74`	`74`	`public function withFormat($tag, Format $format)`
`75`	`75`	`{`
`76`		`- return $this->withPropertyValue('Formats', Arr::set($this->Formats, $tag, $format));`
	`76`	`+ return $this->with('Formats', Arr::set($this->Formats, $tag, $format));`
`77`	`77`	`}`
`78`	`78`
`79`	`79`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -72,15 +72,15 @@ final public function getProvider(): ProviderInterface`
`72`	`72`	`*/`
`73`	`73`	`final public function withContainer(ContainerInterface $container)`
`74`	`74`	`{`
`75`		`- return $this->withPropertyValue('Container', $container);`
	`75`	`+ return $this->with('Container', $container);`
`76`	`76`	`}`
`77`	`77`
`78`	`78`	`/**`
`79`	`79`	`* @inheritDoc`
`80`	`80`	`*/`
`81`	`81`	`final public function push($entity)`
`82`	`82`	`{`
`83`		`- $clone = $this->clone();`
	`83`	`+ $clone = clone $this;`
`84`	`84`	`$clone->Stack[] = $entity;`
`85`	`85`
`86`	`86`	`if ($entity instanceof HasId) {`
`@@ -110,23 +110,23 @@ final public function withValue(string $name, $value)`
`110`	`110`	`}`
`111`	`111`	`}`
`112`	`112`
`113`		`- return $this->withPropertyValue('Values', $values);`
	`113`	`+ return $this->with('Values', $values);`
`114`	`114`	`}`
`115`	`115`
`116`	`116`	`/**`
`117`	`117`	`* @inheritDoc`
`118`	`118`	`*/`
`119`	`119`	`final public function withParent(?Treeable $parent)`
`120`	`120`	`{`
`121`		`- return $this->withPropertyValue('Parent', $parent);`
	`121`	`+ return $this->with('Parent', $parent);`
`122`	`122`	`}`
`123`	`123`
`124`	`124`	`/**`
`125`	`125`	`* @inheritDoc`
`126`	`126`	`*/`
`127`	`127`	`final public function withConformity($conformity)`
`128`	`128`	`{`
`129`		`- return $this->withPropertyValue('Conformity', $conformity);`
	`129`	`+ return $this->with('Conformity', $conformity);`
`130`	`130`	`}`
`131`	`131`
`132`	`132`	`/**`