#Strings

Phuture\Coherence\Strings

class Strings extends StaticClass

Comprehensive string manipulation utility class with multibyte-safe operations.

This utility class provides a complete toolkit for string manipulation, including case conversion, pattern matching, extraction, modification, splitting, joining, validation, truncation, encoding conversion, and miscellaneous string operations.

Key features:

• Core Operations: Length, case conversion, reversal, and repetition
• Search & Matching: Find substrings, check for containment, and locate positions
• Extraction: Extract portions before, after, or between delimiters
• Modification: Replace, remove, trim, pad, and insert substrings
• Case Conversion: camel, snake, kebab, pascal, headline
• Splitting & Joining: Split strings into arrays by patterns or delimiters
• Counting & Comparison: Count occurrences, compare strings, check equality
• Truncation & Wrapping: Limit length, wrap text, and extract excerpts
• Testing & Checking: Validate URLs, emails, UUIDs, ASCII, JSON, and more
• Encoding & Conversion: Transliterate to ASCII, generate slugs
• Miscellaneous: Mask, random strings, UUIDs, chunking, and swapping

#Constants

#MAX_DECIMALS

const MAX_DECIMALS = 100

Highest number of decimal places accepted by numberFormat().

Formatting with an arbitrarily large number of decimals allocates a string of that length, which exhausts memory long before the result is useful. PHP 8.6 rejects out-of-range values outright, so the limit is enforced here to keep the behaviour identical across versions.

#Methods

#addCSlashes()

public static function addCSlashes(string $string, string $characters): string

Escapes specific characters in a string using C-style backslash notation.

Wraps PHP's native addcslashes(). Characters listed in $characters are escaped with backslashes. Supports ranges like \n..\r and \0..\31.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::addCSlashes('hello world', 'aeiou'); // 'h\\ell\\o w\\orld'
4Strings::addCSlashes("hello\x00world", "\x00"); // 'hello\0world'

Returns string — The C-style escaped string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $characters is empty

See also

• \Phuture\Coherence\Strings::stripCSlashes()

#addSlashes()

public static function addSlashes(string $string): string

Escapes single quotes, double quotes, backslashes, and NUL bytes in a string.

Wraps PHP's native addslashes(). Useful for preparing strings for database queries or other contexts that require backslash escaping.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::addSlashes("hello 'world'"); // "hello \\'world\\'"
4Strings::addSlashes('path\\to\\file'); // 'path\\\\to\\\\file'

Returns string — The escaped string

See also

• \Phuture\Coherence\Strings::stripSlashes()

#after()

public static function after(string $string, string $search, string $encoding = 'UTF-8'): string

Returns the portion of the string after the first occurrence of a search value.

Searches for the first occurrence of $search in $string and returns everything that follows it. Returns an empty string when the search value is not found. Returns the original string unchanged when $search is an empty string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::after('[email protected]', '@'); // 'example.com'
4Strings::after('2023-12-25', '-'); // '12-25'
5Strings::after('hello', 'x'); // ''

Returns string — The substring after the first occurrence, or an empty string if not found

See also

• \Phuture\Coherence\Strings::afterLast()
• \Phuture\Coherence\Strings::before()

#afterLast()

public static function afterLast(string $string, string $search, string $encoding = 'UTF-8'): string

Returns the portion of the string after the last occurrence of a search value.

Searches for the last occurrence of $search in $string and returns everything that follows it. Returns an empty string when the search value is not found. Returns the original string unchanged when $search is an empty string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::afterLast('path/to/file.txt', '/'); // 'file.txt'
4Strings::afterLast('a.b.c', '.'); // 'c'
5Strings::afterLast('hello', 'x'); // ''

Returns string — The substring after the last occurrence, or an empty string if not found

See also

• \Phuture\Coherence\Strings::after()
• \Phuture\Coherence\Strings::beforeLast()

#ascii()

public static function ascii(string $string, string $language = 'en'): string

Transliterates a string to its ASCII representation.

Converts accented and non-ASCII characters to their closest ASCII equivalents, then strips any remaining non-printable ASCII characters. Supports language-specific transliteration rules (e.g., German umlauts).

Example:

1use Phuture\Coherence\Strings;
2
3Strings::ascii('héllo'); // 'hello'
4Strings::ascii('ñaño'); // 'nano'
5Strings::ascii('über', 'de'); // 'ueber'

Returns string — The ASCII-safe string

See also

• \Phuture\Coherence\Strings::slug()

#asciiArt()

public static function asciiArt(string $text, string $font = 'block', string $encoding = 'UTF-8'): string

Generates an ASCII art representation of the given text using a block font.

Renders each character of $text as a 5-row tall block-style ASCII art figure. Supports uppercase and lowercase letters A–Z (normalised to uppercase), digits 0–9, and common punctuation. Unsupported characters are rendered as blank columns.

Example:

1use Phuture\Coherence\Strings;
2
3echo Strings::asciiArt('Hi');
4// #    # ######
5// #    #   ##
6// ######   ##
7// #    #   ##
8// #    # ######

Returns string — The multi-line ASCII art string

See also

• \Phuture\Coherence\Strings::ascii()

#before()

public static function before(string $string, string $search, string $encoding = 'UTF-8'): string

Returns the portion of the string before the first occurrence of a search value.

Searches for the first occurrence of $search in $string and returns everything that precedes it. Returns the original string when the search value is not found or when $search is an empty string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::before('[email protected]', '@'); // 'user'
4Strings::before('2023-12-25', '-'); // '2023'
5Strings::before('hello', 'x'); // 'hello'

Returns string — The substring before the first occurrence, or the original string if not found

See also

• \Phuture\Coherence\Strings::beforeLast()
• \Phuture\Coherence\Strings::after()

#beforeLast()

public static function beforeLast(string $string, string $search, string $encoding = 'UTF-8'): string

Returns the portion of the string before the last occurrence of a search value.

Searches for the last occurrence of $search in $string and returns everything that precedes it. Returns the original string when the search value is not found or when $search is an empty string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::beforeLast('path/to/file.txt', '/'); // 'path/to'
4Strings::beforeLast('a.b.c', '.'); // 'a.b'
5Strings::beforeLast('hello', 'x'); // 'hello'

Returns string — The substring before the last occurrence, or the original string if not found

See also

• \Phuture\Coherence\Strings::before()
• \Phuture\Coherence\Strings::afterLast()

#between()

public static function between(string $string, string $start, string $end, string $encoding = 'UTF-8'): string

Returns the portion of the string between two delimiter values.

Finds the first occurrence of $start and the first occurrence of $end after it, and returns everything in between. Returns the original string when either delimiter is empty or not found.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::between('[hello]', '[', ']'); // 'hello'
4Strings::between('[email protected]', '@', '.'); // 'example'
5Strings::between('hello', '{', '}'); // 'hello'

Returns string — The substring between the delimiters, or the original string if not found

See also

• \Phuture\Coherence\Strings::before()
• \Phuture\Coherence\Strings::after()

#camel()

public static function camel(string $string): string

Converts a string to camelCase.

Words separated by spaces, hyphens, underscores, or CamelCase boundaries are joined together with each word (except the first) capitalised. The result starts with a lowercase letter.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::camel('hello world'); // 'helloWorld'
4Strings::camel('hello_world'); // 'helloWorld'
5Strings::camel('hello-world'); // 'helloWorld'
6Strings::camel('HelloWorld'); // 'helloWorld'

Returns string — The camelCase version of the string

See also

• \Phuture\Coherence\Strings::pascal()
• \Phuture\Coherence\Strings::snake()

#censor()

public static function censor(string $string, array $bannedWords, string $replacement = '***'): string

Censors all occurrences of banned words in a string by replacing them with a substitution.

Matching is case-insensitive. Each matched word is replaced with $replacement in full, regardless of the matched word's length. The string is returned unchanged when $bannedWords is empty.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::censor('This is bad and awful', ['bad', 'awful']); // 'This is *** and ***'
4Strings::censor('BAD language', ['bad'], '####'); // '#### language'

Returns string — The censored string

See also

• \Phuture\Coherence\Strings::replace()

#charAt()

public static function charAt(string $string, int $index, string $encoding = 'UTF-8'): string

Returns the character at the given index position.

Supports negative indices to count from the end of the string. Returns an empty string when the index is out of bounds.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::charAt('hello', 0); // 'h'
4Strings::charAt('hello', -1); // 'o'
5Strings::charAt('hello', 10); // ''

Returns string — The character at the given position, or an empty string if out of bounds

See also

• \Phuture\Coherence\Strings::slice()

#charCounts()

public static function charCounts(string $string, CharCountMode $mode = CharCountMode::All): array|int|string

Returns information about the byte values used in a string.

CharCountMode::All returns an array with all 256 possible byte values as keys and their frequency as values. CharCountMode::Present returns only byte values with a count greater than zero. CharCountMode::Absent returns only byte values with a count of zero. CharCountMode::Unique returns a string containing all unique byte values found.

Example:

1use Phuture\Coherence\Strings;
2use Phuture\Coherence\Enum\CharCountMode;
3
4$counts = Strings::charCounts('hello', CharCountMode::Present);
5// $counts[104] is 1 (one 'h'), $counts[108] is 2 (two 'l's)
6
7$unique = Strings::charCounts('hello', CharCountMode::Unique);
8// 'ehlo' — unique bytes sorted

Returns array|int|string — The result depends on $mode

See also

• \Phuture\Coherence\Enum\CharCountMode

#chunk()

public static function chunk(string $string, int $size, string $encoding = 'UTF-8'): array

Splits the string into an array of chunks of the given size.

Divides the string into sequential chunks of $size characters each. The last chunk may be shorter if the string length is not evenly divisible by $size. Throws when $size is less than or equal to zero.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::chunk('abcdef', 2); // ['ab', 'cd', 'ef']
4Strings::chunk('hello', 3); // ['hel', 'lo']

Returns array — Array of string chunks, indexed sequentially from zero

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $size is less than or equal to zero

See also

• \Phuture\Coherence\Strings::split()

#compare()

public static function compare(string $string, string $other, bool $caseSensitive = true, string $encoding = 'UTF-8'): int

Compares two strings lexicographically.

Returns a negative integer, zero, or a positive integer depending on whether the first string is less than, equal to, or greater than the second string. Supports optional case-insensitive comparison.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::compare('apple', 'banana'); // negative
4Strings::compare('banana', 'apple'); // positive
5Strings::compare('hello', 'hello'); // 0
6Strings::compare('Hello', 'hello', false); // 0

Returns int — Negative if less than, 0 if equal, positive if greater than

See also

• \Phuture\Coherence\Strings::equals()

#compareNatural()

public static function compareNatural(string $string, string $other, bool $caseSensitive = true): int

Compares two strings using a "natural order" algorithm.

Natural order comparison arranges strings the way a human would. For example, "img2" comes before "img10" in natural order (unlike lexicographic order). Returns a negative integer, zero, or a positive integer depending on whether the first string is less than, equal to, or greater than the second string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::compareNatural('img2', 'img10'); // negative (img2 < img10)
4Strings::compareNatural('img10', 'img2'); // positive (img10 > img2)
5Strings::compareNatural('hello', 'hello'); // 0
6Strings::compareNatural('Hello', 'hello', false); // 0

Returns int — Negative if less than, 0 if equal, positive if greater than

See also

• \Phuture\Coherence\Strings::compare()

#contains()

public static function contains(string $string, string $search, bool $caseSensitive = true, string $encoding = 'UTF-8'): bool

Determines whether a string contains a given search value.

An empty $search always returns true. Supports optional case-insensitive matching. This method wraps PHP's native str_contains() with multibyte-safe handling and additional case-insensitive support.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::contains('hello world', 'world'); // true
4Strings::contains('hello world', 'World', false); // true (case-insensitive)
5Strings::contains('hello world', 'xyz'); // false

Returns bool — True when the string contains the search value

See also

• \Phuture\Coherence\Strings::containsAll()
• \Phuture\Coherence\Strings::containsNone()

#containsAll()

public static function containsAll(string $string, array $searches, bool $caseSensitive = true): bool

Determines whether a string contains all of the given search values.

Returns true only when every value in $searches is found within $string. An empty $searches array always returns true.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::containsAll('hello world', ['hello', 'world']); // true
4Strings::containsAll('hello world', ['hello', 'xyz']); // false

Returns bool — True when all search values are found

See also

• \Phuture\Coherence\Strings::contains()
• \Phuture\Coherence\Strings::containsNone()

#containsNone()

public static function containsNone(string $string, array $searches, bool $caseSensitive = true): bool

Determines whether a string contains none of the given search values.

Returns true only when every value in $searches is absent from $string. An empty $searches array always returns true.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::containsNone('hello world', ['foo', 'bar']); // true
4Strings::containsNone('hello world', ['hello', 'bar']); // false

Returns bool — True when none of the search values are found

See also

• \Phuture\Coherence\Strings::contains()
• \Phuture\Coherence\Strings::containsAll()

#countOccurrences()

public static function countOccurrences(string $string, string $search, string $encoding = 'UTF-8'): int

Counts the number of non-overlapping times a given text appears in a string.

Returns zero when $search is an empty string or is not found in $string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::countOccurrences('hello world hello', 'hello'); // 2
4Strings::countOccurrences('aaaa', 'aa'); // 2
5Strings::countOccurrences('hello', 'xyz'); // 0

Returns int — The number of non-overlapping times the text appears

See also

• \Phuture\Coherence\Strings::contains()

#dedupe()

public static function dedupe(string $string, string $character = ' '): string

Removes duplicate consecutive occurrences of a character from the string.

Replaces runs of two or more adjacent occurrences of $character with a single occurrence. Returns the string unchanged when $character is an empty string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::dedupe('hello    world'); // 'hello world'
4Strings::dedupe('a,,,b,,,c', ','); // 'a,b,c'
5Strings::dedupe('---test---', '-'); // '-test-'

Returns string — The string with consecutive duplicate characters collapsed

See also

• \Phuture\Coherence\Strings::squish()

#distance()

public static function distance(string $string, string $other): int

Calculates the Levenshtein edit distance between two strings.

The edit distance is the minimum number of single-character edits (insertions, replacements, or deletions) required to transform one string into the other.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::distance('hello', 'hello'); // 0
4Strings::distance('hello', 'hallo'); // 1
5Strings::distance('kitten', 'sitting'); // 3

Returns int — The minimum number of edits needed to transform one string into the other

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When either string exceeds 255 bytes

See also

• \Phuture\Coherence\Strings::similar()

#endsWith()

public static function endsWith(string $string, string $search, string $encoding = 'UTF-8'): bool

Determines whether a string ends with a given search value.

Returns true when $string ends with exactly $search. An empty $search always returns true.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::endsWith('image.jpg', '.jpg'); // true
4Strings::endsWith('hello world', 'world'); // true
5Strings::endsWith('hello', 'Hello'); // false

Returns bool — True when the string ends with the search value

See also

• \Phuture\Coherence\Strings::startsWith()

#entityDecode()

public static function entityDecode(string $string, int $flags = ENT_QUOTES | ENT_SUBSTITUTE, string $encoding = 'UTF-8'): string

Converts HTML entities back to their corresponding characters.

Reverses the encoding performed by entityEncode().

Example:

1use Phuture\Coherence\Strings;
2
3Strings::entityDecode('hello & "world"'); // 'hello & "world"'
4Strings::entityDecode('café'); // 'café'

Returns string — The decoded string

See also

• \Phuture\Coherence\Strings::entityEncode()

#entityEncode()

public static function entityEncode(string $string, int $flags = ENT_QUOTES | ENT_SUBSTITUTE, string $encoding = 'UTF-8'): string

Converts all applicable characters to HTML entities.

Translates characters that have HTML entity equivalents (like &, <, >, accented characters, etc.) into their entity representations.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::entityEncode('hello & "world"'); // 'hello & "world"'
4Strings::entityEncode('café'); // 'café'

Returns string — The HTML-entity-encoded string

See also

• \Phuture\Coherence\Strings::entityDecode()

#equals()

public static function equals(string $string, string $other, bool $caseSensitive = true): bool

Determines whether two strings are equal.

Supports optional case-insensitive comparison using multibyte-safe lowercasing.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::equals('hello', 'hello'); // true
4Strings::equals('Hello', 'hello'); // false
5Strings::equals('Hello', 'hello', false); // true

Returns bool — True when the strings are equal

See also

• \Phuture\Coherence\Strings::compare()

#excerpt()

public static function excerpt(string $string, string $phrase, int $radius = 100, string $omission = '...', string $encoding = 'UTF-8'): string

Extracts a contextual excerpt of a string around a given phrase.

Finds the first occurrence of $phrase (case-insensitive) and returns a surrounding excerpt bounded by $radius characters on each side. Truncated ends are indicated by $omission. When $phrase is empty, returns the beginning of the string up to $radius * 2 characters.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::excerpt('The quick brown fox jumps', 'fox', 5);
4// '...wn fox ju...'

Returns string — The contextual excerpt

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $radius is negative

See also

• \Phuture\Coherence\Strings::limit()
• \Phuture\Coherence\Strings::limitWords()

#explode()

public static function explode(string $string, string $delimiter, int $limit = PHP_INT_MAX): array

Splits a string into an array using a delimiter.

Wraps PHP's native explode() with optional limit support. Throws when $delimiter is an empty string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::explode('a,b,c', ','); // ['a', 'b', 'c']
4Strings::explode('a,b,c', ',', 2); // ['a', 'b,c']

Returns array — Array of substrings, indexed sequentially from zero

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $delimiter is an empty string

See also

• \Phuture\Coherence\Strings::split()

#finish()

public static function finish(string $string, string $suffix): string

Ensures a string ends with exactly one occurrence of the given suffix.

If $string already ends with one or more occurrences of $suffix, they are removed before the suffix is appended once. Returns the string unchanged when $suffix is empty.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::finish('path/to', '/'); // 'path/to/'
4Strings::finish('path/to/', '/'); // 'path/to/'
5Strings::finish('path/to///', '/'); // 'path/to/'

Returns string — The string guaranteed to end with the suffix

See also

• \Phuture\Coherence\Strings::start()

#first()

public static function first(string $string, int $count = 1, string $encoding = 'UTF-8'): string

Returns the first N characters of a string.

Returns an empty string when $count is zero or less, or when the input is empty.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::first('hello', 3); // 'hel'
4Strings::first('ñaño', 2); // 'ña'
5Strings::first('hello'); // 'h'

Returns string — The first N characters

See also

• \Phuture\Coherence\Strings::last()
• \Phuture\Coherence\Strings::take()

#fixEncoding()

public static function fixEncoding(string $string, string $encoding = 'UTF-8'): string

Fixes invalid UTF-8 byte sequences in a string.

Removes or replaces any byte sequences that are not valid UTF-8. The result is guaranteed to be valid UTF-8.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::fixEncoding("hello\xc0world"); // 'helloworld' (invalid byte removed)
4Strings::fixEncoding('valid utf-8 ñoño'); // 'valid utf-8 ñoño'

Returns string — A valid string with invalid byte sequences removed

See also

• \Phuture\Coherence\Strings::scrub()

#format()

public static function format(string $format, mixed ...$args): string

Returns a formatted string using sprintf semantics.

Replaces placeholders in $format with the provided arguments. Supports all standard sprintf format specifiers (%s, %d, %f, %02d, etc.).

Example:

1use Phuture\Coherence\Strings;
2
3Strings::format('Hello, %s!', 'World'); // 'Hello, World!'
4Strings::format('%04d-%02d-%02d', 2026, 5, 1); // '2026-05-01'

Returns string — The formatted string

#fromBase64()

public static function fromBase64(string $string): string

Decodes a Base64-encoded string.

Returns an empty string when the input is not valid Base64.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::fromBase64('aGVsbG8='); // 'hello'
4Strings::fromBase64('not-base64!!!'); // ''

Returns string — The decoded string, or an empty string when decoding fails

See also

• \Phuture\Coherence\Strings::toBase64()

#fromHex()

public static function fromHex(string $string): string|false

Decodes a hex-encoded binary string.

Reverses the encoding performed by toHex(). The input must contain only valid hexadecimal characters (0-9, a-f, A-F) and must have an even length.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::fromHex('68656c6c6f'); // 'hello'

Returns string|false — The decoded binary string, or false when decoding fails

See also

• \Phuture\Coherence\Strings::toHex()

#hamming()

public static function hamming(string $string, string $other, string $encoding = 'UTF-8'): int

Calculates the Hamming distance between two strings.

The Hamming distance is the number of positions at which the corresponding characters are different. Think of it as counting the minimum number of character substitutions needed to turn one string into the other.

Both strings must have the same number of characters. This method is multibyte-safe and works correctly with accented characters and other Unicode text — each Unicode character counts as one unit regardless of how many bytes it uses.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::hamming('karolin', 'kathrin'); // 3
4Strings::hamming('hello', 'hello');     // 0
5Strings::hamming('', '');               // 0

Returns int — The number of positions where the characters differ

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the strings have different character lengths

See also

• \Phuture\Coherence\Strings::distance()
• \Phuture\Coherence\Strings::jaro()

#headline()

public static function headline(string $string): string

Converts a string to a human-readable headline format.

Splits on spaces, hyphens, and underscores, capitalises each word, and joins them with single spaces. Useful for converting identifiers into display labels.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::headline('hello_world'); // 'Hello World'
4Strings::headline('foo-bar-baz'); // 'Foo Bar Baz'
5Strings::headline('hello world'); // 'Hello World'
6Strings::headline('helloWorld'); // 'Hello World'

Returns string — The headline-formatted string

See also

• \Phuture\Coherence\Strings::pascal()
• \Phuture\Coherence\Strings::title()

#highlight()

public static function highlight(string $string, string $phrase, string $tagOpen = '<mark>', string $tagClose = '</mark>'): string

Highlights all occurrences of a phrase within a string by wrapping them in tags.

Matching is case-insensitive. The original casing of the matched text is preserved inside the tags. Returns the string unchanged when $phrase is empty.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::highlight('The quick brown fox', 'quick'); // 'The <mark>quick</mark> brown fox'
4Strings::highlight('Hello World', 'world', '<b>', '</b>'); // 'Hello <b>World</b>'

Returns string — The string with all occurrences of $phrase wrapped in the given tags

See also

• \Phuture\Coherence\Strings::replace()

#indent()

public static function indent(string $string, int $level = 1, string $indentChar = "\t"): string

Adds indentation to each line of a string.

Prepends $indentChar repeated $level times to every line. A line is defined as any sequence ending with \n. Throws when $level is negative.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::indent("line1\nline2"); // "\tline1\n\tline2"
4Strings::indent("line1\nline2", 2); // "\t\tline1\n\t\tline2"
5Strings::indent("line1\nline2", 1, '  '); // "  line1\n  line2"

Returns string — The indented string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $level is negative

#insert()

public static function insert(string $string, string $substring, int $index, string $encoding = 'UTF-8'): string

Inserts a substring into a string at the given index position.

Supports negative indices to insert relative to the end of the string. When $index is beyond the end, the substring is appended. When $index is before the start (after negative adjustment), the substring is prepended.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::insert('hello world', '!', 5); // 'hello! world'
4Strings::insert('hello world', '!', -1); // 'hello worl!d'

Returns string — The string with the substring inserted

See also

• \Phuture\Coherence\Strings::slice()

#is()

public static function is(string $string, string $pattern): bool

Determines whether a string matches a wildcard pattern.

The * character acts as a wildcard matching zero or more characters. All other characters are treated as literals.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::is('user_123', 'user_*'); // true
4Strings::is('photo.jpg', '*.jpg'); // true
5Strings::is('test.jpg', '*.*'); // true
6Strings::is('admin', 'user_*'); // false

Returns bool — True when the string matches the pattern

See also

• \Phuture\Coherence\Strings::matches()

#isAlpha()

public static function isAlpha(string $string): bool

Determines whether a string contains only alphabetic characters.

Returns false for empty strings. Supports multibyte Unicode letters via the \p{L} character class.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isAlpha('hello'); // true
4Strings::isAlpha('héllo'); // true
5Strings::isAlpha('hello1'); // false
6Strings::isAlpha(''); // false

Returns bool — True when the string contains only Unicode letters

See also

• \Phuture\Coherence\Strings::isAlphanumeric()
• \Phuture\Coherence\Strings::isNumeric()

#isAlphanumeric()

public static function isAlphanumeric(string $string): bool

Determines whether a string contains only alphanumeric characters.

Returns false for empty strings. Supports multibyte Unicode letters and numbers via the \p{L}\p{N} character classes.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isAlphanumeric('hello123'); // true
4Strings::isAlphanumeric('hello'); // true
5Strings::isAlphanumeric('hello!'); // false

Returns bool — True when the string contains only Unicode letters and numbers

See also

• \Phuture\Coherence\Strings::isAlpha()
• \Phuture\Coherence\Strings::isNumeric()

#isAscii()

public static function isAscii(string $string): bool

Determines whether a string contains only ASCII characters.

Returns true for empty strings. A string is ASCII-only when all of its bytes fall within the 0x00–0x7F range.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isAscii('hello'); // true
4Strings::isAscii('héllo'); // false
5Strings::isAscii(''); // true

Returns bool — True when the string contains only ASCII characters

See also

• \Phuture\Coherence\Strings::ascii()

#isBlank()

public static function isBlank(string $string): bool

Determines whether a string contains only whitespace characters (or is empty).

Uses PHP's native trim() to detect blank strings. Returns true for the empty string as well as strings containing only spaces, tabs, and newlines.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isBlank(''); // true
4Strings::isBlank('   '); // true
5Strings::isBlank("\t\n"); // true
6Strings::isBlank('hello'); // false

Returns bool — True when the string is blank

See also

• \Phuture\Coherence\Strings::isEmpty()
• \Phuture\Coherence\Strings::isFilled()

#isEmail()

public static function isEmail(string $string): bool

Determines whether a string is a valid email address.

Delegates to PHP's filter_var() with FILTER_VALIDATE_EMAIL.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isEmail('[email protected]'); // true
4Strings::isEmail('not-an-email'); // false

Returns bool — True when the string is a valid email address

See also

• \Phuture\Coherence\Strings::isUrl()

#isEmpty()

public static function isEmpty(string $string): bool

Determines whether a string is exactly empty (zero-length).

A string consisting only of whitespace is NOT considered empty. Use isBlank() to check for whitespace-only strings.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isEmpty(''); // true
4Strings::isEmpty('0'); // false
5Strings::isEmpty(' '); // false

Returns bool — True when the string has zero length

See also

• \Phuture\Coherence\Strings::isNotEmpty()
• \Phuture\Coherence\Strings::isBlank()

#isFilled()

public static function isFilled(string $string): bool

Determines whether a string is non-empty and contains at least one non-whitespace character.

Returns false for empty strings and for strings that consist only of whitespace.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isFilled('hello'); // true
4Strings::isFilled(' hello '); // true
5Strings::isFilled(''); // false
6Strings::isFilled('   '); // false

Returns bool — True when the string contains at least one non-whitespace character

See also

• \Phuture\Coherence\Strings::isBlank()
• \Phuture\Coherence\Strings::isEmpty()

#isJson()

public static function isJson(string $string): bool

Determines whether a string is valid JSON.

Returns false for empty strings and any string that is not valid JSON. Uses PHP 8.3's json_validate() when available, falling back to json_decode() on older versions.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isJson('{"name":"John"}'); // true
4Strings::isJson('["a", "b"]'); // true
5Strings::isJson('not json'); // false
6Strings::isJson(''); // false

Returns bool — True when the string is valid JSON

#isLower()

public static function isLower(string $string): bool

Determines whether a string is entirely lowercase.

Compares the lowercased version of the string against itself using multibyte-safe lowercasing.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isLower('hello'); // true
4Strings::isLower('Hello'); // false
5Strings::isLower(''); // true

Returns bool — True when the string is entirely lowercase

See also

• \Phuture\Coherence\Strings::isUpper()
• \Phuture\Coherence\Strings::lower()

#isNotEmpty()

public static function isNotEmpty(string $string): bool

Determines whether a string is not empty (has at least one character).

The inverse of isEmpty(). A string consisting only of whitespace is NOT empty.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isNotEmpty('hello'); // true
4Strings::isNotEmpty(' '); // true
5Strings::isNotEmpty(''); // false

Returns bool — True when the string is not empty

See also

• \Phuture\Coherence\Strings::isEmpty()

#isNumeric()

public static function isNumeric(string $string): bool

Determines whether a string represents a numeric value.

Returns false for empty strings. Accepts optional leading minus sign and an optional decimal point.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isNumeric('123'); // true
4Strings::isNumeric('-45.6'); // true
5Strings::isNumeric('abc'); // false
6Strings::isNumeric(''); // false

Returns bool — True when the string is numeric

See also

• \Phuture\Coherence\Strings::isAlpha()
• \Phuture\Coherence\Strings::isAlphanumeric()

#isUlid()

public static function isUlid(string $string): bool

Determines whether a string is a valid ULID (Universally Unique Lexicographically Sortable Identifier).

A ULID is 26 characters long and uses Crockford's Base32 character set (0-9 and A-Z excluding I, L, O, U). Matching is case-insensitive.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isUlid('01ARZ3NDEKTSV4RRFFQ69G5FAV'); // true
4Strings::isUlid('not-a-ulid'); // false

Returns bool — True when the string is a valid ULID

See also

• \Phuture\Coherence\Strings::isUuid()

#isUpper()

public static function isUpper(string $string): bool

Determines whether a string is entirely uppercase.

Compares the uppercased version of the string against itself using multibyte-safe uppercasing.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isUpper('HELLO'); // true
4Strings::isUpper('Hello'); // false
5Strings::isUpper(''); // true

Returns bool — True when the string is entirely uppercase

See also

• \Phuture\Coherence\Strings::isLower()
• \Phuture\Coherence\Strings::upper()

#isUrl()

public static function isUrl(string $string): bool

Determines whether a string is a valid URL.

Delegates to PHP's filter_var() with FILTER_VALIDATE_URL.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isUrl('https://example.com'); // true
4Strings::isUrl('not-a-url'); // false

Returns bool — True when the string is a valid URL

See also

• \Phuture\Coherence\Strings::isEmail()

#isUuid()

public static function isUuid(string $string): bool

Determines whether a string is a valid UUID (version 1–5).

Validates the standard 8-4-4-4-12 hexadecimal format using a case-insensitive regular expression.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::isUuid('550e8400-e29b-41d4-a716-446655440000'); // true
4Strings::isUuid('not-a-uuid'); // false

Returns bool — True when the string is a valid UUID

See also

• \Phuture\Coherence\Strings::uuid()

#jaro()

public static function jaro(string $string, string $other, string $encoding = 'UTF-8'): float

Calculates the Jaro similarity between two strings.

The Jaro similarity is a measure of how alike two strings are. It returns a number between 0.0 (completely different) and 1.0 (identical). The algorithm considers two characters to be a "match" when they appear within a certain distance of each other in both strings.

This method is multibyte-safe and works correctly with accented characters, emoji, and other Unicode text — each Unicode character counts as one unit.

Returns 1.0 when both strings are empty (they are identical). Returns 0.0 when one string is empty and the other is not.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::jaro('martha', 'marhta'); // ~0.9444
4Strings::jaro('hello', 'hello'); // 1.0
5Strings::jaro('foo', 'bar'); // 0.0
6Strings::jaro('', ''); // 1.0

Returns float — The Jaro similarity score from 0.0 (different) to 1.0 (identical)

See also

• \Phuture\Coherence\Strings::jaroWinkler()
• \Phuture\Coherence\Strings::distance()
• \Phuture\Coherence\Strings::similar()

#jaroWinkler()

public static function jaroWinkler(string $string, string $other, float $prefixScale = 0.1, string $encoding = 'UTF-8'): float

Calculates the Jaro-Winkler similarity between two strings.

Jaro-Winkler is an extension of the Jaro similarity that gives extra weight to strings sharing a common prefix. A longer shared prefix results in a higher similarity score. This makes it particularly useful for comparing names or words where the beginning matters most.

The prefix scale controls how much the shared prefix boosts the score. The standard value is 0.1 and it must not exceed 0.25, otherwise the result could fall outside the valid 0.0 to 1.0 range.

This method is multibyte-safe and works correctly with accented characters, emoji, and other Unicode text.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::jaroWinkler('martha', 'marhta'); // ~0.9611
4Strings::jaroWinkler('hello', 'hello'); // 1.0
5Strings::jaroWinkler('hello', 'helo', 0.0); // same as jaro()

Returns float — The Jaro-Winkler similarity score from 0.0 (different) to 1.0 (identical)

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $prefixScale exceeds 0.25

See also

• \Phuture\Coherence\Strings::jaro()

#kebab()

public static function kebab(string $string): string

Converts a string to kebab-case.

Words are lowercased and joined with hyphens. Delegates to snake() with a hyphen delimiter.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::kebab('helloWorld'); // 'hello-world'
4Strings::kebab('UserProfileData'); // 'user-profile-data'
5Strings::kebab('hello world'); // 'hello-world'

Returns string — The kebab-case version of the string

See also

• \Phuture\Coherence\Strings::snake()
• \Phuture\Coherence\Strings::camel()

#last()

public static function last(string $string, int $count = 1, string $encoding = 'UTF-8'): string

Returns the last N characters of a string.

Returns an empty string when $count is zero or less, or when the input is empty.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::last('hello', 3); // 'llo'
4Strings::last('ñaño', 2); // 'ño'
5Strings::last('hello'); // 'o'

Returns string — The last N characters

See also

• \Phuture\Coherence\Strings::first()

#lastPosition()

public static function lastPosition(string $string, string $search, int $offset = 0, bool $caseSensitive = true, string $encoding = 'UTF-8'): int|false

Returns the position of the last occurrence of a search value.

Returns false when the search value is not found. Supports optional case-insensitive matching.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::lastPosition('hello world hello', 'hello'); // 12
4Strings::lastPosition('hello', 'xyz'); // false
5Strings::lastPosition('Hello World', 'world', 0, false); // 6

Returns int|false — The position of the last occurrence, or false if not found

See also

• \Phuture\Coherence\Strings::position()

#length()

public static function length(string $string, string $encoding = 'UTF-8'): int

Returns the number of characters in a string.

Multibyte-safe: counts Unicode code points, not bytes.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::length('hello'); // 5
4Strings::length('ñaño'); // 4
5Strings::length('你好'); // 2
6Strings::length(''); // 0

Returns int — The number of characters

See also

• \Phuture\Coherence\Strings::wordCount()

#limit()

public static function limit(string $string, int $limit, string $end = '', string $encoding = 'UTF-8'): string

Limits the string to a given number of characters, appending an omission marker.

Returns the string unchanged when its length is within the limit. Trailing whitespace is trimmed before the omission marker is appended.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::limit('Hello World', 5); // 'Hello'
4Strings::limit('Hello World', 5, '...'); // 'Hello...'
5Strings::limit('Hello World', 5, ' [+]'); // 'Hello [+]'
6Strings::limit('Hi', 5); // 'Hi'

Returns string — The limited string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $limit is negative

See also

• \Phuture\Coherence\Strings::limitWords()
• \Phuture\Coherence\Strings::excerpt()

#limitWords()

public static function limitWords(string $string, int $limit, string $end = ''): string

Limits the number of words in a string, appending an end marker when truncated.

Splits the string into words, keeps only the first $limit words, and joins them back with spaces. Returns the string unchanged when the word count is within the limit.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::limitWords('The quick brown fox jumps', 3); // 'The quick brown'
4Strings::limitWords('The quick brown fox jumps', 3, '...'); // 'The quick brown...'
5Strings::limitWords('Hi there', 5); // 'Hi there' (no truncation, original string returned unchanged)
6Strings::limitWords('Hi there', 5, '...'); // 'Hi there' (no truncation, end marker not appended)

Returns string — The word-limited string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $limit is less than or equal to zero

See also

• \Phuture\Coherence\Strings::limit()
• \Phuture\Coherence\Strings::words()

#lower()

public static function lower(string $string, string $encoding = 'UTF-8'): string

Converts a string to lowercase.

Multibyte-safe: uses mb_strtolower() with UTF-8 encoding.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::lower('HELLO'); // 'hello'
4Strings::lower('ÑOÑO'); // 'ñoño'
5Strings::lower('ÄÖÜ'); // 'äöü'

Returns string — The lowercased string

See also

• \Phuture\Coherence\Strings::upper()
• \Phuture\Coherence\Strings::title()

#lowerFirst()

public static function lowerFirst(string $string, string $encoding = 'UTF-8'): string

Converts only the first character of a string to lowercase.

The remainder of the string is left unchanged. Multibyte-safe.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::lowerFirst('Hello World'); // 'hello World'
4Strings::lowerFirst('HELLO'); // 'hELLO'
5Strings::lowerFirst('Ñoño'); // 'ñoño'

Returns string — The string with its first character lowercased

See also

• \Phuture\Coherence\Strings::lower()
• \Phuture\Coherence\Strings::title()

#mask()

public static function mask(string $string, string $mask = '*', int $offset = 0, ?int $length = null, string $encoding = 'UTF-8'): string

Masks a portion of a string with a repeated mask character.

Replaces characters at positions ($offset, $offset + $length) with $mask. Supports negative offsets to count from the end of the string. When $length is null, all characters from $offset onwards are masked.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::mask('1234567890'); // '**********'
4Strings::mask('1234567890', '*', 3); // '123*******'
5Strings::mask('1234567890', '*', 3, 4); // '123****890'
6Strings::mask('1234567890', '*', -4); // '123456****'

Returns string — The masked string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $length is negative

See also

• \Phuture\Coherence\Strings::limit()

#matches()

public static function matches(string $string, string $pattern): bool

Determines whether a string matches a regular expression pattern.

The $pattern must include delimiters (e.g., /^user_\d+$/). Returns true when the pattern matches the string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::matches('user_123', '/^user_\d+$/'); // true
4Strings::matches('user_abc', '/^user_\d+$/'); // false

Returns bool — True when the pattern matches

See also

• \Phuture\Coherence\Strings::is()

#metaphone()

public static function metaphone(string $string, int $maxPhonemes = 0): string

Calculates the metaphone key of a string.

Metaphone is a phonetic algorithm that encodes words based on how they sound in English. Unlike soundex, metaphone produces keys of variable length and is generally more accurate for English pronunciation. Two words that sound the same will produce the same key.

The string is transliterated to ASCII before processing, making this method safe to use with accented or non-Latin characters — for example, "héllo" is treated the same as "hello".

Example:

1use Phuture\Coherence\Strings;
2
3Strings::metaphone('World'); // 'WRLT'
4Strings::metaphone('Thompson'); // '0MPSN'
5Strings::metaphone('Smith'); // 'SM0'
6Strings::metaphone('Smythe'); // 'SM0'
7Strings::metaphone('héllo'); // 'HL'

Returns string — The metaphone phonetic key

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $string is empty or $maxPhonemes is negative

See also

• \Phuture\Coherence\Strings::soundex()
• \Phuture\Coherence\Strings::ascii()

#nl2br()

public static function nl2br(string $string, bool $useXhtml = true): string

Inserts HTML line breaks before all newlines in a string.

Converts newline characters (\n) to <br> tags. When $useXhtml is true, produces <br /> instead of <br>.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::nl2br("hello\nworld"); // 'hello<br />\nworld'
4Strings::nl2br("hello\nworld", false); // 'hello<br>\nworld'

Returns string — The string with HTML line breaks inserted before newlines

#normalizeNewLines()

public static function normalizeNewLines(string $string): string

Normalizes line endings to Unix-style \n.

Converts Windows-style \r\n and old Mac-style \r to \n. The string is returned unchanged when it contains no line endings.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::normalizeNewLines("line1\r\nline2\rline3"); // "line1\nline2\nline3"

Returns string — The string with all line endings replaced by \n

See also

• \Phuture\Coherence\Strings::strip()

#numberFormat()

public static function numberFormat(float|int $number, int $decimals = 0, string $decimalSeparator = '.', string $thousandsSeparator = ', '): string

Formats a number with grouped thousands and configurable separators.

Rounds the number to $decimals decimal places and inserts $thousandsSeparator between every group of three digits.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::numberFormat(1234.5678, 2); // '1,234.57'
4Strings::numberFormat(1234.5678, 2, ',', '.'); // '1.234,57'
5Strings::numberFormat(1000000); // '1,000,000'

Returns string — The formatted number string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $decimals is negative or greater than MAX_DECIMALS

#of()

public static function of(string $string): Type\Strings

Creates a fluent wrapper around the given string for method chaining.

Returns a Type\Strings instance that wraps the provided string value and exposes every string-returning method as a chainable call.

Example:

1use Phuture\Coherence\Strings;
2
3$result = Strings::of('  hello world  ')
4    ->trim()
5    ->upper()
6    ->get();
7// 'HELLO WORLD'

Returns Type\Strings — A fluent wrapper instance that enables method chaining

See also

• \Phuture\Coherence\Type\Strings — For the fluent wrapper implementation

#pad()

public static function pad(string $string, int $length, string $padString = ' ', PadDirection $direction = PadDirection::Right, string $encoding = 'UTF-8'): string

Pads a string to a given length using a pad string.

Extends the string with the $padString on the side specified by $direction until the total character count reaches $length. When the string is already at or beyond $length, or when $padString is empty, it is returned unchanged. For PadDirection::Both, padding is split evenly; when the total padding is odd the extra character goes to the right side.

Example:

1use Phuture\Coherence\Strings;
2use Phuture\Coherence\Enum\PadDirection;
3
4Strings::pad('hello', 10); // 'hello     '
5Strings::pad('hello', 10, '-'); // 'hello-----'
6Strings::pad('hello', 10, ' ', PadDirection::Left); // '     hello'
7Strings::pad('5', 5, '0', PadDirection::Left); // '00005'
8Strings::pad('hello', 11, '-', PadDirection::Both); // '---hello---'
9Strings::pad('hello', 10, '-', PadDirection::Both); // '--hello---'

Returns string — The padded string

See also

• \Phuture\Coherence\Enum\PadDirection

#pascal()

public static function pascal(string $string): string

Converts a string to PascalCase (StudlyCase).

Words separated by spaces, hyphens, underscores, or CamelCase boundaries are joined together with each word capitalised (including the first).

Example:

1use Phuture\Coherence\Strings;
2
3Strings::pascal('hello world'); // 'HelloWorld'
4Strings::pascal('hello_world'); // 'HelloWorld'
5Strings::pascal('hello-world'); // 'HelloWorld'
6Strings::pascal('helloWorld'); // 'HelloWorld'

Returns string — The PascalCase version of the string

See also

• \Phuture\Coherence\Strings::camel()
• \Phuture\Coherence\Strings::snake()

#password()

public static function password(int $length = 16, bool $includeUppercase = true, bool $includeLowercase = true, bool $includeDigits = true, string $includeSpecialCharacters = '!@#$%^&*()-_=+[]{}|;:, .<>?'): string

Generates a cryptographically secure password with configurable character requirements.

Produces a random password that is guaranteed to contain at least one character from each enabled character pool. The character pools are: uppercase letters, lowercase letters, digits, and special characters. Throws when $length is too short to satisfy all enabled requirements.

Example:

1use Phuture\Coherence\Strings;
2
3$pw = Strings::password(16);
4$pw = Strings::password(20, includeSpecialCharacters: '!@#$%^&*');

Returns string — The generated password

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $length is too short for the enabled requirements
• \Random\RandomException — If the system entropy source is unavailable

See also

• \Phuture\Coherence\Strings::random()

#position()

public static function position(string $string, string $search, int $offset = 0, bool $caseSensitive = true, string $encoding = 'UTF-8'): int|false

Returns the position of the first occurrence of a search value.

Returns false when the search value is not found. Supports optional case-insensitive matching.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::position('hello world', 'world'); // 6
4Strings::position('hello world', 'xyz'); // false
5Strings::position('hello hello', 'hello', 3); // 6
6Strings::position('Hello World', 'world', 0, false); // 6

Returns int|false — The position of the first occurrence, or false if not found

See also

• \Phuture\Coherence\Strings::lastPosition()

#quoteMeta()

public static function quoteMeta(string $string): string

Escapes regular expression meta-characters in a string.

Adds a backslash before each of the characters: . \ + * ? [ ^ ] ( $ ). Useful for preparing a literal string for use in a regular expression pattern.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::quoteMeta('hello (world)'); // 'hello \(world\)'
4Strings::quoteMeta('price: $10.00'); // 'price: \$10\.00'

Returns string — The string with meta-characters escaped

#random()

public static function random(int $length = 16): string

Generates a cryptographically random alphanumeric string.

Uses random_int() for all character selection. Throws RandomException if the system entropy source fails. The character pool is [0-9a-zA-Z] (62 characters).

Example:

1use Phuture\Coherence\Strings;
2
3Strings::random(16); // e.g. 'aB3xK9mNpQ2rZ5wY'
4Strings::random(8); // e.g. 'a1B2c3D4'

Returns string — The random alphanumeric string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $length is less than or equal to zero
• \Random\RandomException — If the system entropy source is unavailable

See also

• \Phuture\Coherence\Strings::uuid()

#remove()

public static function remove(string $string, string $search, bool $caseSensitive = true): string

Removes all occurrences of a search value from a string.

Delegates to replace() with an empty replacement string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::remove('hello world', 'o'); // 'hell wrld'
4Strings::remove('Hello World', 'world', false); // 'Hello '

Returns string — The string with all occurrences removed

See also

• \Phuture\Coherence\Strings::replace()

#repeat()

public static function repeat(string $string, int $times): string

Repeats a string a given number of times.

Returns an empty string when $times is zero. Throws when $times is negative.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::repeat('ab', 3); // 'ababab'
4Strings::repeat('ha', 0); // ''

Returns string — The repeated string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $times is negative

#replace()

public static function replace(string $string, string $search, string $replace, bool $caseSensitive = true): string

Replaces all occurrences of a search value with a replacement.

Returns the string unchanged when $search is empty. Supports optional case-insensitive replacement.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::replace('hello world', 'world', 'PHP'); // 'hello PHP'
4Strings::replace('Hello World', 'world', 'PHP', false); // 'Hello PHP'

Returns string — The string with all occurrences replaced

See also

• \Phuture\Coherence\Strings::replaceFirst()
• \Phuture\Coherence\Strings::replaceLast()
• \Phuture\Coherence\Strings::remove()

#replaceArray()

public static function replaceArray(string $string, string $search, array $replacements, string $encoding = 'UTF-8'): string

Replaces successive occurrences of a search value using values from an array.

Each time $search is found, it is replaced with the next value from $replacements. When the replacements array is exhausted, remaining occurrences are replaced with an empty string. Returns the string unchanged when $search is empty or $replacements is empty.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::replaceArray('Year: ?, Month: ?', '?', ['2026', 'April']); // 'Year: 2026, Month: April'

Returns string — The string with successive occurrences replaced

See also

• \Phuture\Coherence\Strings::replace()

#replaceAt()

public static function replaceAt(string $string, string $replacement, int $position, ?int $length = null, string $encoding = 'UTF-8'): string

Replaces a portion of a string starting at a given character position.

When $length is null, replaces from $position to the end of the string. A negative $position counts from the end of the string. A negative $length stops that many characters before the end of the string.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::replaceAt('hello world', 'PHP', 6); // 'hello PHP'
4Strings::replaceAt('hello world', 'PHP', 6, 5); // 'hello PHP'
5Strings::replaceAt('hello world', '', 5, 6); // 'hello'

Returns string — The modified string

See also

• \Phuture\Coherence\Strings::insert()
• \Phuture\Coherence\Strings::slice()

#replaceFirst()

public static function replaceFirst(string $string, string $search, string $replace, string $encoding = 'UTF-8'): string

Replaces the first occurrence of a search value with a replacement.

Returns the string unchanged when $search is empty or not found.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::replaceFirst('hello hello', 'hello', 'world'); // 'world hello'
4Strings::replaceFirst('hello', 'xyz', 'world'); // 'hello'

Returns string — The string with the first occurrence replaced

See also

• \Phuture\Coherence\Strings::replaceLast()
• \Phuture\Coherence\Strings::replace()

#replaceLast()

public static function replaceLast(string $string, string $search, string $replace, string $encoding = 'UTF-8'): string

Replaces the last occurrence of a search value with a replacement.

Returns the string unchanged when $search is empty or not found.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::replaceLast('hello hello', 'hello', 'world'); // 'hello world'
4Strings::replaceLast('hello', 'xyz', 'world'); // 'hello'

Returns string — The string with the last occurrence replaced

See also

• \Phuture\Coherence\Strings::replaceFirst()
• \Phuture\Coherence\Strings::replace()

#reverse()

public static function reverse(string $string): string

Reverses a string character by character.

Multibyte-safe: splits on Unicode code points before reversing.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::reverse('hello'); // 'olleh'
4Strings::reverse('ñaño'); // 'oñañ'

Returns string — The reversed string

See also

• \Phuture\Coherence\Strings::swap()

#rot13()

public static function rot13(string $string): string

Applies the ROT13 encoding to a string.

ROT13 shifts every ASCII letter by 13 positions, wrapping around the alphabet. Applying it twice returns the original string. Non-alphabetic characters are left unchanged.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::rot13('hello'); // 'uryyb'
4Strings::rot13('uryyb'); // 'hello'
5Strings::rot13('Hello World!'); // 'Uryyb Jbeyq!'

Returns string — The ROT13-encoded string

#scrub()

public static function scrub(string $string): string

Removes dangerous control characters from a string.

Strips bytes in the ranges 0x00–0x08, 0x0B, 0x0C, 0x0E–0x1F, and 0x7F (all ASCII control characters except tab 0x09, LF 0x0A, and CR 0x0D).

Example:

1use Phuture\Coherence\Strings;
2
3Strings::scrub("hello\x00world"); // 'helloworld'
4Strings::scrub("clean text"); // 'clean text'

Returns string — The string with control characters removed

See also

• \Phuture\Coherence\Strings::fixEncoding()

#search()

public static function search(string $string, string $search, bool $beforeNeedle = false, bool $caseSensitive = true, string $encoding = 'UTF-8'): string|false

Returns the portion of the string from the first occurrence of a search value.

Searches for the first occurrence of $search in $string and returns the portion from that position to the end (or everything before it if $beforeNeedle is true). Returns false when $search is not found.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::search('[email protected]', '@'); // '@example.com'
4Strings::search('[email protected]', '@', true); // 'user'
5Strings::search('Hello World', 'world', false, false); // 'World'
6Strings::search('hello', 'xyz'); // false

Returns string|false — The portion from the first occurrence, or false if not found

See also

• \Phuture\Coherence\Strings::position()

#shuffle()

public static function shuffle(string $string): string

Randomly shuffles the characters in a string.

Multibyte-safe: splits on Unicode code points before shuffling. Returns an empty string when the input is empty.

Example:

1use Phuture\Coherence\Strings;
2
3$shuffled = Strings::shuffle('hello'); // e.g. 'lleoh'
4$shuffled = Strings::shuffle('ñaño'); // multibyte-safe shuffle

Returns string — The shuffled string

#similar()

public static function similar(string $string, string $other): float

Calculates the similarity between two strings as a percentage.

Returns a value between 0.0 and 100.0 indicating how similar the two strings are. A value of 100.0 means the strings are identical. Returns 0.0 when either string is empty.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::similar('hello', 'hello'); // 100.0
4Strings::similar('hello', 'hallo'); // ~80.0
5Strings::similar('hello', ''); // 0.0

Returns float — The similarity percentage from 0.0 to 100.0

See also

• \Phuture\Coherence\Strings::distance()

#slice()

public static function slice(string $string, int $start, ?int $length = null, string $encoding = 'UTF-8'): string

Extracts a portion of a string by start position and optional length.

Supports negative $start to count from the end of the string. When $length is null, returns all characters from $start to the end.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::slice('hello world', 0, 5); // 'hello'
4Strings::slice('hello world', 6); // 'world'
5Strings::slice('hello world', -5); // 'world'

Returns string — The extracted substring

See also

• \Phuture\Coherence\Strings::first()
• \Phuture\Coherence\Strings::last()
• \Phuture\Coherence\Strings::charAt()

#slug()

public static function slug(string $string, string $separator = '-', string $language = 'en'): string

Generates a URL-friendly slug from a string.

Transliterates non-ASCII characters, strips non-word characters, collapses separators, and lowercases the result.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::slug('Hello World'); // 'hello-world'
4Strings::slug('Hello World', '_'); // 'hello_world'
5Strings::slug('héllo wörld'); // 'hello-world'

Returns string — The URL-friendly slug

See also

• \Phuture\Coherence\Strings::ascii()

#snake()

public static function snake(string $string, string $delimiter = '_'): string

Converts a string to snake_case with a configurable delimiter.

Words separated by spaces, hyphens, underscores, or CamelCase boundaries are lowercased and joined with the given $delimiter (default: underscore).

Example:

1use Phuture\Coherence\Strings;
2
3Strings::snake('helloWorld'); // 'hello_world'
4Strings::snake('HelloWorld', '-'); // 'hello-world'
5Strings::snake('hello world'); // 'hello_world'
6Strings::snake('XMLParser'); // 'xml_parser'

Returns string — The snake_case version of the string

See also

• \Phuture\Coherence\Strings::kebab()
• \Phuture\Coherence\Strings::camel()

#soundex()

public static function soundex(string $string): string

Calculates the soundex key of a string.

Soundex is a phonetic algorithm that indexes names by their English pronunciation. The result is a 4-character string starting with a letter followed by three digits.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::soundex('Euler'); // 'E460'
4Strings::soundex('Ellery'); // 'E460'
5Strings::soundex('Knuth'); // 'K530'

Returns string — The 4-character soundex key

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $string is empty

#split()

public static function split(string $string, string $pattern, int $limit = -1): array

Splits a string into an array by a literal pattern.

The $pattern is treated as a literal string (not a regex). Returns an array containing the original string when $pattern is empty. The $limit parameter controls the maximum number of elements returned.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::split('a.b.c', '.'); // ['a', 'b', 'c']
4Strings::split('a.b.c', '.', 2); // ['a', 'b.c']

Returns array — Array of substrings, indexed sequentially from zero

See also

• \Phuture\Coherence\Strings::explode()

#squish()

public static function squish(string $string): string

Collapses all whitespace sequences into a single space and trims the result.

Replaces any sequence of one or more whitespace characters (including tabs and newlines) with a single space, then trims the leading and trailing whitespace.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::squish('hello    world'); // 'hello world'
4Strings::squish("  hello   \n   world  "); // 'hello world'
5Strings::squish("a\t\tb\n\nc"); // 'a b c'

Returns string — The string with collapsed whitespace

See also

• \Phuture\Coherence\Strings::trim()
• \Phuture\Coherence\Strings::dedupe()

#start()

public static function start(string $string, string $prefix): string

Ensures a string begins with exactly one occurrence of the given prefix.

If $string already begins with one or more occurrences of $prefix, they are removed before the prefix is prepended once. Returns the string unchanged when $prefix is empty.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::start('/path/to', '/'); // '/path/to'
4Strings::start('path/to', '/'); // '/path/to'
5Strings::start('///path/to', '/'); // '/path/to'

Returns string — The string guaranteed to begin with the prefix

See also

• \Phuture\Coherence\Strings::finish()

#startsWith()

public static function startsWith(string $string, string $search, string $encoding = 'UTF-8'): bool

Determines whether a string begins with a given search value.

Returns true when $string starts with exactly $search. An empty $search always returns true.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::startsWith('hello world', 'hello'); // true
4Strings::startsWith('https://example.com', 'https://'); // true
5Strings::startsWith('hello', 'Hello'); // false

Returns bool — True when the string begins with the search value

See also

• \Phuture\Coherence\Strings::endsWith()

#strip()

public static function strip(string $string, string $allowedTags = ''): string

Strips HTML and PHP tags from a string.

Delegates to PHP's native strip_tags(). An optional list of allowed tags can be provided to preserve specific tags.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::strip('<p>Hello <b>world</b></p>'); // 'Hello world'
4Strings::strip('<p>Hello</p>', '<p>'); // '<p>Hello</p>'

Returns string — The string with HTML/PHP tags removed

See also

• \Phuture\Coherence\Strings::normalizeNewLines()
• \Phuture\Coherence\Strings::trim()

#stripCSlashes()

public static function stripCSlashes(string $string): string

Removes C-style backslash escapes from a string.

Reverses the escaping performed by addCSlashes(), recognizing C-style escape sequences like \n, \r, \t, \0, and octal/hex notations.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::stripCSlashes('h\\ell\\o'); // 'hello'

Returns string — The unescaped string

See also

• \Phuture\Coherence\Strings::addCSlashes()

#stripSlashes()

public static function stripSlashes(string $string): string

Removes backslash escapes added by addSlashes().

Reverses the escaping performed by addSlashes(), removing backslashes before single quotes, double quotes, backslashes, and NUL bytes.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::stripSlashes("hello \\'world\\'"); // "hello 'world'"

Returns string — The unescaped string

See also

• \Phuture\Coherence\Strings::addSlashes()

#swap()

public static function swap(string $string, array $replacements): string

Performs multiple simultaneous search-and-replace operations.

Keys of $replacements are searched for and replaced with their corresponding values. All replacements happen in a single pass.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::swap('hello world', ['hello' => 'hi', 'world' => 'earth']);
4// 'hi earth'

Returns string — The string with all swaps applied

See also

• \Phuture\Coherence\Strings::replace()

#take()

public static function take(string $string, int $count): string

Returns the first or last N characters of a string based on the sign of $count.

A positive $count returns the first N characters; a negative $count returns the last N characters (using the absolute value).

Example:

1use Phuture\Coherence\Strings;
2
3Strings::take('hello world', 5); // 'hello'
4Strings::take('hello world', -5); // 'world'
5Strings::take('hello world', 0); // ''

Returns string — The extracted characters

See also

• \Phuture\Coherence\Strings::first()
• \Phuture\Coherence\Strings::last()

#title()

public static function title(string $string, string $encoding = 'UTF-8'): string

Converts every word in a string to Title Case.

Multibyte-safe: uses mb_convert_case() with MB_CASE_TITLE and UTF-8 encoding.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::title('hello world'); // 'Hello World'
4Strings::title('HELLO WORLD'); // 'Hello World'

Returns string — The title-cased string

See also

• \Phuture\Coherence\Strings::title()
• \Phuture\Coherence\Strings::upper()

#toArray()

public static function toArray(string $string): array

Converts a string to an array of individual characters.

Returns an empty array for an empty string. Each element of the returned array is a single Unicode code point. Multibyte-safe.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::toArray('hello'); // ['h', 'e', 'l', 'l', 'o']
4Strings::toArray('ñaño'); // ['ñ', 'a', 'ñ', 'o']
5Strings::toArray(''); // []

Returns array — Array of individual Unicode characters, indexed sequentially from zero

See also

• \Phuture\Coherence\Strings::split()
• \Phuture\Coherence\Strings::chunk()

#toBase64()

public static function toBase64(string $string): string

Encodes a string to its Base64 representation.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::toBase64('hello'); // 'aGVsbG8='

Returns string — The Base64-encoded string

See also

• \Phuture\Coherence\Strings::fromBase64()

#toHex()

public static function toHex(string $string): string

Converts binary data into its hexadecimal representation.

Generates a hex string (lowercase) where each byte of the input is represented by two hexadecimal digits.

Example:

1use Phuture\Coherence\Strings;
2
3Strings::toHex('hello'); // '68656c6c6f'
4Strings::toHex("\x00\xFF"); // '00ff'

Returns string — The hexadecimal representation

See also

• \Phuture\Coherence\Strings::fromHex()

#trim()

public static function trim(string $string, ?string $characters = null): string

Strips whitespace (or given characters) from the beginning and end of a string.

Delegates to PHP's native mb_trim(). The $characters parameter specifies the characters to strip (default: standard whitespace characters).

Example:

1use Phuture\Coherence\Strings;
2
3Strings::trim('  hello  '); // 'hello'
4Strings::trim('***hello***', '*'); // 'hello'

Returns string — The trimmed string

See also

• \Phuture\Coherence\Strings::trimLeft()
• \Phuture\Coherence\Strings::trimRight()
• \Phuture\Coherence\Strings::squish()

#trimLeft()

public static function trimLeft(string $string, ?string $characters = null): string

Strips whitespace (or given characters) from the beginning of a string.

Delegates to PHP's native mb_ltrim().

Example:

1use Phuture\Coherence\Strings;
2
3Strings::trimLeft('  hello  '); // 'hello  '
4Strings::trimLeft('***hello***', '*'); // 'hello***'

Returns string — The left-trimmed string

See also

• \Phuture\Coherence\Strings::trimRight()
• \Phuture\Coherence\Strings::trim()

#trimRight()

public static function trimRight(string $string, ?string $characters = null): string

Strips whitespace (or given characters) from the end of a string.

Delegates to PHP's native mb_rtrim().

Example:

1use Phuture\Coherence\Strings;
2
3Strings::trimRight('  hello  '); // '  hello'
4Strings::trimRight('***hello***', '*'); // '***hello'