Adding missing Modifier methods

Author: nyamsprod

components/CHANGELOG.md

@@ -9,14 +9,14 @@ All Notable changes to `League\Uri\Components` will be documented in this file
 - `Domain::first` returns the first domain label
 - `Domain::last`  returns the last domain label
 - `Domain::contains` tells wether the label is present in the domain
-- `Domain::indexOf` returns the index of the first occurrence of the label or null
-- `Domain::lastIndexOf` returns the index of the last occurrence of the label or null
+- `Domain::indexOf` returns the index of the first occurrence of the label
+- `Domain::lastIndexOf` returns the index of the last occurrence of the label
 - `Domain::isEmpty` tells whether the domain is empty or not (contains at least on label)
 - `HierarchicalPath::first` returns the first segment
 - `HierarchicalPath::last`  returns the last segment
 - `HierarchicalPath::contains` tells whether the segment is present in the path
-- `HierarchicalPath::indexOf` returns the index of the first occurrence of the segment or null
-- `HierarchicalPath::lastIndexOf` returns the index of the last occurrence of the segment or null
+- `HierarchicalPath::indexOf` returns the index of the first occurrence of the segment
+- `HierarchicalPath::lastIndexOf` returns the index of the last occurrence of the segment
 - `HierarchicalPath::isEmpty` tells whether the path is empty or not (contains at least on segment)
 - `Query::first` returns the first value for a given query key pair
 - `Query::last` returns the last value for a given query key pair
@@ -31,17 +31,22 @@ All Notable changes to `League\Uri\Components` will be documented in this file
 - `Modifier::redactPathSegmentsByOffset` redacts specific path segments by offset if present
 - `Modifier::redactQueryPairs` redacts specific query pair if present
 - `Modifier::prependQuery` prepend a query string to the URI query component
+- `Modifier::prependPath` replace `Modifier::prependSegment`
+- `Modifier::appendPath` replace `Modifier::appendSegment`
+- `Modifier::prependSegments`
+- `Modifier::appendSegments`
 
 ### Fixed
 
 - Fix deprecation message for `Modifier::uri()` method [166](https://github.com/thephpleague/uri-src/pull/166) by [meyerbaptiste](https://github.com/meyerbaptiste) 
-- Fix missing SensitiveParameter usage on `Modifier::withUserInfo` method
+- Fix missing `SensitiveParameter` usage on `Modifier::withUserInfo` method
 - Fix Host resolution using the new `HostRecord` class
-- Fix `Modifier::withPath` improve handling of path leading slash presence
+- Fix `Modifier::withPath` improve handling of path leading slash presence for PSR-7 implementing classes
 
 ### Deprecated
 
-- None
+- `Modifier::prependSegment` use `Modifier::prependPath` instead
+- `Modifier::appendSegment` use `Modifier::appendPath` instead
 
 ### Removed
 

components/Components/HierarchicalPath.php

@@ -28,9 +28,11 @@
 use Uri\Rfc3986\Uri as Rfc3986Uri;
 use Uri\WhatWg\Url as WhatWgUrl;
 
+use ValueError;
 use function array_count_values;
 use function array_filter;
 use function array_keys;
+use function array_map;
 use function array_pop;
 use function array_unshift;
 use function count;
@@ -307,30 +309,60 @@ public function withTrailingSlash(): PathInterface
         };
     }
 
-    public function append(Stringable|string $segment): SegmentedPathInterface
+    public function append(Stringable|string $path): SegmentedPathInterface
     {
-        /** @var string $segment */
-        $segment = self::filterComponent($segment);
+        /** @var string $path */
+        $path = self::filterComponent($path);
 
         return new self(
             rtrim($this->path->toString(), self::SEPARATOR)
             .self::SEPARATOR
-            .ltrim($segment, self::SEPARATOR)
+            .ltrim($path, self::SEPARATOR)
         );
     }
 
-    public function prepend(Stringable|string $segment): SegmentedPathInterface
+    /**
+     * @param iterable<Stringable|string> $segments
+     *
+     * @return SegmentedPathInterface
+     */
+    public function appendSegments(iterable $segments): SegmentedPathInterface
     {
-        /** @var string $segment */
-        $segment = self::filterComponent($segment);
+        $newSegments = [];
+        foreach ($segments as $segment) {
+            $newSegments[] = str_replace('/', '%2F', self::filterComponent($segment) ?? throw new ValueError('The segment can not be null.'));
+        }
+
+        return $this->append(implode('/', $newSegments));
+    }
+
+    public function prepend(Stringable|string $path): SegmentedPathInterface
+    {
+        /** @var string $path */
+        $path = self::filterComponent($path);
 
         return new self(
-            rtrim($segment, self::SEPARATOR)
+            rtrim($path, self::SEPARATOR)
             .self::SEPARATOR
             .ltrim($this->path->toString(), self::SEPARATOR)
         );
     }
 
+    /**
+     * @param iterable<Stringable|string> $segments
+     *
+     * @return SegmentedPathInterface
+     */
+    public function prependSegments(iterable $segments): SegmentedPathInterface
+    {
+        $newSegments = [];
+        foreach ($segments as $segment) {
+            $newSegments[] = str_replace('/', '%2F', self::filterComponent($segment) ?? throw new ValueError('The segment can not be null.'));
+        }
+
+        return $this->prepend(implode('/', $newSegments));
+    }
+
     public function withSegment(int $key, Stringable|string $segment): SegmentedPathInterface
     {
         $nbSegments = count($this->segments);

components/Modifier.php

@@ -31,6 +31,7 @@
 use League\Uri\Contracts\FragmentDirective;
 use League\Uri\Contracts\FragmentInterface;
 use League\Uri\Contracts\PathInterface;
+use League\Uri\Contracts\SegmentedPathInterface;
 use League\Uri\Contracts\UriAccess;
 use League\Uri\Contracts\UriInterface;
 use League\Uri\Exceptions\MissingFeature;
@@ -968,11 +969,39 @@ public function addTrailingSlash(): static
     }
 
     /**
-     * Append a new segment or a new path to the URI path.
+     * Append a new path or add a path to the URI path.
      */
-    public function appendSegment(Stringable|string $segment): static
+    public function appendPath(Stringable|string $path): static
+    {
+        return $this->withPath(HierarchicalPath::fromUri($this->uri)->append($path));
+    }
+
+    /**
+     * Prepend a path or add a new path to the URI path.
+     */
+    public function prependPath(Stringable|string $path): static
     {
-        return $this->withPath(HierarchicalPath::fromUri($this->uri)->append($segment));
+        return $this->withPath(HierarchicalPath::fromUri($this->uri)->prepend($path));
+    }
+
+    /**
+     * Append a list of segments or a new path to the URI path.
+     *
+     * @param iterable<Stringable|string> $segments
+     */
+    public function appendSegments(iterable $segments): static
+    {
+        return $this->withPath(HierarchicalPath::fromUri($this->uri)->appendSegments($segments));
+    }
+
+    /**
+     * Prepend a list of segments or a new path to the URI path.
+     *
+     * @param iterable<Stringable|string> $segments
+     */
+    public function prependSegments(iterable $segments): static
+    {
+        return $this->withPath(HierarchicalPath::fromUri($this->uri)->prependSegments($segments));
     }
 
     /**
@@ -991,14 +1020,6 @@ public function dataPathToBinary(): static
         return $this->withPath(DataPath::fromUri($this->uri)->toBinary()->toString());
     }
 
-    /**
-     * Prepend a new segment or a new path to the URI path.
-     */
-    public function prependSegment(Stringable|string $segment): static
-    {
-        return$this->withPath(HierarchicalPath::fromUri($this->uri)->prepend($segment));
-    }
-
     /**
      * Remove a base path from the URI path.
      */
@@ -1372,6 +1393,32 @@ public function retainFragmentDirectives(): static
         return $this->withFragment(FragmentDirectives::fromUri($this->unwrap()));
     }
 
+    /**
+     * DEPRECATION WARNING! This method will be removed in the next major point release.
+     *
+     * @deprecated Since version 7.7.0
+     * @codeCoverageIgnore
+     * @see Modifier::appendPath
+     */
+    #[Deprecated(message:'use League\Uri\Modifier::appendPath() instead', since:'league/uri-components:7.7.0')]
+    public function appendSegment(Stringable|string $segment): static
+    {
+        return $this->appendPath($segment);
+    }
+
+    /**
+     * DEPRECATION WARNING! This method will be removed in the next major point release.
+     *
+     * @deprecated Since version 7.7.0
+     * @codeCoverageIgnore
+     * @see Modifier::prependPath
+     */
+    #[Deprecated(message:'use League\Uri\Modifier::prependPath() instead', since:'league/uri-components:7.7.0')]
+    public function prependSegment(Stringable|string $segment): static
+    {
+        return $this->prependPath($segment);
+    }
+
     /**
      * DEPRECATION WARNING! This method will be removed in the next major point release.
      *

components/ModifierTest.php

@@ -571,27 +571,27 @@ public function testDataUriWithParameters(): void
         );
     }
 
-    #[DataProvider('appendSegmentProvider')]
+    #[DataProvider('appendPathProvider')]
     public function testAppendProcess(string $segment, string $append): void
     {
-        self::assertSame($append, $this->modifier->appendSegment($segment)->unwrap()->getPath());
+        self::assertSame($append, $this->modifier->appendPath($segment)->unwrap()->getPath());
     }
 
-    public static function appendSegmentProvider(): array
+    public static function appendPathProvider(): array
     {
         return [
             ['toto', '/path/to/the/sky.php/toto'],
             ['le blanc', '/path/to/the/sky.php/le%20blanc'],
         ];
     }
 
-    #[DataProvider('validAppendSegmentProvider')]
+    #[DataProvider('validAppendPathProvider')]
     public function testAppendProcessWithRelativePath(string $uri, string $segment, string $expected): void
     {
-        self::assertSame($expected, Modifier::wrap($uri)->appendSegment($segment)->toString());
+        self::assertSame($expected, Modifier::wrap($uri)->appendPath($segment)->toString());
     }
 
-    public static function validAppendSegmentProvider(): array
+    public static function validAppendPathProvider(): array
     {
         return [
             'uri with trailing slash' => [
@@ -656,14 +656,14 @@ public static function validDirnameProvider(): array
         ];
     }
 
-    #[DataProvider('prependSegmentProvider')]
-    public function testPrependProcess(string $uri, string $segment, string $expectedPath): void
+    #[DataProvider('prependPathProvider')]
+    public function testPrependPathProcess(string $uri, string $segment, string $expectedPath): void
     {
         $uri = Uri::new($uri);
-        self::assertSame($expectedPath, Modifier::wrap($uri)->prependSegment($segment)->unwrap()->getPath());
+        self::assertSame($expectedPath, Modifier::wrap($uri)->prependPath($segment)->unwrap()->getPath());
     }
 
-    public static function prependSegmentProvider(): array
+    public static function prependPathProvider(): array
     {
         return [
             [

docs/components/7.0/modifiers.md

@@ -130,7 +130,7 @@ use League\Uri\Modifier;
 use Uri\WhatWg\Url;
 
 $uri = Modifier::wrap(new Url('https://www.mypoems.net/the-book-of-mwana-kupona/'))
-    ->prependSegment('epic')
+    ->prependPath('epic')
     ->removeLabels(-1)
     ->replaceLabel(1, "africanpoems")
     ->appendFragmentDirectives(new TextDirective(start: "Negema wangu binti", end: "neno lema kukwambia."))
@@ -313,8 +313,10 @@ to apply the following changes to the submitted URI.
   <li><a href="#modifierreplaceextension">replaceExtension</a></li>
   <li><a href="#modifieraddbasepath">addBasePath</a></li>
   <li><a href="#modifierremovebasepath">removeBasePath</a></li>
-  <li><a href="#modifierappendsegment">appendSegment</a></li>
-  <li><a href="#modifierprependsegment">prependSegment</a></li>
+  <li><a href="#modifierappendpath">appendPath</a></li>
+  <li><a href="#modifierprependpath">prependPath</a></li>
+  <li><a href="#modifierappendsegments">appendSegments</a></li>
+  <li><a href="#modifierprependsegments">prependSegments</a></li>
   <li><a href="#modifierreplacesegment">replaceSegment</a></li>
   <li><a href="#modifierremovesegments">removeSegments</a></li>
   <li><a href="#modifierslicesegments">sliceSegments</a></li>
@@ -1047,27 +1049,64 @@ echo Modifier::wrap($uri)
 //display "/sky"
 ~~~
 
-### Modifier::appendSegment
+### Modifier::appendPath
+
+<p class="message-notice">since version <code>7.7.0</code></p>
+<p class="message-info">replaces and deprecates <code>Modifier::appendSegment</code> since <code>7.7.0</code></p>
+
 
 Appends a path to the current URI path.
 
 ~~~php
 $uri = Http::new("http://www.example.com/path/to/the/sky/");
 echo Modifier::wrap($uri)
-    ->appendSegment("and/above")
+    ->appendPath("and/above")
+    ->unwrap()
+    ->getPath();
+ //display "/path/to/the/sky/and/above"
+~~~
+
+### Modifier::prependPath
+
+<p class="message-notice">since version <code>7.7.0</code></p>
+<p class="message-info">replaces and deprecates <code>Modifier::prependSegment</code> since <code>7.7.0</code></p>
+
+Prepends a path to the current URI path.
+
+~~~php
+$uri = Http::new("http://www.example.com/path/to/the/sky/");
+echo Modifier::wrap($uri)
+    ->prependPath("and/above")
+    ->unwrap()
+    ->getPath();
+ //display "/and/above/path/to/the/sky/"
+~~~
+
+### Modifier::appendSegments
+
+<p class="message-notice">since version <code>7.7.0</code></p>
+
+Appends a list of path segments to the current URI path.
+
+~~~php
+$uri = Http::new("http://www.example.com/path/to/the/sky/");
+echo Modifier::wrap($uri)
+    ->appendSegments(["and","above"])
     ->unwrap()
     ->getPath();
  //display "/path/to/the/sky/and/above"
 ~~~
 
-### Modifier::prependSegment
+### Modifier::prependSegments
+
+<p class="message-notice">since version <code>7.7.0</code></p>
 
 Prepends a path to the current URI path.
 
 ~~~php
 $uri = Http::new("http://www.example.com/path/to/the/sky/");
 echo Modifier::wrap($uri)
-    ->prependSegment("and/above")
+    ->prependSegments(["and","above"])
     ->unwrap()
     ->getPath();
  //display "/and/above/path/to/the/sky/"

interfaces/Contracts/SegmentedPathInterface.php

@@ -71,7 +71,7 @@ public function keys(Stringable|string|null $segment = null): array;
     /**
      * Appends a segment to the path.
      */
-    public function append(Stringable|string $segment): self;
+    public function append(Stringable|string $path): self;
 
     /**
      * Extracts a slice of $length elements starting at position $offset from the host.
@@ -86,7 +86,7 @@ public function slice(int $offset, ?int $length = null): self;
     /**
      * Prepends a segment to the path.
      */
-    public function prepend(Stringable|string $segment): self;
+    public function prepend(Stringable|string $path): self;
 
     /**
      * Returns an instance with the modified segment.