Download the PHP package atk14/string4 without Composer

String4

String4 is a PHP class for comfortable, chainable string manipulation with full UTF-8 support. It wraps a plain PHP string in an object and exposes a rich set of methods — case conversion, slugification, truncation, HTML stripping, pluralization, and more — all designed to be chained fluently.

• Installation
• Instantiation
• Method reference
  • Basics
  • Case
  • Search & replace
  • Substrings & slicing
  • Splitting & characters
  • Whitespace
  • HTML
  • Conversion & formatting
  • Line operations
  • Random generation
  • Encoding
  • Utilities
• Testing
• Licence

Installation

Instantiation

Constructor

String4::ToObject($string, $encoding = null) — static factory; returns a copy if the argument is already a String4 instance, otherwise wraps it.

Method reference

Most methods return a new String4 instance and leave the original unchanged, so calls can be chained freely.

Basics

length() → int

Returns the number of characters (not bytes) in the string. Multibyte-safe.

toString() → string

Returns the underlying plain PHP string. Calling echo or interpolating "$s" works too thanks to __toString().

copy() → String4

Returns an independent copy of the object.

getEncoding($normalize = false) → string

Returns the encoding the string was constructed with. Pass true to get a normalized lowercase form (e.g. "utf8" instead of "UTF-8").

Case

upcase() / upper() → String4

Converts all characters to uppercase. Both names are equivalent aliases.

downcase() / lower() → String4

Converts all characters to lowercase.

isUpper() → bool

Returns true when all characters are uppercase. Returns false for an empty string.

isLower() → bool

Returns true when all characters are lowercase. Returns false for an empty string.

capitalize() → String4

Uppercases the first character, leaves the rest unchanged.

uncapitalize() → String4

Lowercases the first character, leaves the rest unchanged.

camelize($options = []) → String4

Converts an underscored string to CamelCase. By default the first letter is uppercased; pass ["lower" => true] for lowerCamelCase.

underscore() → String4

Converts a CamelCase string to snake_case.

titleize($options = []) → String4

Capitalizes every word and replaces underscores and hyphens with spaces. Strips a trailing _id suffix by default; pass ["keep_id_suffix" => true] to keep it.

Search & replace

contains($needle) → bool

Returns true if the string contains the given substring. When an array is passed, all elements must be present.

containsOneOf(...$needles) → bool

Returns true if the string contains at least one of the given substrings. Accepts individual arguments or a single array.

match($pattern, &$matches = null) → int|false

Wrapper around preg_match(). Match groups are returned in $matches as String4 instances.

replace($search, $replace = null) → String4

Replaces occurrences of $search with $replace. When $search is an associative array, each key is replaced with its corresponding value.

gsub($pattern, $replaceOrCallable) → String4

Replaces all matches of a regular expression with a string or the return value of a callback. Wrapper around preg_replace() / preg_replace_callback().

prepend($content) → String4

Inserts a string at the beginning.

append($content) → String4

Appends a string to the end.

Substrings & slicing

substr($start, $length = null) → String4

Returns a substring. Multibyte-safe. Negative $start counts from the end.

first($limit = 1) → String4

Returns the first $limit characters.

at($position) → String4

Returns the character at the given zero-based position.

truncate($length, $options = []) → String4

Shortens the string to $length characters. By default appends "..." to indicate truncation.

Options:

• omission — string appended when truncated (default: "...")
• separator — if set, the string is truncated at the last occurrence of this character before the cutoff, avoiding mid-word cuts

Splitting & characters

chars($options = []) → array

Returns an array of individual characters as String4 instances. Pass ["stringify" => true] to get plain PHP strings instead.

split($separator, $options = []) → array

Splits the string by a plain-string separator and returns an array of String4 instances. Pass ["stringify" => true] for plain strings.

pregSplit($separator, $options = []) → array

Like split() but treats the separator as a regular expression. Shorthand for split($separator, ["preg_split" => true]).

Whitespace

trim($removeHiddenCharacters = false) → String4

Strips whitespace from both ends of the string. For UTF-8 strings this covers all Unicode space characters (NBSP, Em Space, Thin Space, Ideographic Space, etc.), not just ASCII whitespace.

Pass true to also strip invisible/control characters (zero-width spaces, BOM, directional marks, soft hyphens, etc.).

squish() → String4

Trims the string (including invisible characters) and collapses all internal whitespace sequences to a single space.

HTML

stripTags() → String4

Removes all HTML tags (thin wrapper around PHP's strip_tags()).

stripHtml() → String4

A smarter HTML-to-text converter. Compared to stripTags() it:

• removes block-level tags (<p>, <div>, <br>, headings, etc.) and inserts spaces so words don't run together
• removes entire content of <script>, <style>, <head>, <noscript>, and similar non-visible tags
• decodes HTML entities (& → &,   → , etc.)
• normalizes whitespace in the result

Conversion & formatting

toAscii() → String4

Transliterates the string to ASCII, replacing accented and special characters with their closest ASCII equivalents.

toSlug($options = []) → String4

Converts the string to a URL-friendly slug: transliterates to ASCII, lowercases, replaces non-alphanumeric characters with hyphens, and strips leading/trailing hyphens.

An integer can be passed directly as $options to set max_length.

Options:

• max_length — maximum length of the resulting slug
• suffix — string appended to the slug (also slugified itself), useful for appending IDs

toBoolean() → bool

Converts the string to a boolean. Returns false for an empty string and for the values "false", "off", "no", "n", "f" (all case-insensitive). Returns true for everything else.

pluralize() → String4

Returns the plural form of the last word in the string (English only).

singularize() → String4

Returns the singular form of the last word in the string (English only).

tableize() → String4

Converts a CamelCase class name to the corresponding database table name: underscores and pluralizes. Handy for ORM-style conventions.

Line operations

removeEmptyLines($options = []) → String4

Removes empty lines from the string. Handles all common line endings (\n, \r\n, \r).

Options:

• max_empty_lines — how many consecutive empty lines to allow (default: 0 — all removed)
• trim_empty_lines — whether to trim whitespace-only lines before deciding if they are empty (default: true)

eachLineMap($callback) → String4

Applies a callback to every line and returns a new string with the mapped lines. Line endings are preserved.

eachLineFilter($callback = null) → String4

Keeps only the lines for which the callback returns true. When no callback is provided, empty lines are filtered out.

Random generation

String4::RandomString($length = 32, $options = []) → String4

Generates a random alphanumeric string ([A-Za-z0-9]). Uses random_int() for cryptographically secure output, suitable for tokens and API keys.

$length can also be passed as part of $options.

Options:

• length — length of the generated string (default: 32)
• extra_chars — additional characters to draw from

String4::RandomNumericString($length = 6) → String4

Generates a random numeric string of exactly $length digits. The first digit is always 1–9 (never zero), so the result is suitable for use as a numeric code or PIN where leading zeros would cause problems.

String4::RandomPassword($length = 10) → String4

Generates a human-friendly random password. Visually ambiguous characters (0, O, 1, l, I) are excluded to reduce transcription errors. The result mixes letters and digits in a pronounceable pattern.

Also works well as a voucher or coupon code generator.

Encoding

fixEncoding($options = []) → String4

Replaces invalid UTF-8 byte sequences with a replacement character. Only has effect on UTF-8 strings. Accepts a string argument directly as a shorthand for ["replacement" => ...].

The default replacement is U+FFFD (the standard Unicode replacement character ▒).

Utilities

getId() → string

Returns the string value. Exists for compatibility with the ATK14 framework, which sometimes calls getId() on objects to obtain their scalar representation.

Method chaining

All transformation methods return a new String4 instance, so calls can be chained in any order:

Testing

String4 is tested automatically via GitHub Actions across PHP 5.6 to PHP 8.5.

Tests use the atk14/tester wrapper for phpunit/phpunit.

Install development dependencies:

Run the test suite:

Licence

String4 is free software distributed under the terms of the MIT license.