Primordyx Framework Documentation

between()

Extracts the substring found between two delimiters within a string.

Parameters

$str : string

The full input string to search within.

$start : string

The starting delimiter. The result will begin immediately after this.

$end : string

The ending delimiter. The result will end just before this.

Tags

example

Strings::between('abc [target] def', '[', ']');     // 'target'
Strings::between('name: John, age: 42', 'name: ', ','); // 'John'
Strings::between('<<value>>', '<<', '>>');          // 'value'

edgecase

If $start is not found, or $end is not found after $start, the result is null. If $start and $end are the same and only appear once, or appear out of order, the result is null. If the string between delimiters is empty (e.g., abc[]def), an empty string is returned (''), not null.

note

This method only captures the first matching pair of delimiters. It does not support nested or repeated patterns. The search is case-sensitive and non-greedy.

camelCase()

Converts a string into camelCase format, intelligently handling various input styles.

Parameters

$str : string

The input string to convert. May include delimiters or be already in PascalCase or camelCase.

Tags

example

Strings::camelCase('first_name');         // 'firstName'
Strings::camelCase('AlreadyCamelCase');   // 'alreadyCamelCase'
Strings::camelCase('user id');            // 'userId'
Strings::camelCase('super-duper-helper'); // 'superDuperHelper'
Strings::camelCase('JustWordsNoDelimiters'); // 'justWordsNoDelimiters'

edgecase

If the string contains no delimiters and already resembles camelCase or PascalCase, only the first character is lowercased. Empty strings will return as-is.

note

This function does not alter internal capitalization of words in preformatted camelCase input. It assumes you want to preserve existing word boundaries unless delimiters indicate otherwise.

center()

Centers a string within a field of a given width using a specified padding character.

Parameters

$str : string

The input string to center.

$width : int

The total width of the resulting string, including padding.

$pad : string = ' '

The character used for padding. Must be a non-empty string. Defaults to a space ' '.

Tags

example

Strings::center('hello', 11);         // '   hello   '
Strings::center('hello', 10, '-');    // '---hello--'
Strings::center('text', 4);           // 'text'

edgecase

If the padding character is an empty string, str_repeat() will emit a warning and return false. If the total padding is odd, the right side will receive one extra character.

note

This method uses mb_strlen() to ensure multibyte character safety when calculating width.

charFrequency()

Returns a frequency map of characters in the given string.

Parameters

$str : string

The input string.

Tags

example

Strings::charFrequency('hello') returns:
['h' => 1, 'e' => 1, 'l' => 2, 'o' => 1]

clean()

Cleans up excess whitespace from a string.

Parameters

$str : string

The input string to clean.

Tags

example

Strings::clean("  This   is  \n a   test\tstring. "); // 'This is a test string.'
Strings::clean("No extra   spaces");                 // 'No extra spaces'

edgecase

If the input string contains only whitespace, the result will be an empty string. If the input is already clean, it is returned unchanged.

note

This function does not remove or escape HTML tags, special characters, or punctuation— it deals with whitespace only.

collapseWhitespace()

Collapses all sequences of whitespace (spaces, tabs, newlines) into a single space.

Parameters

$str : string

The input string.

Tags

example

Strings::collapseWhitespace(" Hello\t \n world!  ");  // 'Hello world!'

constantTimeEquals()

Compares two strings in constant time to prevent timing attacks.

Parameters

$a : string

The expected (trusted) string.

$b : string

The actual (untrusted) string to compare.

Tags

example

Strings::constantTimeEquals('secret123', 'secret123');  // true
Strings::constantTimeEquals('secret123', 'secret124');  // false

note

This function should always be used for comparing sensitive values like tokens, signatures, or passwords — especially when accepting user input in authentication or verification flows.

contains()

Determines whether a given substring exists within a larger string.

Parameters

$haystack : string

The string to search within.

$needle : string

The substring to search for.

Tags

example

Strings::contains('hello world', 'world'); // true
Strings::contains('hello world', 'World'); // false (case-sensitive)

edgecase

If $needle is an empty string, this function will always return true, because strpos() treats an empty string as being found at the beginning of any string. Example: Strings::contains('anything', '') === true

note

This function is case-sensitive. For case-insensitive checks, use stripos() instead of strpos().

containsAny()

Checks whether the input string contains any of the given substrings.

Parameters

$haystack : string

The string to search within.

$needles : array<string|int, mixed>

An array of substrings to look for.

$ignoreCase : bool = false

Whether to perform case-insensitive matching. Default is false.

Tags

example

Strings::containsAny('Hello World', ['world'], true);    // true
Strings::containsAny('ABC123', ['abc']);                 // false
Strings::containsAny('circle6mail', ['Mail'], true);     // true

decrementString()

Decrements a trailing numeric suffix on a string, optionally removing it if it reaches zero.

Parameters

$str : string

The input string to modify.

$separator : string = '_'

The separator before the number. Default is "_".

$padWidth : int|null = null

If provided, output is zero-padded to this width. Otherwise, preserves original width.

$removeIfZero : bool = false

If true, removes the numeric suffix entirely when result reaches 0. Default is false.

$strictSuffixOnly : bool = false

If true, only decrements suffixes of the form "separator + digits". Default is false.

Tags

example

Strings::decrementString('file_007');                    // 'file_006'
Strings::decrementString('file_001', '_', 3, true);      // 'file'
Strings::decrementString('report-v2', '-', 3, true, true); // 'report-v2-000'
Strings::decrementString('file', '_');                   // 'file'

dedent()

Removes the smallest common leading whitespace from all non-empty lines in a multiline string.

Parameters

$str : string

The input string with consistent leading indentation.

Tags

example

Strings::dedent("    line 1\n    line 2\n    line 3");    // "line 1\nline 2\nline 3"
Strings::dedent("  foo\n    bar\n  baz");                 // "foo\n  bar\nbaz"

note

Blank lines are ignored when calculating minimum indentation. Works with spaces, tabs, or mixed whitespace — but doesn’t normalize them.

detectCaseStyle()

Attempts to detect the casing style of a string.

Parameters

$str : string

The string to analyze.

Tags

example

Strings::detectCaseStyle('helloWorld');     // 'camel'
Strings::detectCaseStyle('HelloWorld');     // 'pascal'
Strings::detectCaseStyle('hello_world');    // 'snake'
Strings::detectCaseStyle('hello-world');    // 'kebab'
Strings::detectCaseStyle('HELLO WORLD');    // 'upper'

detectEncoding()

Attempts to detect the encoding of a string using mb_detect_encoding().

Parameters

$str : string

The input string.

Tags

example

Strings::detectEncoding("hello");   // 'ASCII' or 'UTF-8'

endsWith()

Checks whether a string ends with a given substring.

Parameters

$haystack : string

The full string to evaluate.

$needle : string

The substring to check for at the end of $haystack.

Tags

example

Strings::endsWith('filename.txt', '.txt'); // true
Strings::endsWith('filename.txt', '.TXT'); // false (case-sensitive)
Strings::endsWith('hello', '');            // true (empty needle)

edgecase

An empty $needle will always return true, regardless of $haystack. This behavior might be unexpected in some cases. It stems from the logic that any string "ends with" an empty string.

note

This function is case-sensitive. For case-insensitive checks, consider converting both strings to a common case (strtolower() or mb_strtolower()) before comparison.

endsWithAny()

Checks whether the given string ends with any of the specified suffixes.

Parameters

$haystack : string

The string to check.

$suffixes : array<string|int, mixed>

An array of string suffixes to test against.

Tags

example

Strings::endsWithAny('report.csv', ['.csv', '.txt']);       // true
Strings::endsWithAny('hello-world.js', ['.php', '.html']);  // false

note

Comparison is case-sensitive. Use strtolower() on both haystack and suffixes if you need case-insensitive behavior.

equalsIgnoreCase()

Compares two strings for equality, ignoring case differences.

Parameters

$a : string

The first string to compare.

$b : string

The second string to compare.

Tags

example

Strings::equalsIgnoreCase('Hello', 'hello');     // true
Strings::equalsIgnoreCase('Test', 'TEST');       // true
Strings::equalsIgnoreCase('abc', 'abC');         // true
Strings::equalsIgnoreCase('abc', 'abcd');        // false

edgecase

Locale-sensitive characters (like ß, İ, or accented letters) may not behave as expected with strtolower() depending on the environment and encoding. For full Unicode case folding, use mb_strtolower() with an appropriate locale.

note

This function is ASCII-case-insensitive by default. It may not account for locale or multibyte edge cases unless mbstring functions are explicitly used.

excerpt()

Extracts a contextual excerpt around the first occurrence of a query string.

Parameters

$str : string

The full text to search within.

$query : string

The substring to find within the text.

$radius : int = 50

The number of characters to include before and after the match. Defaults to 50.

Tags

example

Strings::excerpt('The quick brown fox jumps over the lazy dog', 'fox');
// '...quick brown fox jumps over the lazy...'
    *
Strings::excerpt('Nothing to see here', 'missing');
// ''

edgecase

If the query isn't found, the function returns an empty string. If the match is near the start or end of the string, the excerpt may be shorter than expected. If $query appears multiple times, only the first match is considered.

note

This method does not highlight the query term or ensure word boundaries — it’s intended for simple previews. Ellipses are always added at both ends, even if the excerpt begins at position 0 or ends at the string’s end.

formatCurrency()

Parameters

$amount : float

hasMixedCase()

Determines if a string contains both uppercase and lowercase characters.

Parameters

$str : string

The string to evaluate.

Tags

example

Strings::hasMixedCase('Password123');  // true
Strings::hasMixedCase('password');     // false
Strings::hasMixedCase('PASSWORD');     // false

note

This function is multibyte-safe.

hasPrefixAny()

Checks whether a string starts with any of the given prefixes.

Parameters

$haystack : string

The string to evaluate.

$prefixes : array<string|int, mixed>

An array of prefix strings to test against the start of $haystack.

Tags

example

Strings::hasPrefixAny('foobar', ['foo', 'bar']);     // true
Strings::hasPrefixAny('hello world', ['hi', 'hey']); // false
Strings::hasPrefixAny('data.json', ['data.', 'meta.']); // true

edgecase

An empty $prefixes array will always return false since there's nothing to check against. If any prefix in the array is an empty string, it will always match (per startsWith() logic), causing the function to return true immediately.

note

This function performs a case-sensitive comparison. To make it case-insensitive, use a modified version of startsWith() with case normalization.

incrementString()

Appends or increments a trailing numeric suffix on a string, optionally zero-padded.

Parameters

$str : string

The input string to modify.

$separator : string = '_'

The separator to use before the number. Default is "_".

$padWidth : int|null = null

Optional zero-padding width (e.g., 3 → "007").

$strictSuffixOnly : bool = false

If true, only increments suffixes with exact separator + digits. Default is false.

Tags

example

Strings::incrementString('file');                         // 'file_1'
Strings::incrementString('report-v2', '-', 3);            // 'report-v003'
Strings::incrementString('report-v2', '-', 3, true);      // 'report-v2-001' (v2 not incremented)
Strings::incrementString('build-2023.12.01', '-', 3, true); // 'build-2023.12.01-001'

indent()

Indents each line of a string by a given number of characters.

Parameters

$str : string

The input string, possibly multiline.

$spaces : int = 4

The number of characters to indent each line. Default is 4.

$char : string = ' '

The character to use for indentation. Default is a space.

Tags

example

Strings::indent("line 1\nline 2");           // "    line 1\n    line 2"
Strings::indent("foo\nbar", 2, '-');         // "--foo\n--bar"

note

Applies to each line independently using ^ and multiline (/m) regex mode.

initials()

Extracts the uppercase initials from a name or phrase.

Parameters

$str : string

The input string (e.g., full name).

Tags

example

Strings::initials('John Doe');        // 'JD'
Strings::initials('alice cooper');    // 'AC'

isAlnum()

Checks whether a string contains only alphanumeric characters (A–Z, a–z, 0–9).

Parameters

$str : string

The input string to check.

Tags

example

Strings::isAlnum('abc123');      // true
Strings::isAlnum('ABC');         // true
Strings::isAlnum('123');         // true
Strings::isAlnum('abc 123');     // false (contains space)
Strings::isAlnum('naïve');       // false (accented i)

note

This is an ASCII-only check. For Unicode support (e.g., non-English letters and digits), use a Unicode-aware alternative like isLettersOrDigits().

isAlpha()

Determines if a string contains only alphabetic characters (A–Z, a–z).

Parameters

$str : string

The input string to test.

Tags

example

Strings::isAlpha('abc');        // true
Strings::isAlpha('ABCdef');     // true
Strings::isAlpha('abc123');     // false
Strings::isAlpha('café');       // false (accented é is not A–Z)

note

This is ASCII-only. For Unicode letters (e.g., accents, other scripts), use Strings::onlyLetters() with a Unicode-aware regex like \p{L}.

isAscii()

Checks whether a string contains only 7-bit ASCII characters.

Parameters

$str : string

The input string to evaluate.

Tags

example

Strings::isAscii('Hello123');         // true
Strings::isAscii('Café');             // false (é is non-ASCII)
Strings::isAscii("Line\nBreak");      // true (newline is ASCII)

note

Uses mb_check_encoding() for reliable detection. If you want to detect only printable ASCII, use Strings::isPrintable() in combination with this method.

isBlank()

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

Parameters

$str : string

The input string to check.

Tags

example

Strings::isBlank("");           // true
Strings::isBlank("    ");       // true
Strings::isBlank("\n\t\r");     // true
Strings::isBlank("hello");      // false

isEmail()

Validates whether a given string is a well-formed email address.

Parameters

$str : string

The input string to validate as an email address.

Tags

example

Strings::isEmail('user@example.com');    // true
Strings::isEmail('bad-email@');          // false
Strings::isEmail('user@localhost');      // false (fails under strict RFC rules)
Strings::isEmail('user.name+tag@domain.com'); // true

edgecase

Some technically valid but rare email formats may fail (e.g., Unicode domains, quoted local-parts), depending on PHP version and filter_var() implementation.

note

This validation checks basic syntax only. It does not verify whether the domain exists or whether the email address is deliverable.

isHex()

Determines whether a string is a valid hexadecimal number.

Parameters

$str : string

The string to evaluate.

$allowPrefix : bool = false

Whether to allow an optional '0x' or '0X' prefix. Default is false.

Tags

example

Strings::isHex('deadBEEF');           // true
Strings::isHex('0x123abc');           // false
Strings::isHex('0x123abc', true);     // true
Strings::isHex('g123');               // false
Strings::isHex('');                   // false

isJson()

Determines whether a given string is valid JSON.

Parameters

$str : string

The string to test for JSON validity.

Tags

example

Strings::isJson('{"key":"value"}');      // true
Strings::isJson('[1, 2, 3]');             // true
Strings::isJson('"Just a string"');      // true
Strings::isJson('null');                 // true
Strings::isJson('not json');             // false

edgecase

This function will return true for valid JSON values like "true", "42", or "null", which may not be what some callers expect if they're only checking for objects or arrays.

note

This does not check the type of JSON structure — only that the input is syntactically valid. To ensure the decoded result is an array or object, you must additionally inspect the result of json_decode().

isLetters()

Determines if a string contains only Unicode letters (from any language).

Parameters

$str : string

The input string to evaluate.

Tags

example

Strings::isLetters('abc');           // true
Strings::isLetters('CrèmeBrûlée');   // true
Strings::isLetters('Москва');        // true
Strings::isLetters('hello123');      // false
Strings::isLetters('naïve!');        // false (contains punctuation)

note

Blank strings will return false. Matching is Unicode-aware and multibyte-safe.

isLettersOrDigits()

Determines if a string contains only Unicode letters or digits.

Parameters

$str : string

The string to evaluate.

Tags

example

Strings::isLettersOrDigits('abc123');      // true
Strings::isLettersOrDigits('Crème123');    // true
Strings::isLettersOrDigits('Москва2024');  // true
Strings::isLettersOrDigits('abc!123');     // false (contains punctuation)

note

This method is multibyte-aware and supports full Unicode. An empty string will return false.

isLower()

Checks whether all characters in the string are lowercase.

Parameters

$str : string

The input string to evaluate.

Tags

example

Strings::isLower('hello');         // true
Strings::isLower('HELLO');         // false
Strings::isLower('Crème');         // false (C is uppercase)
Strings::isLower('straße');        // true (ß is lowercase)

note

This method is multibyte-safe. Returns false for empty strings.

isNumericString()

Determines if a string is a valid numeric value (int or float).

Parameters

$str : string

The input string to test.

Tags

example

Strings::isNumericString('123');      // true
Strings::isNumericString('-12.5e3');  // true
Strings::isNumericString('123abc');   // false

isPrintable()

Checks if a string contains only printable characters.

Parameters

$str : string

The input string to evaluate.

Tags

example

Strings::isPrintable('hello');              // true
Strings::isPrintable("hello\nworld");       // false
Strings::isPrintable('🚀 Launch!');          // true
Strings::isPrintable("abc\x00def");         // false (contains null byte)

note

This is Unicode-aware and multibyte-safe. It does not filter whitespace like spaces or tabs, only non-printable control characters (General Category: C* in Unicode).

isSentenceLike()

Determines if a string resembles a sentence (starts with uppercase and ends with punctuation).

Parameters

$str : string

The string to evaluate.

Tags

example

Strings::isSentenceLike('Hello world.');   // true
Strings::isSentenceLike('hello world');    // false

isStrictTitleCase()

Determines if a string is strictly title case: each word starts with a single uppercase letter, followed only by lowercase letters — excluding all-uppercase acronyms like 'NASA' or 'HTTP'.

Parameters

$str : string

The input string to evaluate.

Tags

example

Strings::isStrictTitleCase('The Quick Brown Fox');   // true
Strings::isStrictTitleCase('NASA Launch Site');      // false
Strings::isStrictTitleCase('The NASA Space Center'); // false

note

This method is multibyte-safe and Unicode-aware. Words are split on whitespace.

isTitleCase()

Determines if a string is in title case (each word starts with an uppercase letter, followed by lowercase).

Parameters

$str : string

The string to check.

Tags

example

Strings::isTitleCase('The Quick Brown Fox');    // true
Strings::isTitleCase('the Quick Brown Fox');    // false
Strings::isTitleCase('Das Ist Gut');            // true

note

This method is Unicode-aware and multibyte-safe. Words are split on whitespace.

isUpper()

Checks whether all characters in the string are uppercase.

Parameters

$str : string

The input string to evaluate.

Tags

example

Strings::isUpper('HELLO');         // true
Strings::isUpper('hello');         // false
Strings::isUpper('CRÈME');         // true
Strings::isUpper('München');       // false (ü is lowercase)

note

This method is multibyte-safe and works with accented/Unicode characters. Returns false for empty strings.

isUrl()

Validates whether a given string is a well-formed URL.

Parameters

$str : string

The input string to validate as a URL.

Tags

example

Strings::isUrl('https://example.com');         // true
Strings::isUrl('http://localhost:8000/test');  // true
Strings::isUrl('ftp://example.com/resource');  // true
Strings::isUrl('www.example.com');             // false (missing scheme)

edgecase

URLs without a scheme (like www.example.com) will fail, even though browsers accept them. URLs with uncommon schemes or IP addresses may be flagged as invalid depending on the environment.

note

This method only checks the syntactic validity of the URL — it does not confirm that the domain exists or that the URL is reachable.

isUuid()

Validates whether a given string is a well-formed UUID (version 1 through 5).

Parameters

$str : string

The string to validate as a UUID.

Tags

example

Strings::isUuid('550e8400-e29b-41d4-a716-446655440000'); // true
Strings::isUuid('not-a-uuid');                           // false
Strings::isUuid('123e4567-e89b-12d3-a456-426614174000'); // true

edgecase

This validator only accepts UUIDs with hyphens and lowercase/uppercase hex characters. It will reject nil UUIDs (00000000-0000-0000-0000-000000000000) if version or variant bits don't conform.

note

This checks only the format and version compliance — it does not guarantee the UUID was generated correctly or is unique. Adjust the regex if you need to accept other UUID variants (e.g., version 0 or nil UUIDs).

isValidBase64()

Checks whether a string is a valid base64-encoded string.

Parameters

$str : string

The input string to check.

Tags

example

Strings::isValidBase64('aGVsbG8=');      // true
Strings::isValidBase64('hello');         // false

kebabCase()

Converts a string into kebab-case format.

Parameters

$str : string

The input string to convert. May contain spaces, punctuation, or symbols.

Tags

example

Strings::kebabCase('Hello World!');           // 'hello-world'
Strings::kebabCase('already-kebab-case');     // 'already-kebab-case'
Strings::kebabCase('Multiple---delimiters');  // 'multiple-delimiters'
Strings::kebabCase('Ünicode & Symbols ™️');   // 'ünicode-symbols'

edgecase

If the input contains only symbols or whitespace, the result may be an empty string. Consecutive non-word characters are collapsed into a single hyphen.

note

This function is Unicode-aware via \p{L} (letters) and \p{N} (numbers), and uses the u modifier for proper multibyte string handling.

length()

Returns the number of characters in a string, using multibyte-safe logic.

Parameters

$str : string

The input string to measure.

Tags

example

Strings::length('Hello');          // 5
Strings::length('💡 Idea!');       // 7
Strings::length('naïve');          // 5

edgecase

If the input string is empty, the result will be 0.

note

This method depends on the mbstring extension. If it's not available, mb_strlen() may cause a fatal error or return incorrect results.

limitChars()

Truncates a string to a maximum number of characters, optionally avoiding mid-word breaks.

Parameters

$str : string

The input string.

$maxChars : int

Maximum total characters, including ellipsis.

$ellipsis : string = '…'

String to append after truncation. Default is '…'.

$preserveWords : bool = false

If true, avoid breaking words in the middle.

Tags

example

Strings::limitChars("Hello world, how are you?", 10);                  // "Hello w…"
Strings::limitChars("Hello world, how are you?", 10, '…', true);       // "Hello…"
Strings::limitChars("Short", 10);                                      // "Short"

limitHtmlSafeChars()

Truncates a string containing HTML to a maximum number of visible characters.

Parameters

$html : string

The HTML string.

$maxChars : int

Max visible characters, including ellipsis.

$ellipsis : string = '…'

What to append if truncated. Default is '…'.

$preserveWords : bool = false

Whether to avoid cutting mid-word.

Tags

example

Strings::limitHtmlSafeChars('<b>Hello</b> world!', 8); // "<b>Hello</b> w…"

limitWords()

Truncates a string after a specified number of words and appends an ellipsis (or other trailing marker).

Parameters

$str : string

The input string to process.

$maxWords : int

The maximum number of words to retain.

$ellipsis : string = '…'

The string to append if truncation occurs. Defaults to a Unicode ellipsis (…).

Tags

example

Strings::limitWords('The quick brown fox jumps over the lazy dog', 4);      // 'The quick brown fox…'
Strings::limitWords('Short sentence.', 5);                                   // 'Short sentence.'
Strings::limitWords('One two three four five', 3, '...');                    // 'One two three...'

edgecase

If $maxWords is zero or negative, the result will be just the ellipsis. If the input string is empty or contains only whitespace, it returns an empty string.

note

Words are determined using preg_split('/\s+/'), so any sequence of whitespace is considered a separator. This method does not account for punctuation or HTML tags when splitting words.

loadCleanWordList()

Loads and filters a clean word list from a file like /usr/share/dict/words, with static caching.

Parameters

$path : string = '/usr/share/dict/words'

Path to the wordlist file. Defaults to /usr/share/dict/words.

$minLen : int = 3

Minimum word length to include. Defaults to 3.

$maxLen : int = 12

Maximum word length to include. Defaults to 12.

Tags

throws

RuntimeException

If the file is missing or unreadable.

mask()

Masks all but the last few characters of a string using a specified mask character.

Parameters

$str : string

The input string to mask.

$visible : int = 4

The number of characters to leave visible at the end of the string. Defaults to 4.

$maskChar : string = '*'

The character to use for masking. Defaults to '*'.

Tags

example

Strings::mask('123456789', 4);       // '*****6789'
Strings::mask('secret', 2, '#');     // '####et'
Strings::mask('short', 10);          // '*****' (input too short to preserve visibility)

edgecase

If $visible is greater than or equal to the length of $str, the entire string will be masked. If $maskChar is an empty string, str_repeat() will emit a warning and return false.

note

This method uses mb_strlen() and mb_substr() to ensure multibyte safety. Always validate $maskChar to avoid unexpected behavior when empty.

matchesPattern()

Determines whether a string matches a given regular expression pattern.

Parameters

$str : string

The input string to evaluate.

$pattern : string

A valid regular expression pattern, including delimiters (e.g., '/^abc/i').

Tags

example

Strings::matchesPattern('hello123', '/\d+/');     // true
Strings::matchesPattern('abc', '/^a/');           // true
Strings::matchesPattern('test', '/\d+/');         // false
Strings::matchesPattern('Test', '/test/i');       // true (case-insensitive)

edgecase

If the pattern is invalid (e.g., bad syntax or delimiters), preg_match() will return false and may trigger a warning or error depending on error reporting settings.

note

Always validate or escape user-supplied patterns before using them, to avoid security issues or unintended behavior. Patterns must include valid delimiters and optional flags.

normalize_newlines_to_crlf()

Normalizes all newline characters in a string to CRLF (`\r\n`) format.

Parameters

$input : string

The input string that may contain mixed or inconsistent newline characters.

Tags

example

Strings::normalize_newlines_to_crlf("Line 1\rLine 2\nLine 3\r\n");
// "Line 1\r\nLine 2\r\nLine 3\r\n"

edgecase

Any existing \r\n sequences will be preserved correctly after transformation. Lone \r or \n sequences will be safely converted into consistent \r\n.

note

This method is useful when preparing files for Windows environments, email headers, or protocols where CRLF is the required newline format.

normalizeHex()

Normalizes a hexadecimal string by removing the optional "0x"/"0X" prefix and optionally converting to lowercase or uppercase.

Parameters

$hex : string

The input hex string (with or without prefix).

$toUpper : bool = false

Whether to convert the result to uppercase. Default is false (lowercase).

Tags

example

Strings::normalizeHex('0xDEADBEEF');    // 'deadbeef'
Strings::normalizeHex('abc123');        // 'abc123'
Strings::normalizeHex('0xABC123', true); // 'ABC123'

note

Does not validate the input. Use Strings::isHex() first if needed.

normalizeWhitespace()

Normalizes all whitespace in a string to single spaces and trims the result.

Parameters

$str : string

The input string to normalize.

Tags

example

Strings::normalizeWhitespace("  This\t is\n\nmessy   text. ");  // 'This is messy text.'
Strings::normalizeWhitespace("Line 1\nLine 2\r\nLine 3");       // 'Line 1 Line 2 Line 3'

edgecase

If the input string contains only whitespace, the result will be an empty string. Unicode whitespace (e.g., non-breaking space \u00A0) is treated as whitespace due to the \s pattern and u modifier.

note

The regular expression uses the u (Unicode) modifier for multibyte safety. This function is ideal for sanitizing user input or normalizing content before display or storage.

obfuscateCreditCard()

Obfuscates a credit card number by masking all but the first and last 4 digits.

Parameters

$creditCard : string

The raw credit card number input.

$grouped : bool = false

Whether to format the result with grouped blocks (e.g., 4111 **** **** 1111). Defaults to false.

$maskChar : string = '*'

Tags

example

Strings::obfuscateCreditCard('4111 1111 1111 1111');          // '4111********1111'
Strings::obfuscateCreditCard('4111-1111-1111-1111', true);    // '4111 **** **** 1111'

note

The method does not perform any credit card validation (Luhn, issuer, etc.). Input should contain at least 8 digits to produce a meaningful result.

obfuscateEmail()

Obfuscates an email address by masking the username portion with asterisks.

Parameters

$email : string

The full email address to obfuscate.

Tags

example

Strings::obfuscateEmail('john.doe@example.com');    // 'j******e@example.com'
Strings::obfuscateEmail('a@b.com');                 // 'a@b.com'
Strings::obfuscateEmail('xy@domain.com');           // 'x*y@domain.com'

note

This method assumes a valid email with a single '@'. Invalid input may cause errors or incorrect formatting.

obfuscateMiddle()

Obfuscates the middle portion of a string, preserving the beginning and end.

Parameters

$input : string

The string to obfuscate (API key, token, etc.).

$visibleStart : int = 3

Number of visible characters at the beginning.

$visibleEnd : int = 4

Number of visible characters at the end.

$maskChar : string = '*'

Masking character to use. Defaults to '*'.

Tags

example

Strings::obfuscateMiddle('sk_test_abc1234567890xyz', 7, 4);  // 'sk_test****************xyz'
Strings::obfuscateMiddle('abc123', 2, 2);                    // 'ab**23'

obfuscatePhoneNumber()

Obfuscates a phone number by masking the middle digits with asterisks.

Parameters

$phoneNumber : string

The input phone number (may contain spaces, dashes, etc.).

Tags

example

Strings::obfuscatePhoneNumber('123-456-7890');    // '123***7890'
Strings::obfuscatePhoneNumber('(800) 555-1212');  // '800*****1212'

note

This assumes U.S.-style phone numbers with at least 7 digits. If fewer than 7 digits, the result may expose more or all digits.

obfuscatePostalCode()

Obfuscates a postal code by masking the middle digits with asterisks.

Parameters

$postalCode : string

The postal code (ZIP, ZIP+4, etc.) to obfuscate.

Tags

example

Strings::obfuscatePostalCode('78701');           // '787*1'
Strings::obfuscatePostalCode('78701-0423');      // '787****0423'

note

This assumes U.S.-style ZIP or ZIP+4 formats. Input with fewer than 5 digits may not be obfuscated meaningfully. If the input has fewer than 4 trailing digits, the ending portion will be as long as possible.

onlyAlpha()

Removes all non-alphabetic characters from the input string.

Parameters

$str : string

The input string to sanitize.

Tags

example

Strings::onlyAlpha('abc123!@#');      // 'abc'
Strings::onlyAlpha('Circle-6 Mail');  // 'CircleMail'
Strings::onlyAlpha('42');             // ''

note

This does not support accented or Unicode letters. Use a Unicode-aware version (e.g., \p{L}) if working with non-ASCII alphabets.

onlyLetters()

Removes all non-letter characters from the input string, including digits and symbols.

Parameters

$str : string

The input string to filter.

Tags

example

Strings::onlyLetters('abc123');         // 'abc'
Strings::onlyLetters('Crème brûlée!');  // 'Crèmebrûlée'
Strings::onlyLetters('Москва 2024');    // 'Москва'

note

Uses Unicode \p{L} character class to match any kind of letter. Requires the u (UTF-8) modifier to work properly with multibyte characters.

ordinal()

Converts an integer into its ordinal string representation (e.g., 1 → "1st", 2 → "2nd").

Parameters

$number : int

The integer to convert.

Tags

example

Strings::ordinal(1);   // '1st'
Strings::ordinal(2);   // '2nd'
Strings::ordinal(3);   // '3rd'
Strings::ordinal(4);   // '4th'
Strings::ordinal(11);  // '11th'
Strings::ordinal(22);  // '22nd'
Strings::ordinal(113); // '113th'

edgecase

Numbers ending in 11, 12, or 13 always return 'th' due to English ordinal rules, even though they end in 1, 2, or 3 (e.g., 111 → '111th', not '111st').

note

This method assumes input is a non-negative integer. Negative numbers will still return a valid string with the correct suffix, but the format (e.g., -1st) may not be meaningful in all contexts.

outdent()

Removes a fixed number of leading characters (indentation) from each line.

Parameters

$str : string

The multiline string to outdent.

$count : int = 4

Number of leading characters to remove per line. Default is 4.

$char : string = ' '

The character to remove. Default is space.

Tags

example

Strings::outdent("    line 1\n    line 2");     // "line 1\nline 2"
Strings::outdent("--foo\n--bar", 2, '-');       // "foo\nbar"

note

This only removes characters if they match the specified character exactly. Mixed indentation (e.g. tabs + spaces) must be normalized first.

padLeft()

Pads a string on the left side to a specified total length using a given padding character.

Parameters

$str : string

The input string to pad.

$length : int

The total length of the resulting string after padding.

$char : string = ' '

The character to pad with. Must be a non-empty string. Defaults to a space ' '.

Tags

example

Strings::padLeft('42', 5);               // '   42'
Strings::padLeft('abc', 6, '0');         // '000abc'
Strings::padLeft('already long', 5);     // 'already long'

edgecase

If $char is an empty string, str_pad() will emit a warning and return false. Always ensure $char is a non-empty string.

note

Padding is repeated as needed to fill the gap. If the padding string is longer than one character, it will be truncated if it doesn’t divide evenly into the padding length.

padRight()

Pads a string on the right side to a specified total length using a given padding character.

Parameters

$str : string

The input string to pad.

$length : int

The total desired length of the resulting string after padding.

$char : string = ' '

The character to pad with. Must be a non-empty string. Defaults to a space ' '.

Tags

example

Strings::padRight('42', 5);               // '42   '
Strings::padRight('abc', 6, '.');         // 'abc...'
Strings::padRight('already long', 5);     // 'already long'

edgecase

If $char is an empty string, str_pad() will emit a warning and return false. Be sure to use a non-empty string for padding.

note

If the padding string is more than one character, it will repeat as needed and be truncated to fit the exact length.

randomSlugFromWordlist()

Generates a human-friendly random slug using two words and a number.

Parameters

$wordlist : array<string|int, mixed>|null = null

Optional preloaded word list. Loads from /usr/share/dict/words by default.

$numberRange : int = 100

Max numeric suffix. Defaults to 100.

$separator : string = '-'

Separator between slug parts (e.g., '-', '_', '.'). Defaults to '-'.

$prefix : string = ''

Optional prefix string to prepend. No separator automatically added.

$suffix : string = ''

Optional suffix string to append. No separator automatically added.

Tags

example

Strings::randomSlugFromWordlist();                            // 'silent-sunset-42'
Strings::randomSlugFromWordlist(null, 999, '_');              // 'wild_cloud_314'
Strings::randomSlugFromWordlist(null, 100, '-', 'inv-', '-qa'); // 'inv-bold-stone-91-qa'

throws

Exception

randomString()

Generates a cryptographically secure random string of a given length, optionally with a prefix.

Parameters

$length : int = 64

The total desired length of the output string, including prefix. Defaults to 64.

$prefix : string = ''

A string to prepend to the output. The remaining characters will be randomly generated.

$characterPool : string = 'ABCDEFGHJKMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789'

A string containing the characters to randomly choose from. Defaults to a URL-safe, unambiguous set (no 0, O, l, 1).

Tags

example

Strings::randomString(10);                       // e.g., 'a8B7jk3Mnp'
Strings::randomString(16, 'id_');                // e.g., 'id_7GkP8xLqJ93R'
Strings::randomString(5, '', 'ABC123');          // e.g., 'C1BA2'

edgecase

If $characterPool is empty or $length <= strlen($prefix), the method returns the prefix truncated or padded to the desired length.

note

This method uses PHP's random_int() and is cryptographically secure, making it suitable for tokens, nonces, session keys, or other security-sensitive purposes. However, it does not guarantee uniqueness. For universally unique identifiers, use a UUID generator.

throws

Exception

removeAccents()

Removes accents and diacritics from a UTF-8 string by converting to ASCII.

Parameters

$str : string

The input UTF-8 string.

Tags

example

Strings::removeAccents("Crème brûlée");     // "Creme brulee"
Strings::removeAccents("München");          // "Munchen"
Strings::removeAccents("façade");           // "facade"

note

This function removes all non-ASCII characters. Symbols like em-dashes (—) or smart quotes (“ ”) will be stripped.

removeDuplicateWords()

Removes consecutive duplicate words in a string.

Parameters

$str : string

The input string.

Tags

example

Strings::removeDuplicateWords('this this is is a test');  // 'this is a test'

removePrefix()

Removes the given prefix from the start of a string, if present.

Parameters

$str : string

The input string to process.

$prefix : string

The prefix to remove if found at the beginning.

Tags

example

Strings::removePrefix('unhappy', 'un');       // 'happy'
Strings::removePrefix('hello world', 'hi');   // 'hello world' (unchanged)
Strings::removePrefix('abc123', 'abc');       // '123'

note

Comparison is case-sensitive. Use strtolower() if case-insensitive behavior is needed.

removeSuffix()

Removes the given suffix from the end of a string, if present.

Parameters

$str : string

The input string to process.

$suffix : string

The suffix to remove if found at the end.

Tags

example

Strings::removeSuffix('filename.txt', '.txt');     // 'filename'
Strings::removeSuffix('report_final', '_final');   // 'report'
Strings::removeSuffix('document.PDF', '.pdf');     // 'document.PDF' (case-sensitive)

note

Comparison is case-sensitive. Use strtolower() or str_ends_with(strtolower(...)) if you need case-insensitive behavior.

repeat()

Repeats a string a specified number of times.

Parameters

$str : string

The string to repeat.

$times : int

The number of times to repeat the string. Should be a non-negative integer.

Tags

example

Strings::repeat('abc', 3);     // 'abcabcabc'
Strings::repeat('*', 5);       // '*****'
Strings::repeat('xyz', 0);     // ''

edgecase

If $times is negative, str_repeat() returns an empty string without error. If $str is an empty string, the result will always be an empty string, regardless of $times.

note

This function does not trim or insert separators between repetitions. If you want space- or delimiter-separated repetitions, use a loop or implode().

replaceFirstPartOfString()

Replaces the beginning of a string with a new prefix of the same length.

Parameters

$original : string

The original string whose beginning will be replaced.

$newFrontPiece : string

The string that will replace the first part of $original. Its full length is used.

Tags

example

Strings::replaceFirstPartOfString('username123', 'admin');   // 'adminme123'
Strings::replaceFirstPartOfString('abcdef', 'XY');           // 'XYcdef'

edgecase

If $newFrontPiece is longer than $original, the result will include all of $newFrontPiece, followed by an empty string from substr(). This may result in truncation or unexpected output. If $newFrontPiece is an empty string, the result is identical to $original.

note

This is a low-level utility that performs raw byte-length replacement (via strlen() and substr()), not multibyte-safe. If working with UTF-8 strings containing multibyte characters, consider using mb_strlen() and mb_substr() for accuracy.

reverse()

Reverses a string safely with full multibyte (UTF-8) support.

Parameters

$str : string

The input string to reverse.

Tags

example

Strings::reverse('hello');           // 'olleh'
Strings::reverse('áéíóú');           // 'úóíéá'
Strings::reverse('Доброе утро');     // 'орту еорбоД'
Strings::reverse('👩‍🚀💫🚀');           // '🚀💫👩‍🚀' (may break emoji clusters visually)

note

Uses mb_str_split() to correctly handle Unicode characters. Emoji or combining characters may not always render properly after reversal due to their complexity.

reverseLines()

Reverses the order of lines in a multiline string.

Parameters

$str : string

The input multiline string.

Tags

example

Strings::reverseLines("line 1\nline 2\nline 3");
// "line 3\nline 2\nline 1"

note

Handles LF (\n), CRLF (\r\n), and CR (\r) line endings. Output will use the same line endings as the input.

reverseWords()

Reverses the order of words in a string while preserving the words themselves.

Parameters

$str : string

The input string containing words.

Tags

example

Strings::reverseWords('The quick brown fox');   // 'fox brown quick The'
Strings::reverseWords('Привет мир');            // 'мир Привет'

note

Whitespace is normalized to single spaces in the output. Multibyte characters are fully supported. Punctuation stays attached to words (e.g., 'hello!' becomes 'hello!').

rot13()

Applies the ROT13 cipher to a string.

Parameters

$str : string

The input string.

Tags

example

Strings::rot13('Hello');  // 'Uryyb'
Strings::rot13('Uryyb');  // 'Hello'

safeHtml()

Escapes special characters in a string for safe output in HTML.

Parameters

$str : string

The raw input string to escape for HTML output.

Tags

example

Strings::safeHtml('<script>alert("XSS")</script>'); // '&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'
Strings::safeHtml("Tom & Jerry's \"Cat\"");         // 'Tom &amp; Jerry&#039;s &quot;Cat&quot;'

edgecase

If the string contains invalid UTF-8 sequences, ENT_SUBSTITUTE ensures they are replaced with a Unicode replacement character (�) rather than causing encoding errors or breaking output.

note

This method escapes both double and single quotes (ENT_QUOTES), making it safe for use in attribute values. Always use this (or similar escaping) when inserting untrusted content into HTML pages.

sanitizeFilename()

Sanitizes a string for use as a safe filename by replacing disallowed characters with underscores.

Parameters

$str : string

The input string to sanitize.

Tags

example

Strings::sanitizeFilename('My Report (Final).pdf');    // 'My_Report__Final_.pdf'
Strings::sanitizeFilename('user@domain.com');          // 'user_domain.com'
Strings::sanitizeFilename('file name*&^%.txt');        // 'file_name____.txt'

edgecase

If the input contains only disallowed characters, the result will be all underscores. This method does not collapse consecutive underscores or trim the result — it is literal.

note

This method does not check for reserved filenames (like CON, NUL, or COM1 on Windows), nor does it enforce length limits. Consider additional validation if targeting specific filesystems.

sanitizeHex()

Validates and normalizes a hexadecimal string.

Parameters

$hex : string

The input hex string to validate and sanitize.

$toUpper : bool = false

Whether to return the result in uppercase. Default is false (lowercase).

Tags

example

Strings::sanitizeHex('0xABC123');        // 'abc123'
Strings::sanitizeHex('ABC123', true);    // 'ABC123'
Strings::sanitizeHex('g123');            // null

note

This method combines isHex() and normalizeHex() with prefix support.

sentenceCount()

Counts the number of sentences in a string.

Parameters

$str : string

The input text.

Tags

example

Strings::sentenceCount('This is one. And another!');  // 2

shuffle()

Randomly shuffles the characters in a multibyte string.

Parameters

$str : string

The input string to shuffle.

Tags

example

Strings::shuffle('hello');        // might return 'lohel', 'elhol', etc.
Strings::shuffle('áéíóú');        // preserves multibyte characters correctly

note

This is not cryptographically secure. Do not use for password generation or security tokens. Multibyte-safe via mb_str_split().

signHmac()

Generates an HMAC signature for a payload using the given key and algorithm.

Parameters

$payload : string

The message to sign.

$key : string

The secret key.

$algo : string = 'sha256'

The hashing algorithm to use. Default is 'sha256'.

Tags

example

Strings::signHmac('data', 'secret');             // 'aabbcc...'
Strings::signHmac('payload', 'key', 'sha1');     // SHA1 HMAC

similarity()

Calculates the percentage similarity between two strings.

Parameters

$a : string

The first string to compare.

$b : string

The second string to compare.

Tags

example

Strings::similarity('apple', 'apples');      // 91.666...
Strings::similarity('hello', 'yellow');      // 60.0
Strings::similarity('cat', 'dog');           // 0.0

edgecase

An empty string compared with another string results in 0.0. Case differences are treated as mismatches — the comparison is case-sensitive.

note

This function uses a time-consuming algorithm for long strings, as similar_text() has O(N^3) complexity. For faster or fuzzy comparisons, consider levenshtein() or external string similarity libraries.

slugify()

Converts a string into a URL-friendly "slug" format.

Parameters

$str : string

The input string to convert into slug form.

Tags

example

Strings::slugify('Hello World!');        // 'hello-world'
Strings::slugify('PHP & MySQL Tips');    // 'php-mysql-tips'
Strings::slugify('  Leading/Trailing  '); // 'leading-trailing'

edgecase

If the input string is empty or contains no alphanumeric characters, the return value will be an empty string.

note

Only basic ASCII characters are handled. Accented characters (e.g., é, ñ) will be removed rather than converted. To support Unicode or transliteration, additional normalization steps (e.g., iconv(), transliterator_transliterate()) would be required.

slugToTitle()

Converts a slug-formatted string into a human-readable title case string.

Parameters

$slug : string

The slug string to convert. Typically lowercase, words separated by - or _.

Tags

example

Strings::slugToTitle('my-awesome-title');     // 'My Awesome Title'
Strings::slugToTitle('another_example_here'); // 'Another Example Here'
Strings::slugToTitle('mixed-separators_here'); // 'Mixed Separators Here'

edgecase

If the slug is an empty string, the result will also be an empty string. If the slug contains characters beyond alphanumerics, dashes, or underscores, they will remain in the result unless handled by titleCase().

note

This function depends on self::titleCase() for casing logic. If titleCase() has locale-specific behavior or Unicode quirks, those will affect the output of this method as well.

smartTitleCase()

Converts a string to title case while preserving acronyms and lowercasing stop words.

Parameters

$str : string

The input string to convert.

$acronyms : array<string|int, mixed> = ['ID', 'HTML', 'CSS', 'PHP', 'NASA', 'API', 'URL', 'JSON']

Acronyms to preserve in uppercase. Default includes common technical acronyms.

$stopWords : array<string|int, mixed> = ['and', 'or', 'but', 'for', 'nor', 'a', 'an', 'the', 'in', 'on', 'at', 'to', 'by', 'of', 'with']

Stop words to keep lowercase unless at the start. Default includes common English stop words.

Tags

example

Strings::smartTitleCase('introduction to php and html');
// 'Introduction to PHP and HTML'

Strings::smartTitleCase('the future of ai in nasa');
// 'The Future of AI in NASA'

snake_case()

Converts a string into snake_case format.

Parameters

$str : string

The input string to convert. Can contain spaces, punctuation, symbols, etc.

Tags

example

Strings::snake_case('Hello World!');           // 'hello_world'
Strings::snake_case('already_snake_case');     // 'already_snake_case'
Strings::snake_case('Multiple---delimiters');  // 'multiple_delimiters'
Strings::snake_case('Ünicode & Symbols ™️');   // 'ünicode_symbols'

edgecase

Input with only non-alphanumeric characters (e.g., '!!!') will result in an empty string after trimming. Multiple adjacent non-word characters are collapsed into a single underscore.

note

This function uses Unicode character classes (\p{L} for letters, \p{N} for numbers) and requires the u modifier to properly handle multibyte input. If the mbstring or pcre extension is misconfigured or missing, results may be unreliable.

startsWith()

Checks whether a string starts with a given substring.

Parameters

$haystack : string

The full string to evaluate.

$needle : string

The substring to check for at the start of $haystack.

Tags

example

Strings::startsWith('hello world', 'hello'); // true
Strings::startsWith('hello world', 'Hello'); // false (case-sensitive)
Strings::startsWith('abc', '');              // true (empty needle)

edgecase

If $needle is an empty string, the function will return true regardless of $haystack. This may be unintuitive but is consistent with how prefix checks are typically defined.

note

This function is case-sensitive. If you need case-insensitive behavior, consider converting both strings to lowercase before comparison (e.g., using strtolower()).

startsWithAny()

Checks whether the given string starts with any of the specified prefixes.

Parameters

$haystack : string

The string to check.

$prefixes : array<string|int, mixed>

An array of string prefixes to test against.

Tags

example

Strings::startsWithAny('circle6maildrop.com', ['https://', 'circle']);     // true
Strings::startsWithAny('example.txt', ['test', 'demo']);                   // false

note

Comparison is case-sensitive. Use strtolower() on both haystack and prefixes if you need case-insensitive behavior.

strip()

Removes all occurrences of the specified characters from a string.

Parameters

$str : string

The input string to clean.

$chars : array<string|int, mixed>

An array of characters or substrings to remove from the input.

Tags

example

Strings::strip('hello world', ['l', ' ']);     // 'heoworld'
Strings::strip('(123) 456-7890', ['(', ')', '-', ' ']); // '1234567890'
Strings::strip('abcXYZ123', ['a', '1', 'Z']);  // 'bcXY23'

edgecase

If $chars is an empty array, the input string is returned unchanged. If any of the values in $chars are longer substrings (e.g., 'abc'), entire matches will be removed.

note

This function performs exact, case-sensitive replacements. If you need case-insensitive stripping, consider normalizing the input and $chars array to lowercase or using str_ireplace().

stripDiacritics()

Removes diacritical marks (accents) from characters while preserving the base letter.

Parameters

$str : string

The input string.

Tags

example

Strings::stripDiacritics("Crème brûlée");  // 'Creme brulee'

stripHtmlButAllow()

Strips all HTML tags from a string except those explicitly allowed.

Parameters

$str : string

The input string potentially containing HTML.

$allowedTags : string = '<b><i><br>'

A string of allowed tags in angle brackets (e.g., '<b><i><br>'). Tags must be lowercase and well-formed to be preserved.

Tags

example

Strings::stripHtmlButAllow('<b>Hello</b> <script>bad()</script>', '<b>'); // '<b>Hello</b> bad()'
Strings::stripHtmlButAllow('<i>Italic</i><br><u>Underlined</u>', '<i><br>'); // '<i>Italic</i><br>Underlined'
Strings::stripHtmlButAllow('No HTML at all'); // 'No HTML at all'

edgecase

The $allowedTags string must use lowercase tag names — uppercase versions will not match and will be stripped. Any tag not listed exactly (e.g., <BR> or <i class="foo">) will be stripped, even if visually similar.

note

This method does not validate or close malformed HTML. It simply removes disallowed tags without restructuring the DOM. For stricter or more sophisticated HTML filtering, consider using a dedicated HTML purifier library.

stripNonPrintable()

Removes all non-printable (control) characters from a string.

Parameters

$str : string

The input string to sanitize.

Tags

example

Strings::stripNonPrintable("abc\x00\x1Fdef");   // 'abcdef'
Strings::stripNonPrintable("Hello\nWorld");     // 'HelloWorld'
Strings::stripNonPrintable("🚀 Launch!");        // '🚀 Launch!' (unchanged)

note

This method is Unicode-aware and multibyte-safe. Whitespace such as spaces and tabs are preserved.

stripPunctuation()

Removes all punctuation characters from a string, preserving letters, numbers, and whitespace.

Parameters

$str : string

The input string.

Tags

example

Strings::stripPunctuation("Hello, world!");  // 'Hello world'

titleCase()

Converts a string to title case using multibyte-safe logic.

Parameters

$str : string

The input string to convert to title case.

Tags

example

Strings::titleCase('hello world');        // 'Hello World'
Strings::titleCase('mULTIbYTE çharacters'); // 'Multibyte Çharacters'
Strings::titleCase('123 go!');            // '123 Go!'

edgecase

Words that start with non-letter characters (e.g., numbers or punctuation) will remain unchanged at the beginning, and only subsequent alphabetic characters will be affected.

note

This function uses mb_convert_case() with 'UTF-8' encoding and requires the mbstring extension. It lowercases the rest of each word — so acronyms or intentional capitalization (e.g., “iPhone”) may be normalized.

toAscii()

Converts a UTF-8 string to an ASCII-only representation by transliterating accented and special characters.

Parameters

$str : string

The UTF-8 encoded input string to convert.

Tags

example

Strings::toAscii('Jalapeño');     // 'Jalapeno'
Strings::toAscii('français');     // 'francais'
Strings::toAscii('naïve café');   // 'naive cafe'

edgecase

Characters that cannot be represented in ASCII and are not translatable will be silently discarded. If the input string is already ASCII, the result will be identical.

note

This function depends on the iconv extension. If iconv() is not available or fails, it may return false or an empty string, depending on the PHP environment. Also, behavior of transliteration may vary slightly across systems or locales.

toAsciiSafe()

Converts a string to ASCII by transliterating or removing non-ASCII characters.

Parameters

$str : string

The input string to sanitize.

$replacement : string = ''

Optional string to insert in place of untranslatable characters. Default is empty string.

Tags

example

Strings::toAsciiSafe('Café');              // 'Cafe'
Strings::toAsciiSafe('Grüße aus München'); // 'Grusse aus Munchen'
Strings::toAsciiSafe('👋🌍');               // '' (emoji are removed)

note

iconv() may behave differently across platforms. Remaining non-ASCII characters are stripped using a regex cleanup.

toCamelCase()

Converts a string to camelCase.

Parameters

$str : string

The input string.

Tags

example

Strings::toCamelCase('user name');      // 'userName'
Strings::toCamelCase('hello_world');    // 'helloWorld'

toggleCase()

Toggles the case of each character in a string.

Parameters

$str : string

The input string to toggle.

Tags

example

Strings::toggleCase('Hello World');   // 'hELLO wORLD'
Strings::toggleCase('123abcABC');     // '123ABCabc'
Strings::toggleCase('!@#');           // '!@#' (unchanged)

edgecase

Multibyte characters (e.g., accented or non-Latin characters) are not supported correctly, since str_split() and ctype_upper() operate on single bytes. Characters like é or ß may be split incorrectly or ignored.

note

This function is not multibyte safe. For Unicode-safe case toggling, a more robust approach using mb_* functions and normalization would be needed.

toKebabCase()

Converts a string to kebab-case.

Parameters

$str : string

The input string.

Tags

example

Strings::toKebabCase('HelloWorld');     // 'hello-world'
Strings::toKebabCase('user_name');      // 'user-name'

toSlugId()

Converts a string to a slug and appends an identifier, forming a slug-ID composite string.

Parameters

$str : string

The input string to convert into a slug.

$id : int|string

The identifier to append. Typically a numeric ID, but any scalar value can be used.

Tags

example

Strings::toSlugId('Hello World', 42);         // 'hello-world-42'
Strings::toSlugId('Ünicode Title', 'abc123'); // 'unicode-title-abc123'

edgecase

If $str results in an empty slug (e.g., if it only contains symbols), the result will be -$id. If $id is not scalar, it will be coerced to string, which may produce unintended output (e.g., 'Array' or 'Object').

note

This method relies on self::slugify(), which removes special characters and collapses whitespace. Be sure to validate or sanitize $id if used in URLs or filenames.

toSnakeCase()

Converts a string to snake_case.

Parameters

$str : string

The input string.

Tags

example

Strings::toSnakeCase('HelloWorld');     // 'hello_world'
Strings::toSnakeCase('user name');      // 'user_name'

toTitleCase()

Converts a string to title case, capitalizing the first letter of each word.

Parameters

$str : string

The input string to convert.

Tags

example

Strings::toTitleCase('the quick brown fox');     // 'The Quick Brown Fox'
Strings::toTitleCase('grüße aus münchen');       // 'Grüße Aus München'

truncate()

Truncates a string to a specified length and appends an ellipsis (or other trailing marker).

Parameters

$string : string

The input string to truncate.

$length : int

The maximum length of the returned string, including the ellipsis. Must be at least as long as the ellipsis itself.

$ellipsis : string = '…'

The string to append to the end of truncated text. Defaults to a single Unicode ellipsis character (…).

Tags

example

Strings::truncate('This is a long sentence.', 10);           // 'This is a…'
Strings::truncate('Short text', 20);                         // 'Short text'
Strings::truncate('Multibyte 💡 text here', 15);             // 'Multibyte 💡…'
Strings::truncate('Cut mid-word test', 7, '...');            // 'Cut...'

edgecase

If $length is less than or equal to the length of $ellipsis, the function may return just a portion of the ellipsis or an empty string. This can lead to unexpected results. Example: truncate('test', 2, '...') returns '.'.

note

This method uses mb_strlen() and mb_substr() for proper multibyte (e.g., UTF-8) character handling. If your environment lacks the mbstring extension, it may produce incorrect behavior.

ulid()

Generates a ULID (Universally Unique Lexicographically Sortable Identifier).

Parameters

$uppercase : bool = true

Whether to return the ULID in uppercase (default) or lowercase.

Tags

example

Strings::ulid();                              // e.g., '01HZX7RCEJMBFZZC1P4EW6Q7NH'
Strings::ulid(1700000000000);                 // ULID with a fixed timestamp
Strings::ulid(null, false);                   // Lowercase ULID using current timestamp
Strings::ulid(1700000000000, false);          // '01hzb5xq4rg23ndgjtw4ht9q4f'

throws

Exception

ulidTimestamp()

Extracts the timestamp (in milliseconds since Unix epoch) from a ULID string.

Parameters

$ulid : string

A valid 26-character ULID string.

Tags

throws

InvalidArgumentException

If the input is not a valid ULID.

example

$ulid = Strings::ulid(1700000000000);
$ms = Strings::ulidTimestamp($ulid); // 1700000000000

ulidTimestampToDateTime()

Extracts the timestamp from a ULID and returns it as a DateTimeImmutable object.

Parameters

$ulid : string

A valid 26-character ULID.

Tags

throws

InvalidArgumentException

If the ULID is not valid.

throws

Exception

example

$ulid = Strings::ulid(); // e.g., '01HZX7RCEJMBFZZC1P4EW6Q7NH'
$dt = Strings::ulidTimestampToDateTime($ulid);
echo $dt->format('Y-m-d H:i:s'); // e.g., "2023-11-14 21:33:20"

uuid()

Generates a RFC 4122–compliant UUID (version 4), with optional casing.

Parameters

$uppercase : bool = true

If true (default), returns UUID in uppercase. If false, returns lowercase.

Tags

example

Strings::uuid();              // '3F6C0A7E-9F57-42DB-9A73-91F3A984D317'
Strings::uuid(false);         // '3f6c0a7e-9f57-42db-9a73-91f3a984d317'

throws

Exception

uuidv7()

Generates a UUID version 7 (time-ordered + random) based on the draft UUIDv7 spec.

Parameters

$uppercase : bool = true

Whether to return the UUID in uppercase. Defaults to true.

Tags

example

Strings::uuidv7();        // '017F22E2-79B0-7CC3-98C4-DC0C0C07398F'
Strings::uuidv7(false);   // '017f22e2-79b0-7cc3-98c4-dc0c0c07398f'

throws

Exception

verifyHmacSignature()

Verifies an HMAC signature against a message and secret key using a constant-time comparison.

Parameters

$payload : string

The raw message or data (e.g., webhook body).

$signature : string

The HMAC signature to verify (hex or base64).

$secret : string

The shared secret key used to generate the original signature.

$algo : string = 'sha256'

Hashing algorithm to use (e.g. 'sha256', 'sha1'). Default is 'sha256'.

$isBase64 : bool = false

Whether the signature is base64-encoded instead of hex.

Tags

example

// Verifying a GitHub-style HMAC signature:
Strings::verifyHmacSignature($json, $_SERVER['HTTP_X_HUB_SIGNATURE_256'], $secret, 'sha256');

verifyTwilioSignature()

Verifies a Twilio webhook signature.

Parameters

$url : string

The full request URL (no query string).

$params : array<string|int, mixed>

The POST parameters (from $_POST).

$signature : string

The value of X-Twilio-Signature header.

$authToken : string

Your Twilio auth token.

Tags

example

Strings::verifyTwilioSignature(
    'https://example.com/handler',
    $_POST,
    $_SERVER['HTTP_X_TWILIO_SIGNATURE'],
    getenv('TWILIO_AUTH_TOKEN')
);

wordCount()

Counts the number of words in a string, ignoring any HTML tags.

Parameters

$str : string

The input string to analyze. Can include HTML.

Tags

example

Strings::wordCount('Hello world!');                       // 2
Strings::wordCount('<p>Hello <strong>world</strong></p>'); // 2
Strings::wordCount('Él vive en México.');                 // 4 (may vary if multibyte-aware logic is needed)

edgecase

str_word_count() may undercount or skip words that contain accented characters, emojis, or characters outside the basic ASCII range unless locale settings are adjusted. HTML entities like & are preserved and may count as words depending on context.

note

This method is not multibyte-aware and may give inaccurate results for non-English or non-ASCII content. For full Unicode-aware word counting, consider using preg_match_all() with a Unicode word boundary regex.

wordWrapHtmlSafe()

Wraps long text inside HTML content without breaking tags.

Parameters

$str : string

The HTML-containing string to wrap.

$width : int = 75

The maximum line width before inserting a break. Defaults to 75 characters.

$break : string = " "

The string to insert as the break. Defaults to a newline character ("\n").

Tags

example

Strings::wordWrapHtmlSafe('<p>This is a very long sentence that needs to wrap properly within HTML.</p>', 20);
// '<p>This is a very long\nsentence that needs to\nwrap properly within\nHTML.</p>'

edgecase

Only visible text between tags is affected. Content inside tags like <script> or <style> may not be handled as expected. Text inside attributes (e.g., title="...") is not affected or wrapped. If the HTML is malformed (e.g., unclosed tags), behavior may be unpredictable.

note

This function uses a regular expression to match content between > and <, so it assumes reasonably well-formed HTML. It's designed for basic formatting tasks — not for deeply nested or edge-case HTML.

wrap()

Wraps a string with a given prefix and suffix.

Parameters

$str : string

The input string to wrap.

$prefix : string

The string to prepend.

$suffix : string

The string to append.

Tags

example

Strings::wrap('value', '[', ']');         // '[value]'
Strings::wrap('text', '"', '"');          // '"text"'
Strings::wrap('hello', '<b>', '</b>');    // '<b>hello</b>'

edgecase

If $str is an empty string, only the prefix and suffix are returned (e.g., wrap('', '[', ']') → '[]'). If either $prefix or $suffix is empty, only the non-empty part is added.

note

This method does not escape or validate the input or wrappers — it's a raw string operation.