Merge branch 'master' into 3.1

# Conflicts:
#	.github/workflows/test.yml
#	src/service-governance/src/Listener/RegisterServiceListener.php
#	src/stringable/composer.json
#	src/stringable/tests/StrTest.php

Author: limingxinleo

.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Create Release
         id: create_release
         uses: actions/create-release@v1

composer.json

@@ -17,6 +17,7 @@
     },
     "require": {
         "php": ">=8.1",
+        "ext-mbstring": "*",
         "hyperf/collection": "~3.1.0",
         "hyperf/conditionable": "~3.1.0",
         "hyperf/macroable": "~3.1.0",

src/Str.php

@@ -16,6 +16,7 @@
 use Hyperf\Collection\Collection;
 use Hyperf\Macroable\Macroable;
 use InvalidArgumentException;
+use JsonException;
 use Ramsey\Uuid\Uuid;
 use Ramsey\Uuid\UuidInterface;
 use RuntimeException;
@@ -877,6 +878,178 @@ public static function orderedUuid(?DateTimeInterface $time = null): UuidInterfa
         return Uuid::uuid7($time);
     }
 
+    public static function betweenFirst($subject, $from, $to)
+    {
+        if ($from === '' || $to === '') {
+            return $subject;
+        }
+
+        return Str::before(Str::after($subject, $from), $to);
+    }
+
+    public static function classNamespace($value): string
+    {
+        if ($pos = strrpos($value, '\\')) {
+            return substr($value, 0, $pos);
+        }
+
+        return '';
+    }
+
+    public static function convertCase(string $string, int $mode = MB_CASE_FOLD, ?string $encoding = 'UTF-8'): string
+    {
+        return mb_convert_case($string, $mode, $encoding);
+    }
+
+    public static function excerpt($text, $phrase = '', $options = [])
+    {
+        $radius = $options['radius'] ?? 100;
+        $omission = $options['omission'] ?? '...';
+
+        preg_match('/^(.*?)(' . preg_quote((string) $phrase) . ')(.*)$/iu', (string) $text, $matches);
+
+        if (empty($matches)) {
+            return null;
+        }
+
+        $startStr = ltrim($matches[1]);
+        $start = Str::of(mb_substr($matches[1], max(mb_strlen($startStr, 'UTF-8') - $radius, 0), $radius, 'UTF-8'))->ltrim();
+        $start = $start->unless(
+            (fn ($startWithRadius) => $startWithRadius->exactly($startStr))($start),
+            fn ($startWithRadius) => $startWithRadius->prepend($omission),
+        );
+
+        $endStr = rtrim($matches[3]);
+        $end = Str::of(mb_substr($endStr, 0, $radius, 'UTF-8'))->rtrim();
+        $end = $end->unless(
+            (fn ($endWithRadius) => $endWithRadius->exactly($endStr))($end),
+            fn ($endWithRadius) => $endWithRadius->append($omission),
+        );
+
+        return $start->append($matches[2], $end)->__toString();
+    }
+
+    public static function isJson($value): bool
+    {
+        if (! is_string($value)) {
+            return false;
+        }
+
+        if (function_exists('json_validate')) {
+            return json_validate($value, 512);
+        }
+
+        try {
+            json_decode($value, true, 512, JSON_THROW_ON_ERROR);
+        } catch (JsonException $e) {
+            return false;
+        }
+
+        return true;
+    }
+
+    public static function lcfirst($string): string
+    {
+        return Str::lower(Str::substr($string, 0, 1)) . Str::substr($string, 1);
+    }
+
+    public static function password($length = 32, $letters = true, $numbers = true, $symbols = true, $spaces = false)
+    {
+        return (new Collection())
+            ->when($letters, fn ($c) => $c->merge([
+                'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k',
+                'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v',
+                'w', 'x', 'y', 'z', 'A', 'B', 'C', 'D', 'E', 'F', 'G',
+                'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R',
+                'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
+            ]))
+            ->when($numbers, fn ($c) => $c->merge([
+                '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
+            ]))
+            ->when($symbols, fn ($c) => $c->merge([
+                '~', '!', '#', '$', '%', '^', '&', '*', '(', ')', '-',
+                '_', '.', ',', '<', '>', '?', '/', '\\', '{', '}', '[',
+                ']', '|', ':', ';',
+            ]))
+            ->when($spaces, fn ($c) => $c->merge([' ']))
+            ->pipe(fn ($c) => Collection::times($length, fn () => $c[random_int(0, $c->count() - 1)]))
+            ->implode('');
+    }
+
+    public static function replaceStart($search, $replace, $subject)
+    {
+        $search = (string) $search;
+
+        if ($search === '') {
+            return $subject;
+        }
+
+        if (static::startsWith($subject, $search)) {
+            return static::replaceFirst($search, $replace, $subject);
+        }
+
+        return $subject;
+    }
+
+    public static function replaceEnd($search, $replace, $subject)
+    {
+        $search = (string) $search;
+
+        if ($search === '') {
+            return $subject;
+        }
+
+        if (static::endsWith($subject, $search)) {
+            return static::replaceLast($search, $replace, $subject);
+        }
+
+        return $subject;
+    }
+
+    public static function reverse($value): string
+    {
+        return implode(array_reverse(mb_str_split($value)));
+    }
+
+    public static function squish($value): array|string|null
+    {
+        return preg_replace('~(\s|\x{3164}|\x{1160})+~u', ' ', preg_replace('~^[\s\x{FEFF}]+|[\s\x{FEFF}]+$~u', '', $value));
+    }
+
+    public static function substrReplace($string, $replace, $offset = 0, $length = null): array|string
+    {
+        if ($length === null) {
+            $length = strlen($string);
+        }
+
+        return substr_replace($string, $replace, $offset, $length);
+    }
+
+    public static function swap(array $map, $subject): array|string
+    {
+        return str_replace(array_keys($map), array_values($map), $subject);
+    }
+
+    public static function ucsplit($string): array|bool
+    {
+        return preg_split('/(?=\p{Lu})/u', $string, -1, PREG_SPLIT_NO_EMPTY);
+    }
+
+    public static function wordCount($string): array|int
+    {
+        return str_word_count($string);
+    }
+
+    public static function wrap($value, $before, $after = null): string
+    {
+        return $before . $value . ($after ??= $before);
+    }
+
+    public static function wordWrap($string, $characters = 75, $break = "\n", $cutLongWords = false): string
+    {
+        return wordwrap($string, $characters, $break, $cutLongWords);
+    }
+
     /**
      * Returns the replacements for the ascii method.
      * Note: Adapted from Stringy\Stringy.

src/Stringable.php

@@ -13,6 +13,7 @@
 
 use ArrayAccess;
 use Closure;
+use Hyperf\Collection\Collection;
 use Hyperf\Conditionable\Conditionable;
 use Hyperf\Macroable\Macroable;
 use Hyperf\Tappable\Tappable;
@@ -246,7 +247,7 @@ public function exactly($value)
      *
      * @param string $delimiter
      * @param int $limit
-     * @return \Hyperf\Collection\Collection
+     * @return Collection
      */
     public function explode($delimiter, $limit = PHP_INT_MAX)
     {
@@ -259,7 +260,7 @@ public function explode($delimiter, $limit = PHP_INT_MAX)
      * @param int|string $pattern
      * @param int $limit
      * @param int $flags
-     * @return \Hyperf\Collection\Collection
+     * @return Collection
      */
     public function split($pattern, $limit = -1, $flags = 0)
     {
@@ -404,7 +405,7 @@ public function isMatch($pattern)
      * Get the string matching the given pattern.
      *
      * @param string $pattern
-     * @return \Hyperf\Collection\Collection
+     * @return Collection
      */
     public function matchAll($pattern)
     {
@@ -865,4 +866,156 @@ public function offsetUnset(mixed $offset): void
     {
         unset($this->value[$offset]);
     }
+
+    public function betweenFirst($from, $to): static
+    {
+        return new static(Str::betweenFirst($this->value, $from, $to));
+    }
+
+    public function classNamespace(): static
+    {
+        return new static(Str::classNamespace($this->value));
+    }
+
+    public function convertCase($mode = MB_CASE_FOLD, $encoding = 'UTF-8'): static
+    {
+        return new static(Str::convertCase($this->value, $mode, $encoding));
+    }
+
+    public function excerpt($phrase = '', $options = []): ?string
+    {
+        return Str::excerpt($this->value, $phrase, $options);
+    }
+
+    public function isJson(): bool
+    {
+        return Str::isJson($this->value);
+    }
+
+    public function lcfirst(): static
+    {
+        return new static(Str::lcfirst($this->value));
+    }
+
+    public function newLine($count = 1): static
+    {
+        return $this->append(str_repeat(PHP_EOL, $count));
+    }
+
+    public function replaceStart($search, $replace): static
+    {
+        return new static(Str::replaceStart($search, $replace, $this->value));
+    }
+
+    public function replaceEnd($search, $replace): static
+    {
+        return new static(Str::replaceEnd($search, $replace, $this->value));
+    }
+
+    public function reverse(): static
+    {
+        return new static(Str::reverse($this->value));
+    }
+
+    public function scan($format): Collection
+    {
+        return collect(sscanf($this->value, $format));
+    }
+
+    public function squish(): static
+    {
+        return new static(Str::squish($this->value));
+    }
+
+    public function substrReplace($replace, $offset = 0, $length = null): static
+    {
+        return new static(Str::substrReplace($this->value, $replace, $offset, $length));
+    }
+
+    public function swap(array $map)
+    {
+        return new static(strtr($this->value, $map));
+    }
+
+    public function toString(): string
+    {
+        return $this->value;
+    }
+
+    public function ucsplit(): Collection
+    {
+        return collect(Str::ucsplit($this->value));
+    }
+
+    public function value(): string
+    {
+        return $this->toString();
+    }
+
+    public function whenContains($needles, $callback, $default = null)
+    {
+        return $this->when($this->contains($needles), $callback, $default);
+    }
+
+    public function whenContainsAll(array $needles, $callback, $default = null)
+    {
+        return $this->when($this->containsAll($needles), $callback, $default);
+    }
+
+    public function whenEndsWith($needles, $callback, $default = null)
+    {
+        return $this->when($this->endsWith($needles), $callback, $default);
+    }
+
+    public function whenExactly($needles, $callback, $default = null)
+    {
+        return $this->when($this->exactly($needles), $callback, $default);
+    }
+
+    public function whenIs($pattern, $callback, $default = null)
+    {
+        return $this->when($this->is($pattern), $callback, $default);
+    }
+
+    public function whenIsUlid($callback, $default = null)
+    {
+        return $this->when($this->isUlid(), $callback, $default);
+    }
+
+    public function whenIsUuid($callback, $default = null)
+    {
+        return $this->when($this->isUuid(), $callback, $default);
+    }
+
+    public function whenNotExactly($needles, $callback, $default = null)
+    {
+        return $this->when(! $this->exactly($needles), $callback, $default);
+    }
+
+    public function whenStartsWith($needles, $callback, $default = null)
+    {
+        return $this->when($this->startsWith($needles), $callback, $default);
+    }
+
+    public function whenTest($pattern, $callback, $default = null)
+    {
+        return $this->when($this->test($pattern), $callback, $default);
+    }
+
+    public function wrap($before, $after = null)
+    {
+        return new static(Str::wrap($this->value, $before, $after));
+    }
+
+    /**
+     * Wrap a string to a given number of characters.
+     *
+     * @param mixed $characters
+     * @param mixed $break
+     * @param mixed $cutLongWords
+     */
+    public function wordWrap($characters = 75, $break = "\n", $cutLongWords = false): static
+    {
+        return new static(Str::wordWrap($this->value, $characters, $break, $cutLongWords));
+    }
 }