Introduction

Windwalker Utilities is a set of small helpers that other Windwalker packages build on. Its two main classes, Arr and Str, cover the array and string work that native PHP functions make awkward: nested data is read by key path, argument order is consistent, and text is handled as UTF-8 by default.

The package has these main parts:

• Arr: static helpers for arrays and objects. It reads, writes, filters, queries, merges, and diffs data by dot-separated key paths. See Arr.
• Arr::sync(): splits existing and incoming rows into creating, deleting, and keeping groups. See Array Sync.
• Str: static helpers for strings. It searches, trims, pads, truncates, and increments text with encoding awareness. See Str.

Both classes are static. You call them directly, with no instance to create and no service to register.

Installation

composer require windwalker/utilities ^4.0

The package requires PHP 8.4.6 or later.

Use as Standalone Component

Import the classes you need. No configuration is required:

use Windwalker\Utilities\Arr;
use Windwalker\Utilities\Str;

$config = [
    'app' => ['name' => 'blog'],
];

$name = Arr::get($config, 'app.name');   // blog
$path = Str::ensureStart('admin', '/');  // /admin

Use in Windwalker

The helpers are not registered in the Windwalker container. Use them the same way as in standalone code, by importing the class where you need it:

use Windwalker\Utilities\Arr;

class UserProfile
{
    public function displayName(array $user): string
    {
        return Arr::get($user, 'profile.name') ?? 'Guest';
    }
}

Core Concepts

Both classes follow the same two ideas.

• Key paths: a dot-separated string such as db.host addresses a value inside nested arrays or objects. Passing a different delimiter changes the separator. Read Arr for details.
• Non-destructive by default: most methods return a new value and leave the input unchanged. The exceptions, such as Arr::takeout(), are named in their topic pages.

Topic Pages

• Arr: reading, writing, selecting, and reshaping arrays and objects by key path.
• Array Sync: comparing a stored list with incoming input to decide what to create, delete, and update.
• Str: searching, trimming, padding, truncating, and transforming strings, with encoding support.
• Assert: one-line argument and state checks with messages that name the caller and the value.
• Attributes: reading PHP attributes from classes, members, and parent classes, trait options, and controlling which properties appear in object dumps.
• Enum Metadata: titles, icons, colors, and other metadata on enum cases.
• Iterators: lazy pipelines, re-runnable generators, paged sources, unique values, and ordered priority queues.
• Exceptions: exception helpers for multiple messages and verbosity levels.
• Object Helpers: caching values in a class, reflective member access, and PHP 8.4 lazy objects.
• Helpers: global helper functions, and the Env class.
• Identifiers: numbered sequences and named markers.
• Text Transforms: filling placeholders in text, singular and plural forms of English words, and converting names between naming styles.
• Type Cast: strict, safe, and forced conversions between types.

Related components

• Scalars: wraps arrays and strings in chainable objects that use Arr and Str internally.