orryv/x-string

Immutable, fluent string manipulation toolkit for PHP.

v1.1.5 2025-11-14 03:01 UTC

Requires

• php: ^8.1
• paragonie/sodium_compat: ^2.4

Requires (Dev)

• phpunit/phpunit: ^10.5

Suggests

• ext-iconv: Used as a fallback for character encoding conversions.
• ext-intl: Enables Normalizer support for Unicode normalization.
• ext-mbstring: Improves multibyte string handling performance.
• ext-openssl: Required for AES-256-GCM encryption/decryption support.

MIT

README

XString is an immutable, fluent string manipulation toolkit for PHP. It exposes a single value object that keeps track of the underlying string, the logical length "mode" (bytes, codepoints, or graphemes), and the active encoding. Every operation returns a new instance so that strings can be safely composed without side effects.

TODO

• remove Regex where it doesn't make sense
• add Stringable where it makes sense
• html entity encode and decode methods:
  • encodeHtmlEntities()
  • decodeHtmlEntities()
• toInt(), toFloat(), toBool() methods, tobool translates 'true', 'yes', 'ok', ... and '1', '2', ... to true . And 'false', 'no', 'failed', ... and '0', '-1', ... to false.
• methods to safely make folfder/file names for various filesystems (windows, linux, macos):
  • toWindowsFileName() // Also escapes reserved names like CON, PRN, AUX, NUL, COM1, LPT1, etc. and . and ..
  • toWindowsFolderName()
  • toWindowsPath()
  • toUnixFileName()
  • toUnixFolderName()
  • toUnixPath()
  • toMacOSFileName()
  • toMacOSFolderName()
  • toMacOSPath()
  • toSafeFileName() // generic safe file name
  • toSafeFolderName() // generic safe folder name
  • toSafePath() // generic safe path

Requirements

• PHP 8.1 or higher.
• The library works without extensions, but it takes advantage of the following when they are available:
  • ext-mbstring for multibyte-safe string operations.
  • ext-intl (Normalizer + grapheme functions) for Unicode normalization.
  • ext-iconv as an additional encoding conversion fallback.
  • ext-openssl for AES-256-GCM encryption/decryption helpers.

Installation

composer require orryv/x-string

XString ships as a regular Composer library. All classes live in the Orryv or Orryv\\XString namespaces and are autoloaded through PSR-4.

Quick start

use Orryv\\XString;

$xstring = XString::new('  Grüß Gott!  ')
    ->trim()
    ->normalize()
    ->toAscii()
    ->toUpper();

echo (string) $xstring; // outputs "GRUSS GOTT!"

Instance methods can also be invoked statically by providing the initial value as the first argument. This is useful when you only need a single operation:

echo (string) XString::repeat('#', 3); // outputs "###"

The fluent API covers common text tasks: casing, normalization, substring operations, tokenisation, searching, replacing, cryptographic helpers, formatting, and more. Each operation honours the configured mode so you can work with multibyte characters and grapheme clusters reliably.

Documentation

Comprehensive documentation for every public method lives in the docs/ folder. Each markdown file describes behaviour, edge cases, and contains tested examples (prefixed with <!-- test:... -->) that are automatically converted into PHPUnit tests. Start with docs/examples/basic.md for an overview and use the per-method pages under docs/x-string/ for reference material.

Helper types such as Newline, Regex, and HtmlTag are documented in their respective subdirectories. The XStringType factory shortcuts mirror the "type" helpers described throughout the docs.

Testing

Run the full test suite (documentation examples + PHPUnit suites) with:

composer test

If you add or modify documentation examples, regenerate the corresponding tests with composer compose-docs-tests before running PHPUnit.

Contributing

Issues and pull requests are welcome. Please keep the API immutable, document new features in the docs/ folder, and include representative examples so that new behaviour is exercised by the generated tests.

License

The library is open-source software licensed under the MIT license.

API reference

The tables below are used to generate documentation-based tests. Each entry links to the detailed markdown page in the docs/ directory.

Method	Version	Signature & Description
new	1.0	public static function new(Newline|HtmlTag|Regex|Stringable|string|array<Newline|HtmlTag|Regex|Stringable|string> $data = ''): self Create a new instance of XString. You can provide a string, an array of strings, a Newline object, an HtmlTag object, or a Regex object. If an array is provided, it will be joined into a single string. If no data is provided, it defaults to an empty string.
withMode	1.0	public function withMode(string $mode = 'graphemes', string $encoding = 'UTF-8'): self Create a new instance of XString with the specified mode ('bytes', 'codepoints', or 'graphemes') and encoding (default 'UTF-8').
asBytes	1.0	public function asBytes(string $encoding = 'UTF-8'): self Alias for withMode('bytes', $encoding).
asCodepoints	1.0	public function asCodepoints(string $encoding = 'UTF-8'): self Alias for withMode('codepoints', $encoding).
asGraphemes	1.0	public function asGraphemes(string $encoding = 'UTF-8'): self Alias for withMode('graphemes', $encoding).

Generation

Will throw if internal string is not empty (new($data) with $data not empty.)

Method	Version	Signature & Description
rand	1.0	public static function rand(int $length, string $characters = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'): self Create a random string of a given length using the provided characters.
randInt	1.0	public static function randInt(int $length, int $int_min = 0, int $int_max = 9): self Create a random integer between the specified minimum and maximum values (inclusive).
randLower	1.0	public static function randLower(int $length, bool $include_numbers = false): self Create a random lowercase string of a given length. If $include_numbers is true, numbers will be included in the string.
randUpper	1.0	public static function randUpper(int $length, bool $include_numbers = false): self Create a random uppercase string of a given length. If $include_numbers is true, numbers will be included in the string.
randAlpha	1.0	public static function randAlpha(int $length): self Create a random alphabetic string of a given length (both uppercase and lowercase).
randHex	1.0	public static function randHex(int $length): self Create a random hexadecimal string of a given length.
randBase64	1.0	public static function randBase64(int $length): self Create a random Base64 string of a given length.
randBase62	1.0	public static function randBase62(int $length): self Create a random Base62 string of a given length.
uuid	1.0	public static function uuid(int $version = 4, ?string $namespace = null, ?string $name = null): self Create a UUID (Universally Unique Identifier) of the specified version (1, 3, 4, or 5). For v3/v5, $namespace and $name are required and validated.
implode	1.0	public static function implode(array<Newline|HtmlTag|Regex|Stringable|string> $data, string $glue = ''): self Join array elements into a single string with an optional glue string between elements.
join	1.0	public static function join(array<Newline|HtmlTag|Regex|Stringable|string> $data, string $glue = ''): self Alias for implode().
fromFile	1.0	public static function fromFile(string $file_path, null | int $length = null, null | int $offset = 0, string $encoding = 'UTF-8'): self Create a new instance of XString from the contents of a file. You can specify the length and offset to read from the file and the encoding label. Use withMode() afterwards if you need a different logical mode.

Manipulation

Method	Version	Signature & Description
append	1.0	public function append(Newline|HtmlTag|Regex|Stringable|string|array<Newline|HtmlTag|Regex|Stringable|string> $data): self Append a string to the end of the current string.
prepend	1.0	public function prepend(Newline|HtmlTag|Regex|Stringable|string|array<Newline|HtmlTag|Regex|Stringable|string> $data): self Prepend a string to the beginning of the current string.
toUpper	1.0	public function toUpper(): self Convert the string to upper case. (Alias: toUpperCase())
toUpperCase	1.0	public function toUpperCase(): self Alias for toUpper().
ucfirst	1.0	public function ucfirst(): self Convert the first character of the string to upper case.
lcfirst	1.0	public function lcfirst(): self Convert the first character of the string to lower case.
toLower	1.0	public function toLower(): self Convert the string to lower case. (Alias: toLowerCase())
toLowerCase	1.0	public function toLowerCase(): self Alias for toLower().
trim	1.0	public function trim($newline = true, $space = true, $tab = true): self Trim the string. By default it trims newlines, spaces and tabs. You can disable trimming of any of these by setting the relevant parameter to false.
ltrim	1.0	public function ltrim($newline = true, $space = true, $tab = true): self Left trim the string. By default it trims newlines, spaces and tabs. You can disable trimming of any of these by setting the relevant parameter to false.
rtrim	1.0	public function rtrim($newline = true, $space = true, $tab = true): self Right trim the string. By default it trims newlines, spaces and tabs. You can disable trimming of any of these by setting the relevant parameter to false.
replace	1.0	public function replace(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search, Newline|HtmlTag|Regex|string $replace, null|int $limit = null, $reversed = false): self Replace occurrences of a string with another string. By default it replaces all occurrences, but you can limit the number of replacements by setting the $limit parameter. If $reversed is true, it replaces from the end of the string.
replaceFirst	1.0	public function replaceFirst(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search, Newline|HtmlTag|Regex|string $replace): self Replace the first occurrence of a string with another string.
replaceLast	1.0	public function replaceLast(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search, Newline|HtmlTag|Regex|string $replace): self Replace the last occurrence of a string with another string.
substr	1.0	public function substr(int $start, null | int $length = null): self Get a substring of the string. If $length is not provided, it returns the substring from $start to the end of the string. (Default mode for indexing/length is graphemes.)
limit	1.0	public function limit(int $length, HtmlTag|Newline|Stringable|string $append_string = '...'): self Truncate the string to a maximum length using the current mode and only append the suffix when truncation occurs.
repeat	1.0	public function repeat(int $times): self Repeat the string a number of times.
reverse	1.0	public function reverse(): self Reverse the string. (Default mode graphemes.)
shuffle	1.0	public function shuffle(): self Shuffle the characters in the string randomly.
slug	1.0	public function slug(Newline|HtmlTag|string $separator = '-'): self Convert the string to a URL-friendly "slug". Replaces spaces and special characters with the specified separator (default is '-').
fileNameSlug	1.0	public function fileNameSlug(Newline|HtmlTag|string $separator = '-'): self Generate a filesystem-safe filename, preserving extensions while replacing invalid characters with the separator.
insertAtInterval	1.0	public function insertAtInterval(Newline|HtmlTag|Regex|string $insert, int $interval): self Insert a string at regular intervals in the current string. (Default counting mode graphemes.)
wrap	1.0	public function wrap(Newline|HtmlTag|Regex|string $before, Newline|HtmlTag|Regex|string $after = null): self Wrap the string with the specified before and after strings. If $after is not provided, it uses the same value as $before.
indent	1.0	public function indent(int $spaces = 2, int $tabs = 0, int $lines = 0): self Indent the string by adding spaces and/or tabs at the beginning of each line. Positive $lines count from the top; negative values count from the bottom.
outdent	1.0	public function outdent(int $spaces = 2, int $tabs = 0, int $lines = 0): self Outdent the string by removing spaces and/or tabs from the beginning of each line. Positive $lines count from the top; negative values count from the bottom.
normalize	1.0	public function normalize(int $form = Normalizer::FORM_C): self Normalize the string to a specific Unicode normalization form. Default is Normalizer::FORM_C.
pad	1.0	public function pad(int $length, Newline|HtmlTag|Regex|string $pad_string = ' ', bool $left = true, bool $right = true): self Pad the string to a certain length with another string. You can specify whether to pad on the left, right, or both sides. By default it pads on both sides.
lpad	1.0	public function lpad(int $length, Newline|HtmlTag|Regex|string $pad_string = ' '): self Convenience wrapper around pad() that pads only on the left side.
rpad	1.0	public function rpad(int $length, Newline|HtmlTag|Regex|string $pad_string = ' '): self Convenience wrapper around pad() that pads only on the right side.
center	1.0	public function center(int $length, Newline|HtmlTag|Regex|string $pad_string = ' '): self Center the string within a certain length by padding it on both sides with another string.
mask	1.0	public function mask(Newline|HtmlTag|Regex|string $mask, Newline|HtmlTag|Regex|string $mask_char = '#', bool $reversed = false): self Mask the string using a specified mask pattern. The mask pattern uses a special character (default is '#') to indicate where characters from the original string should be placed, and can optionally align placeholders from the end.
collapseWhitespace	1.0	public function collapseWhitespace($space = true, $tab = true, $newline = false): self Collapse consecutive whitespace characters. By default, newlines are not collapsed. You can enable/disable collapsing individually.
collapseWhitespaceToSpace	1.0	public function collapseWhitespaceToSpace(): self Replace every run of whitespace with a single regular space.
collapseWhitespaceToTab	1.0	public function collapseWhitespaceToTab(): self Replace every run of whitespace with a single tab character.
collapseWhitespaceToNewline	1.0	public function collapseWhitespaceToNewline(): self Replace every run of whitespace with a single newline character.
between	1.0	public function between(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $start, Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $end, $last_occurence = false, int $skip_start = 0, int $skip_end = 0): self Get the substring between two strings. If $last_occurence is true, it searches from the end of the string. You can skip a number of occurrences of the start and end strings by setting $skip_start and $skip_end. If an array is provided for $start and/or $end, it will search for the first value, then starting from that index, search for the next one, etc.
before	1.0	public function before(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search, $last_occurence = false, int $skip = 0): self Get the substring before a specific string. If $last_occurence is true, it searches from the end of the string. You can skip a number of occurrences of the search string by setting $skip.
after	1.0	public function after(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search, $last_occurence = false, int $skip = 0): self Get the substring after a specific string. If $last_occurence is true, it searches from the end of the string. You can skip a number of occurrences of the search string by setting $skip.
toSnake	1.0	public function toSnake(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $input_delimiter = ' '): self Convert the string to snake_case. The parameter specifies the input delimiter or delimiters; e.g. when ' ' is given, spaces are converted to '_'. Output always uses underscores.
toKebab	1.0	public function toKebab(): self Convert the string to kebab-case (lowercase words separated by hyphens).
toCamel	1.0	public function toCamel(bool $capitalize_first = false): self Convert the string to camelCase. If $capitalize_first is true, it converts to PascalCase (first letter capitalized).
toTitle	1.0	public function toTitle(): self Convert the string to Title Case (first letter of each word capitalized).
toPascal	1.0	public function toPascal(): self Convert the string to PascalCase (first letter capitalized, no spaces).
match	1.0	public function match(Regex|array<Regex> $pattern, int $offset = 0): null | XString Match the string against one or more regex patterns starting at an optional offset. Returns the earliest matched substring as a new XString, or null if none are found.

Strip / Remove

Method	Version	Signature & Description
strip	1.0	public function strip(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search, null|int $limit = null, $reversed = false): self Remove all occurrences of a specific string from the current string. By default it removes all occurrences, but you can limit the number of removals by setting the $limit parameter. If $reversed is true, it removes from the end of the string.
stripEmojis	1.0	public function stripEmojis(): self Remove all emoji characters from the string.
stripTags	1.0	public function stripTags(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $allowed_tags = ''): self Strip HTML and PHP tags from the string. You can specify tags that should not be stripped by providing them in the $allowed_tags parameter.
stripAccents	1.0	public function stripAccents(): self Remove accents from characters in the string. (e.g. é -> e, ñ -> n)

Affixing

Method	Version	Signature & Description
ensurePrefix	1.0	public function ensurePrefix(Newline|HtmlTag|string $prefix): self Ensure the string starts with the specified prefix. If it doesn't, the prefix is added.
ensureSuffix	1.0	public function ensureSuffix(Newline|HtmlTag|string $suffix): self Ensure the string ends with the specified suffix. If it doesn't, the suffix is added.
removePrefix	1.0	public function removePrefix(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $prefix): self Remove the specified prefix from the string if it exists. If an array is provided it will act as an OR.
removeSuffix	1.0	public function removeSuffix(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $suffix): self Remove the specified suffix from the string if it exists. If an array is provided it will act as an OR.
togglePrefix	1.0	public function togglePrefix(Newline|HtmlTag|string $prefix): self Toggle the specified prefix on the string. If the string starts with the prefix, it is removed. If it doesn't, the prefix is added.
toggleSuffix	1.0	public function toggleSuffix(Newline|HtmlTag|string $suffix): self Toggle the specified suffix on the string. If the string ends with the suffix, it is removed. If it doesn't, the suffix is added.
hasPrefix	1.0	public function hasPrefix(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $prefix): bool Check if the string starts with the specified prefix. If an array is provided it will act as an OR.
hasSuffix	1.0	public function hasSuffix(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $suffix): bool Check if the string ends with the specified suffix. If an array is provided it will act as an OR.

Other methods

Method	Version	Signature & Description
split	1.0	public function split(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $delimiter, null| int $limit = null): array Split the string into an array using the specified delimiter. If $limit is provided, it limits the number of splits. If an array is provided it will act as an OR.
explode	1.0	public function explode(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $delimiter, null | int $limit = null): array Alias for split().
lines	1.0	public function lines(bool $trim = false, null|int $limit = null): array Split the string into an array of lines. If $trim is true, it trims each line. If $limit is provided, it limits the number of lines returned.
words	1.0	public function words(bool $trim = false, null|int $limit = null): array Split the string into an array of words. If $trim is true, it trims each word.
betweenAll	1.0	public function betweenAll(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $start, Newline|HtmlTag|Regex|string $end, $reversed = false): array Get all substrings between two strings. If $reversed is true, it searches from the end of the string. If arrays are provided for $start and/or $end, it will search for the first value, then starting from that index, search for the next one, etc. when $reversed it searches backwards.
length	1.0	public function length(): int Get the length of the string. (Default graphemes.)
byteLength	1.0	public function byteLength(): int Get the byte length of the string.
graphemeLength	1.0	public function graphemeLength(): int Get the grapheme length of the string.
wordCount	1.0	public function wordCount(): int Get the number of words in the string.
lineCount	1.0	public function lineCount(): int Get the number of lines in the string.
sentenceCount	1.0	public function sentenceCount(): int Get the number of sentences in the string.
charAt	1.0	public function charAt(int $index): string Get the character at a specific index in the string. (Default graphemes.)
contains	1.0	public function contains(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search): bool Check if the string contains a specific substring. If an array is provided it will act as an OR.
indexOf	1.0	public function indexOf(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search, $reversed = false): false|int Get the index of the first occurrence of a substring. If $reversed is true, it searches from the end of the string. If an array is provided it will act as an OR. Returns the first (lowest) index found among all candidates, or false if not found.
isEmpty	1.0	public function isEmpty($newline = true, $space = true, $tab = true): bool Check if the string is empty. By default it considers newlines, spaces and tabs as empty characters. You can disable checking for any of these by setting the relevant parameter to false.
startsWith	1.0	public function startsWith(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search): bool Check if the string starts with the specified substring. If an array is provided it will act as an OR.
endsWith	1.0	public function endsWith(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search): bool Check if the string ends with the specified substring. If an array is provided it will act as an OR.
equals	1.0	public function equals(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $string, bool $case_sensitive = true): bool Check if the string is equal to another string. You can specify whether the comparison should be case-sensitive. Default is true. If an array is provided it will act as an OR.
countOccurrences	1.0	public function countOccurrences(Newline|HtmlTag|Regex|string|array<Newline|HtmlTag|Regex|string> $search): int Count the number of occurrences of a substring in the string. If an array is provided it will act as an OR.
matchAll	1.0	public function matchAll(Regex|array<Regex> $pattern, false|int $limit = false, array|int|null $flags = PREG_PATTERN_ORDER): array Match all occurrences of a regex pattern in the string. You can limit the number of matches by setting $limit. The $flags parameter determines the format of the returned array (default is PREG_PATTERN_ORDER).
similarityScore	1.0	public function similarityScore(Newline|HtmlTag|Regex|string $comparison, string $algorithm = 'github-style', array $options = []): float Calculate a normalized similarity score between this string and another. Returns a ratio in [0.0, 1.0]. Algorithms: levenshtein — Minimum single‑char edits; normalized by max length (great for typos). damerau-levenshtein — Levenshtein where adjacent transposition counts as one edit. jaro-winkler — Rewards matching order and common prefixes; ideal for short strings/names. lcs-myers — Longest Common Subsequence (Myers). Score = 2·LCS/(|A|+|B|); feels like diffs. ratcliff-obershelp — “Gestalt”/SequenceMatcher-style recursive common-substring ratio. jaccard — Token set overlap; ignores order and duplicates. sorensen-dice — Token overlap coefficient; slightly more forgiving than Jaccard. cosine-ngrams — Cosine similarity over character/word n‑grams (supports TF, TF‑IDF, etc.). monge-elkan — Soft token matching using a secondary metric per token pair. soft-tfidf — TF‑IDF weighted tokens with soft equality via a secondary metric and threshold. github-style — Token‑level LCS ratio with a small common‑prefix boost for a diff‑like feel. Options: granularity: token | word | character (default: token; “token” = whitespace/punct split) case_sensitive: true | false (default: false) threshold: float 0..1 (default: 0.0; post‑filter on the final score) n: int for n‑grams (default: 3; used by cosine-ngrams) weighting: binary | tf | log | augmented | double-normalization-0.5 | tfidf (default: binary; applies to cosine-ngrams/soft-tfidf) tokenizer: callable to tokenize input (default: internal tokenizer based on granularity) secondary_metric: algorithm used inside monge-elkan/soft-tfidf (default: jaro-winkler) tau: float 0..1 soft-match threshold for soft-tfidf/monge-elkan (default: 0.9) normalize_whitespace: true | false (default: true) strip_punctuation: true | false (default: true when granularity ≠ character)
toInt	1.0	public function toInt(): int Convert the current value to an integer, accepting optional underscores and floating-point notation (truncated toward zero) with range validation.
toFloat	1.0	public function toFloat(): float Convert the current value to a finite floating-point number with underscore support.
toBool	1.0	public function toBool(): bool Interpret the string as a boolean using common affirmative/negative tokens and numeric semantics.
toString	1.1	public function toString(): string Return the underlying PHP string without casting.

Encoding methods

Method	Version	Signature & Description
transliterate	1.0	public function transliterate(string $to = 'ASCII//TRANSLIT'): self Transliterate the string to a different character set. Default is 'ASCII//TRANSLIT'.
toEncoding	1.0	public function toEncoding(string $to_encoding, null|string $from_encoding = null): self Convert the string to a different encoding. If $from_encoding is not provided, it tries to detect the current encoding.
detectEncoding	1.0	public function detectEncoding(array $encodings = ['UTF-8', 'ISO-8859-1', 'ASCII']): string|false Detect the encoding of the string from a list of possible encodings. Returns the detected encoding or false if none matched.
isValidEncoding	1.0	public function isValidEncoding(null|string $encoding = null): bool Check if the string is valid in the specified encoding. If $encoding is not provided, it uses the current encoding of the string.
isAscii	1.0	public function isAscii(): bool Check if the string contains only ASCII characters.
isUtf8	1.0	public function isUtf8(): bool Check if the string is valid UTF-8.
toUtf8	1.0	public function toUtf8(nul |string $from_encoding = null): self Convert the string to UTF-8 encoding. If $from_encoding is not provided, it tries to detect the current encoding.
toAscii	1.0	public function toAscii(null|string $from_encoding = null): self Convert the string to ASCII encoding. If $from_encoding is not provided, it tries to detect the current encoding.

Encryption and Hashing

Method	Version	Signature & Description
base64Encode	1.0	public function base64Encode(): self Base64-encode the string.
base64Decode	1.0	public function base64Decode(): self Base64-decode the string.
md5	1.0	public function md5(bool $raw_output = false): self Get the MD5 hash of the string. If $raw_output is true, it returns the raw binary format.
crc32	1.0	public function crc32(bool $raw_output = false): self Get the CRC32B checksum of the string. If $raw_output is true, it returns the raw binary format.
sha1	1.0	public function sha1(bool $raw_output = false): self Get the SHA-1 hash of the string. If $raw_output is true, it returns the raw binary format.
sha256	1.0	public function sha256(bool $raw_output = false): self Get the SHA-256 hash of the string. If $raw_output is true, it returns the raw binary format.
crypt	1.0	public function crypt(string $salt): self Hash the string using the crypt() function with the specified salt.
passwordHash	1.0	public function passwordHash(int $algo = PASSWORD_BCRYPT, array $options = []): self Hash the string using password_hash() with the specified algorithm and options. Default is PASSWORD_BCRYPT.
passwordVerify	1.0	public function passwordVerify(string $hash): bool Verify the string against a given hash using password_verify(). Returns true if the string matches the hash, false otherwise.
encrypt	1.0	public function encrypt(string $password, string $cipher = 'sodium_xchacha20'): self Encrypt the string using authenticated encryption (AEAD). Requires libsodium for the default XChaCha20-Poly1305 path; pass 'aes-256-gcm' to use the OpenSSL backend. Returns a versioned envelope (salt + nonce + tag + algorithm id + ciphertext) encoded as a string.
decrypt	1.0	public function decrypt(string $password, string $cipher = 'sodium_xchacha20'): self Decrypt a ciphertext produced by encrypt(). Verifies integrity (auth tag). Supports sodium_xchacha20 (libsodium required) or aes-256-gcm (OpenSSL). Throws on invalid password, tampering, or unsupported version.

Codecs

Method	Version	Signature & Description
htmlEscape	1.0	public function htmlEscape(int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, string $encoding = 'UTF-8'): self Escape HTML special characters in the string. You can specify flags and encoding.
htmlUnescape	1.0	public function htmlUnescape(): self Unescape HTML special characters in the string.
encodeHtmlEntities	1.0	public function encodeHtmlEntities(int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, ?string $encoding = null, bool $double_encode = false): self Encode the string with htmlentities(), allowing custom flags, encoding, and optional double encoding (disabled by default).
decodeHtmlEntities	1.0	public function decodeHtmlEntities(int $flags = ENT_QUOTES | ENT_HTML401, ?string $encoding = null): self Decode HTML entities back to characters while respecting flags and encoding.
urlEncode	1.0	public function urlEncode(bool $raw = false): self URL-encode the string. If $raw is true, it uses rawurlencode().
urlDecode	1.0	public function urlDecode(bool $raw = false): self URL-decode the string. If $raw is true, it uses rawurldecode().
nl2br	1.0	public function nl2br(bool $is_xhtml = true): self Convert newlines to HTML <br> tags. If $is_xhtml is true, it uses for XHTML compliance.
br2nl	1.0	public function br2nl(): self Convert HTML <br> tags to newlines.

Filesystem helpers

Method	Version	Signature & Description
encodeWindowsFileName	1.0	public function encodeWindowsFileName(bool $double_encode = false): self Percent-encode characters that Windows forbids in filenames so decoding is lossless.
decodeWindowsFileName	1.0	public function decodeWindowsFileName(): self Decode %XX sequences in Windows filenames produced by encodeWindowsFileName().
encodeWindowsFolderName	1.0	public function encodeWindowsFolderName(bool $double_encode = false): self Percent-encode forbidden characters and reserved device names inside Windows folder names.
decodeWindowsFolderName	1.0	public function decodeWindowsFolderName(): self Restore Windows folder names by decoding escapes generated by encodeWindowsFolderName().
encodeWindowsPath	1.0	public function encodeWindowsPath(bool $double_encode = false): self Percent-encode unsafe characters within Windows path segments while preserving drive and UNC prefixes.
decodeWindowsPath	1.0	public function decodeWindowsPath(): self Decode Windows path strings that were encoded with encodeWindowsPath().
toWindowsFileName	1.0	public function toWindowsFileName(): self Sanitise the value into a Windows-compatible filename, escaping reserved device names and forbidden characters.
toWindowsFolderName	1.0	public function toWindowsFolderName(): self Generate a Windows-safe folder name by replacing forbidden characters, trimming trailing dots/spaces, and prefixing reserved names.
toWindowsPath	1.0	public function toWindowsPath(): self Normalise the string into a Windows path with safe segments, preserving drive letters and UNC prefixes.
encodeUnixFileName	1.0	public function encodeUnixFileName(bool $double_encode = false): self Percent-encode /, %, and null bytes so Unix filenames can be restored exactly.
decodeUnixFileName	1.0	public function decodeUnixFileName(): self Decode %XX escapes created by encodeUnixFileName().
encodeUnixFolderName	1.0	public function encodeUnixFolderName(bool $double_encode = false): self Percent-encode Unix-forbidden characters inside folder names while leaving everything else untouched.
decodeUnixFolderName	1.0	public function decodeUnixFolderName(): self Reverse the escapes created by encodeUnixFolderName().
encodeUnixPath	1.0	public function encodeUnixPath(bool $double_encode = false): self Percent-encode forbidden characters within Unix path segments while keeping / separators.
decodeUnixPath	1.0	public function decodeUnixPath(): self Decode Unix path strings generated by encodeUnixPath().
toUnixFileName	1.0	public function toUnixFileName(): self Produce a Unix-safe filename by removing control bytes and replacing forbidden separators.
toUnixFolderName	1.0	public function toUnixFolderName(): self Produce a Unix-safe folder name by stripping control bytes, replacing slashes, and collapsing special names.
toUnixPath	1.0	public function toUnixPath(): self Convert the value to a Unix path using cleaned segments joined by forward slashes.
encodeMacOSFileName	1.0	public function encodeMacOSFileName(bool $double_encode = false): self Percent-encode /, :, %, and null bytes in macOS filenames while leaving other characters intact.
decodeMacOSFileName	1.0	public function decodeMacOSFileName(): self Decode %XX escapes created by encodeMacOSFileName().
encodeMacOSFolderName	1.0	public function encodeMacOSFolderName(bool $double_encode = false): self Percent-encode macOS-forbidden characters inside folder names for lossless decoding.
decodeMacOSFolderName	1.0	public function decodeMacOSFolderName(): self Decode escapes produced by encodeMacOSFolderName().
encodeMacOSPath	1.0	public function encodeMacOSPath(bool $double_encode = false): self Percent-encode forbidden characters within macOS path segments while preserving / separators.
decodeMacOSPath	1.0	public function decodeMacOSPath(): self Decode macOS path strings generated by encodeMacOSPath().
toMacOSFileName	1.0	public function toMacOSFileName(): self Return a macOS-friendly filename by replacing colons/slashes and collapsing special names.
toMacOSFolderName	1.0	public function toMacOSFolderName(): self Return a macOS-friendly folder name by replacing colons/slashes, stripping control characters, and normalising special names.
toMacOSPath	1.0	public function toMacOSPath(): self Normalise the value to a macOS path with cleaned segments and / separators.
encodeSafeFileName	1.0	public function encodeSafeFileName(bool $double_encode = false): self Percent-encode filesystem-forbidden characters for maximum cross-platform safety.
decodeSafeFileName	1.0	public function decodeSafeFileName(): self Decode %XX escapes created by encodeSafeFileName().
encodeSafeFolderName	1.0	public function encodeSafeFolderName(bool $double_encode = false): self Percent-encode unsafe characters in folder names according to the strictest platform rules.
decodeSafeFolderName	1.0	public function decodeSafeFolderName(): self Decode escapes produced by encodeSafeFolderName().
encodeSafePath	1.0	public function encodeSafePath(bool $double_encode = false): self Percent-encode forbidden characters in each path segment while normalising separators to /.
decodeSafePath	1.0	public function decodeSafePath(): self Decode portable paths that were encoded with encodeSafePath().
toSafeFileName	1.0	public function toSafeFileName(): self Generate a conservative filename safe across Windows, Unix-like systems, and macOS.
toSafeFolderName	1.0	public function toSafeFolderName(): self Generate a conservative folder name safe across Windows, Unix-like systems, and macOS.
toSafePath	1.0	public function toSafePath(): self Produce a portable path by sanitising each segment and joining with forward slashes.

Newline class methods

Used to tell search arguments in other methods that you want to search for newlines.

Method	Version	Signature & Description
new	1.0	public static function new(null|string $newline = null): self Create a new Newline instance. Default newline is any.
startsWith	1.0	public function startsWith(null|string $string, bool $trim = false): self Creates a newline that starts with $string. Can be used to check if the newline starts with the specified string.
endsWith	1.0	public function endsWith(null|string $string, bool $trim = false): self Creates a newline that ends with $string. Can be used to check if the newline ends with the specified string.
contains	1.0	public function contains(null|string $string): self Used to check if a newline contains the specified string.
equals	1.0	public function equals(null|string $string): self Used to check if a newline is equal to the specified string.

Regex class methods (all static)

Used to tell search arguments in other methods that you want to search for a regex pattern.

Method	Version	Signature & Description
new	1.0	public static function new(string $pattern, int $modifiers = 0): self Create a new Pattern instance. $modifiers is a bitmask of regex modifiers (ex. Pattern::MODIFIER_CASE_INSENSITIVE).

HtmlTag class methods

Method	Version	Signature & Description
new	1.0	public static function new(string $tag_name, bool $self_closing = false, bool $case_sensitive = false): self Create a new HtmlTag instance.
closeTag	1.0	public static function closeTag(string $tag_name, bool $case_sensitive = false): self Create a new HtmlTag instance that matches a closing tag.
withClass	1.0	public function withClass(string|array<string> ...$class_name): self Add one or more class name conditions to the HtmlTag instance.
withId	1.0	public function withId(string $id): self Add an ID condition to the HtmlTag instance. The tag must have this ID to match.
withAttribute	1.0	public function withAttribute(string $attr_name, null|string $attr_value = null, bool $case_sensitive = false): self Add an attribute condition to the HtmlTag instance. The tag must have this attribute (and value if provided) to match.
withBody	1.0	public function withBody(HtmlTag|Newline|Regex|Stringable|string|array $body): self Append body fragments to the opening tag.
withEndTag	1.0	public function withEndTag(bool $append_newline = true): self Emit the matching closing tag, optionally inserting a trailing newline.

XStringType (factory) class

Method	Version	Signature & Description
newline	1.0	public static function newline(null|string $newline = null): Newline Create a new Newline instance via XStringType::newline().
regex	1.0	public static function regex(string $pattern): Regex Create a new Regex instance via XStringType::regex().
htmlTag	1.0	public static function htmlTag(string $tag_name, bool $self_closing = false, bool $case_sensitive = false): HtmlTag Create a new HtmlTag instance via XStringType::htmlTag().
htmlCloseTag	1.0	public static function htmlCloseTag(string $tag_name, bool $case_sensitive = false): HtmlTag Create a new HtmlTag instance that matches a closing tag via XStringType::htmlCloseTag().

Examples

Here are some examples of how to use the XString class:

Basic Usage

use Orryv\XString;

// Create a new XString instance
$str = XString::new(" Hello, World! \n");
#Test: self::assertTrue($str instanceof XString);
#Test: self::assertEquals(" Hello, World! \n", (string)$str);

// Trim whitespace
$trimmed = $str->trim();
#Test: self::assertEquals("Hello, World!", (string)$trimmed);

Newlines

use Orryv\XString;
use Orryv\XString\Newline;

$str = ' Line1 - blabla' . PHP_EOL . 'Hello, World!';

$string = XString::new($str);
#Test: self::assertEquals($str, (string)$string);

// Remove first line (one way to do it)
$string = $string->after(Newline::new()->startsWith('Line1', trim:true));
//Same as: $string->after(XStringType::newline()->startsWith('Line1', trim:true));
#Test: self::assertEquals("Hello, World!", (string)$string);