README

English | 日本語

A small utility class that recursively trims whitespace (or custom characters) from strings, including strings nested inside arrays of any depth.

Why

PHP's built-in trim() / ltrim() / rtrim() only operate on a single string. Trimming every string value inside a (possibly nested) array normally means writing your own recursive helper, or reaching for array_map() — which breaks as soon as the array contains nested arrays or non-string values.

Trimmer handles this for you.

Installation

composer require bvp/trimmer

Usage

use BVP\Trimmer\Trimmer;

Trimmer::trim('  hello  ');
// 'hello'

Trimmer::trim([' foo ', ' bar ', ['  baz  ', null, 42]]);
// ['foo', 'bar', ['baz', null, 42]]

Available methods

Method	Behavior
`Trimmer::trim($items, $characters = null, $encoding = null, $trimKeys = false)`	Trims both ends
`Trimmer::ltrim(...)`	Trims the left end only
`Trimmer::rtrim(...)`	Trims the right end only
`Trimmer::trimStart(...)`	Alias for `ltrim()`
`Trimmer::trimEnd(...)`	Alias for `rtrim()`

All methods accept the same four parameters:

$items (mixed) — a string, an array (nested to any depth), or any other value. Strings are trimmed; arrays are walked recursively; anything else is returned untouched.
$characters (?string) — the set of characters to trim. Defaults to the standard whitespace characters (" \t\n\r\0\x0B"), same as PHP's built-in trim().
$encoding (?string) — character encoding, only used on PHP ≥ 8.4 (see below).
$trimKeys (bool, default false) — when true, string array keys are trimmed as well (see Trimming array keys).

PHP version behavior

PHP ≥ 8.4: uses the multibyte-aware mb_trim() / mb_ltrim() / mb_rtrim(), so $encoding is respected.
PHP < 8.4: falls back to the built-in trim() / ltrim() / rtrim() (byte-based); $encoding is ignored.

Trimming array keys

By default, only array values are trimmed — keys are left as-is, matching how a plain array_map('trim', $array) would behave.

Pass trimKeys: true to also trim string keys:

Trimmer::trim([' foo ' => ' bar ', 'foo' => 'baz'], trimKeys: true);
// ['foo' => 'baz']

Note on collisions: if trimming causes two keys to become identical (including PHP's automatic casting of a canonical numeric string key like "8" to the integer 8), the later value silently overwrites the earlier one — the same behavior you'd get from a normal PHP array assignment ($array[$key] = $value).

Maximum nesting depth

Nested arrays are walked recursively, so an array nested deeper than Trimmer::MAX_DEPTH (512, matching PHP's own json_decode() / json_encode() default) throws OverflowException instead of risking a stack overflow.

What it does not do

It does not trim object properties. Objects are returned untouched, since trimming them safely would require knowing each class's getters/setters, readonly properties, and constructor validation — which can't be handled generically without risking broken invariants.

License

Trimmer is open-source software released under the MIT license.

bvp / trimmer

Maintainers

Package info

Statistics

Security