String Utilities

Purpose and Scope

This document covers the Str utility class, which provides string manipulation, pattern matching, and validation capabilities. The Str class extends Hyperf's base string library with additional methods for type conversion, wildcard pattern matching, and UUID validation.

For general helper functions related to strings (like e(), blank(), filled()), see Helper Functions. For data manipulation helpers, see Data Manipulation.

Sources: src/Str.php1-131

---

Class Overview

The Str class is located at Hypervel\Support\Str and extends Hyperf\Stringable\Str (aliased as BaseStr). This inheritance provides access to all base string manipulation methods from Hyperf while adding Hypervel-specific functionality.

Class Hierarchy

Sources: src/Str.php14 src/Str.php8 src/Str.php11-12

---

Type Conversion Methods

The Str class provides methods for converting various types into strings, which is useful for APIs that accept mixed identifier types (cache tags, session keys, Sanctum token abilities).

Method: from()

Converts a single value from multiple input types into a string.

Signature:

Supported Input Types:

Input Type	Conversion Logic	Example
BackedEnum	Extracts the enum's value property	Status::Active->value
Stringable	Calls __toString() method	Object implementing Stringable interface
string	Returns as-is (cast to string)	"example"
int	Cast to string	42 → "42"

Implementation Logic:

Sources: src/Str.php22-33

Method: fromAll()

Converts an array of mixed-type values into an array of strings by applying from() to each element.

Signature:

Implementation:

• Uses array_map() with first-class callable syntax self::from(...)
• Preserves array keys while transforming values

Sources: src/Str.php41-44

---

Pattern Matching

The is() method provides wildcard pattern matching for strings, supporting multiple patterns and case-insensitive matching.

Method: is()

Signature:

Parameters:

Parameter	Type	Description
$pattern	iterable<string>|string	Pattern(s) to match against (supports wildcards)
$value	string	Value to test
$ignoreCase	bool	Whether to perform case-insensitive matching

Pattern Matching Algorithm

Wildcard Behavior:

• * matches any sequence of characters (including empty string)
• Pattern matching is anchored at both ends (uses ^ and \z)
• Multiple patterns are OR'ed together (returns true if any pattern matches)

Examples:

Pattern	Value	Result
"foo*"	"foobar"	true
"foo*"	"barfoo"	false
"*"	Any string	true
["foo*", "bar*"]	"bazqux"	false
["foo*", "bar*"]	"foobar"	true

Sources: src/Str.php53-88

---

UUID Validation

The isUuid() method validates UUID strings and optionally checks for specific UUID versions.

Method: isUuid()

Signature:

Parameters:

Parameter	Type	Description
$value	mixed	Value to validate
$version	null|'max'|'nil'|int<0, 8>	Optional UUID version to check

Version Support

Version Value	Validation Behavior
null	Basic format validation only (regex pattern match)
0 or 'nil'	Checks if UUID is all zeros (nil UUID)
'max'	Checks if UUID is all ones (max UUID)
1 through 8	Validates specific RFC 4122 version

UUID Validation Flow

UUID Format (RFC 4122):

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

• x: Any hexadecimal digit
• M: Version number (1-8 for standard UUIDs)
• N: Variant bits (typically 8, 9, A, or B)

Validation Modes:

1. Basic Format Validation (version = null):

   • Uses regex pattern matching
   • Fast path that doesn't instantiate UUID objects
   • Checks for correct length, hyphen placement, and hexadecimal characters

2. Version-Specific Validation (version provided):

   • Uses Ramsey UUID library for parsing
   • Validates UUID structure and version bits
   • Can distinguish between nil, max, and versioned UUIDs

Sources: src/Str.php96-130

---

Dependencies and Integration

External Dependencies

Required Packages:

• hyperf/stringable (provides base string manipulation via BaseStr)
• ramsey/uuid (provides UUID parsing and validation)

Sources: src/Str.php7-12

---

Usage Patterns

Converting Mixed Types to Strings

Typical Use Case: Converting cache tags that may be enums, objects, or scalars

Pattern Matching with Wildcards

Typical Use Case: Checking if a string matches allowed patterns

UUID Validation

Typical Use Case: Validating API input parameters

Sources: src/Str.php16-33 src/Str.php53-88 src/Str.php96-130

---

Method Summary Table

Method	Parameters	Return Type	Purpose
from()	string|int|BackedEnum|Stringable $value	string	Convert single value to string
fromAll()	array $values	array<string>	Convert array of values to strings
is()	iterable|string $pattern, string $value, bool $ignoreCase = false	bool	Test if value matches wildcard pattern(s)
isUuid()	mixed $value, null|'max'|'nil'|int<0,8> $version = null	bool	Validate UUID format and version

Sources: src/Str.php22 src/Str.php41 src/Str.php53 src/Str.php96