feat(support): add wrap and unwrap to StringHelper (#693)

Author: innocenzi

src/Tempest/Support/src/StringHelper.php

@@ -487,6 +487,51 @@ public function prepend(string|Stringable ...$prepend): self
         return new self(implode('', $prepend) . $this->string);
     }
 
+    /**
+     * Wraps the instance with the given string. If `$after` is specified, it will be appended instead of `$before`.
+     *
+     * ### Example
+     * ```php
+     * str('Scott')->wrap(before: 'Leon ', after: ' Kennedy'); // Leon Scott Kennedy
+     * ```
+     */
+    public function wrap(string|Stringable $before, string|Stringable $after = null): self
+    {
+        return new self($before . $this->string . ($after ??= $before));
+    }
+
+    /**
+     * Removes the specified `$before` and `$after` from the beginning and the end of the instance. If `$after` is null, `$before` is used instead.
+     * Setting `$strict` to `false` will unwrap the instance even if both ends do not correspond to the specified `$before` and `$after`.
+     *
+     * ### Example
+     * ```php
+     *  str('Scott Kennedy')->unwrap(before: 'Leon ', after: ' Kennedy', strict: false); // Scott
+     * ```
+     */
+    public function unwrap(string|Stringable $before, string|Stringable $after = null, bool $strict = true): self
+    {
+        $string = $this->string;
+
+        if ($string === '') {
+            return $this;
+        }
+
+        if ($after === null) {
+            $after = $before;
+        }
+
+        if (! $strict) {
+            return (new self($string))->after($before)->beforeLast($after);
+        }
+
+        if ($this->startsWith($before) && $this->endsWith($after)) {
+            $string = (string) (new self($string))->after($before)->beforeLast($after);
+        }
+
+        return new self($string);
+    }
+
     /**
      * Replaces all occurrences of the given `$search` with `$replace`.
      */

src/Tempest/Support/tests/StringHelperTest.php

@@ -456,4 +456,23 @@ public function test_excerpt(): void
 
         $this->assertSame([2 => 'b', 3 => 'c', 4 => 'd'], $content->excerpt(2, 4, asArray: true)->toArray());
     }
+
+    public function test_wrap(): void
+    {
+        $this->assertSame('Leon Scott Kennedy', str('Scott')->wrap(before: 'Leon ', after: ' Kennedy')->toString());
+        $this->assertSame('"value"', str('value')->wrap('"')->toString());
+    }
+
+    public function test_unwrap(): void
+    {
+        $this->assertSame('Scott', str('Leon Scott Kennedy')->unwrap(before: 'Leon ', after: ' Kennedy')->toString());
+        $this->assertSame('value', str('"value"')->unwrap('"')->toString());
+        $this->assertSame('"value"', str('"value"')->unwrap('`')->toString());
+        $this->assertSame('[value', str('[value')->unwrap('[', ']')->toString());
+        $this->assertEquals('some: "json"', str('{some: "json"}')->unwrap('{', '}')->toString());
+
+        $this->assertSame('value', str('[value')->unwrap('[', ']', strict: false)->toString());
+        $this->assertSame('value', str('value]')->unwrap('[', ']', strict: false)->toString());
+        $this->assertSame('Scott', str('Scott Kennedy')->unwrap(before: 'Leon ', after: ' Kennedy', strict: false)->toString());
+    }
 }