Last indexed: 14 February 2026 (fb2a0f)

Utilities and Helpers

Purpose and Scope

This section documents the utility classes and global helper functions provided by the hypervel/support package. These utilities form the foundation for common programming tasks including data manipulation, value transformation, environment detection, memoization, type introspection, and process execution.

The utilities are organized into the following subsystems:

Helper Functions - Global functions in src/helpers.php for common operations
Collections - Extended collection class with resource transformation capabilities
Data Manipulation - Dot notation access via data_get(), data_set(), data_fill(), data_forget()
Environment Configuration - Environment detection via Environment class and env() helper
Memoization - Once/Onceable system for caching callable results
Reflection Utilities - Parameter inspection via Reflector and ReflectsClosures
Process Utilities - Shell argument escaping via ProcessUtils

For information about the DataObject system's immutable DTO capabilities, see Data Object System. For testing-specific utilities, see Testing Infrastructure.

Overview of Utility Categories

The hypervel/support package provides utilities across seven main categories:

Category	Key Components	Child Page
Helper Functions	`value()`, `blank()`, `filled()`, `transform()`, `tap()`, `optional()`, `retry()`, `with()`, `throw_if()`, `throw_unless()`, `when()`	8.1
Collections	`Collection` class, `collect()`, `toResourceCollection()`	8.2
Data Manipulation	`data_get()`, `data_set()`, `data_fill()`, `data_forget()`, `object_get()`	8.3
Environment	`env()`, `environment()`, `Environment` class, `is*()` methods	8.4
Memoization	`once()`, `Once` class, `Onceable` trait	8.5
Reflection	`Reflector`, `ReflectsClosures` trait	8.6
Process Utilities	`ProcessUtils::escapeArgument()`	8.7

Sources: src/helpers.php1-420 src/Collection.php1-20 src/Environment.php1-87 src/Traits/ReflectsClosures.php1-91 src/ProcessUtils.php1-72

Utility System Architecture

Utility System Components: Code Entity Mapping

This diagram maps helper functions and utility classes to their file locations. Global functions in src/helpers.php delegate to specialized classes or Hyperf framework utilities. The Collection, Environment, Once/Onceable, and Reflector classes provide domain-specific functionality.

Sources: src/helpers.php15-420 src/Collection.php1-20 src/Environment.php1-87 src/HigherOrderTapProxy.php1-12 src/Traits/ReflectsClosures.php1-91 src/ProcessUtils.php1-72

Subsystem Overview

8.1 Helper Functions

The src/helpers.php file provides 25+ global functions organized into functional categories:

Category	Functions	Purpose
Value Resolution	`value()`, `blank()`, `filled()`, `transform()`, `with()`	Resolve callables and check value presence
Data Access	`data_get()`, `data_set()`, `data_fill()`, `data_forget()`, `object_get()`	Access nested structures with dot notation
Control Flow	`tap()`, `optional()`, `retry()`, `when()`	Functional programming patterns
Collections	`collect()`, `head()`, `last()`	Create and manipulate collections
Error Handling	`throw_if()`, `throw_unless()`	Conditional exception throwing
Environment	`env()`, `environment()`	Access environment variables
Type Inspection	`class_basename()`, `class_uses_recursive()`, `trait_uses_recursive()`	Introspect class hierarchies
Memoization	`once()`	Execute callables once per context
HTML Safety	`e()`	Escape HTML special characters

See Helper Functions for detailed documentation.

Sources: src/helpers.php15-420

8.2 Collections

The Collection class src/Collection.php16-19 extends Hyperf\Collection\Collection and adds the TransformsToResourceCollection trait, providing the toResourceCollection() method for transforming model collections into API resources.

See Collections for detailed documentation.

Sources: src/Collection.php1-20 src/Traits/TransformsToResourceCollection.php1-126

8.3 Data Manipulation

Data manipulation functions provide dot notation access to arrays and objects:

These functions delegate to Hyperf\Collection\data_get() and related functions src/helpers.php122-150

See Data Manipulation for detailed documentation.

Sources: src/helpers.php112-222

8.4 Environment Configuration

The Environment class src/Environment.php19-86 provides environment detection with magic methods:

The environment() helper src/helpers.php39-51 returns the Environment instance or checks environment patterns.

See Environment Configuration for detailed documentation.

Sources: src/Environment.php1-87 src/helpers.php35-52

8.5 Memoization

The Once/Onceable system provides callable memoization:

Implementation uses Onceable::tryFromTrace() src/helpers.php235-237 to generate a hash from the call context, and Once::instance()->value() to cache results using WeakMap storage.

See Memoization for detailed documentation.

Sources: src/helpers.php224-242

8.6 Reflection Utilities

The ReflectsClosures trait src/Traits/ReflectsClosures.php14-90 provides methods for inspecting closure parameter types:

firstClosureParameterType() - Get first parameter class name src/Traits/ReflectsClosures.php24-37
firstClosureParameterTypes() - Get first parameter types including unions src/Traits/ReflectsClosures.php47-69
closureParameterTypes() - Get all parameter types src/Traits/ReflectsClosures.php78-89

Used by event listeners, service providers, and DataObject for type resolution.

See Reflection Utilities for detailed documentation.

Sources: src/Traits/ReflectsClosures.php1-91

8.7 Process Utilities

The ProcessUtils class src/ProcessUtils.php12-71 provides escapeArgument() for safely escaping shell arguments on Windows and Unix-like systems, handling edge cases like PHP bugs #43784 and #49446.

See Process Utilities for detailed documentation.

Sources: src/ProcessUtils.php1-72

Utility Integration with Core Systems

Utility Integration: How Utilities Support Other Systems

Utilities provide foundational services to all framework layers. The DataObject and ServiceProvider systems use reflection for type resolution. Facades use Environment for environment detection. Views use helpers for HTML escaping. Events use reflection for listener binding and Once for memoization.

Sources: src/helpers.php1-420 src/Collection.php1-20 src/Environment.php1-87 src/Traits/ReflectsClosures.php1-91

Key Implementation Patterns

Pattern 1: Delegation to Hyperf Framework

Many helpers delegate to Hyperf framework functions while providing a Laravel-compatible API:

Delegation Pattern: Hypervel to Hyperf

Functions in src/helpers.php wrap Hyperf framework functions: env() src/helpers.php29-32 optional() src/helpers.php248-251 with() src/helpers.php348-351 data_get() src/helpers.php126-129 data_set() src/helpers.php136-139 and class_basename() src/helpers.php186-189

Sources: src/helpers.php25-351

Pattern 2: Higher-Order Proxies

The tap() function src/helpers.php298-307 returns a HigherOrderTapProxy src/HigherOrderTapProxy.php9-11 when called without a callback, enabling method chaining:

Pattern 3: Callable Memoization

The once() function src/helpers.php233-241 uses Onceable::tryFromTrace() to hash the execution context and Once::instance()->value() to cache results:

Each call site is memoized separately based on file, line, and context.

Sources: src/helpers.php224-242 src/HigherOrderTapProxy.php1-12

Common Usage Patterns

Safe Value Retrieval with Transformation

Functions Used: transform() src/helpers.php330-341 data_get() src/helpers.php126-129

Conditional Exception Throwing

Functions Used: throw_if() src/helpers.php366-377 throw_unless() src/helpers.php392-403 blank() src/helpers.php80-99 filled() src/helpers.php176-179

Retry with Exponential Backoff

Functions Used: retry() src/helpers.php260-291

Tap for Fluent Operations

Functions Used: tap() src/helpers.php298-307

Null-Safe Optional Access

Functions Used: optional() src/helpers.php248-251

Sources: src/helpers.php76-407

Helper Function Quick Reference

Function	File Location	Purpose
`value()`	src/helpers.php19-22	Resolve callable or return value
`env()`	src/helpers.php29-32	Get environment variable
`environment()`	src/helpers.php39-51	Get/check Environment instance
`e()`	src/helpers.php58-73	Escape HTML special characters
`blank()`	src/helpers.php80-99	Check if value is blank
`filled()`	src/helpers.php176-179	Check if value is filled
`collect()`	src/helpers.php106-109	Create Collection instance
`data_get()`	src/helpers.php126-129	Get nested value with dot notation
`data_set()`	src/helpers.php136-139	Set nested value with dot notation
`data_fill()`	src/helpers.php116-119	Set nested value if not present
`data_forget()`	src/helpers.php146-149	Remove nested value with dot notation
`head()`	src/helpers.php156-159	Get first array element
`last()`	src/helpers.php166-169	Get last array element
`object_get()`	src/helpers.php206-221	Get object property with dot notation
`once()`	src/helpers.php233-241	Execute callable once per context
`optional()`	src/helpers.php248-251	Null-safe object access
`retry()`	src/helpers.php260-291	Retry callable with backoff
`tap()`	src/helpers.php298-307	Execute callback and return value
`transform()`	src/helpers.php330-341	Transform value if filled
`with()`	src/helpers.php348-351	Pass value through callback
`throw_if()`	src/helpers.php366-377	Throw exception if condition true
`throw_unless()`	src/helpers.php392-403	Throw exception if condition false
`when()`	src/helpers.php413-418	Return value based on condition
`class_basename()`	src/helpers.php186-189	Get class name without namespace
`class_uses_recursive()`	src/helpers.php196-199	Get all traits recursively
`trait_uses_recursive()`	src/helpers.php314-323	Get trait's traits recursively

For detailed parameter signatures and usage examples, see Helper Functions.

Sources: src/helpers.php1-420

Utility Class Reference

Core Utility Classes

Class	File Path	Purpose
`Collection`	src/Collection.php16-19	Extends Hyperf Collection with resource transformation
`Environment`	src/Environment.php19-86	Environment detection and debug mode
`HigherOrderTapProxy`	src/HigherOrderTapProxy.php9-11	Proxy for tap() pattern without callback
`Reflector`	src/Reflector.php	Parameter type inspection utilities
`ProcessUtils`	src/ProcessUtils.php12-71	Shell argument escaping

Traits

Trait	File Path	Purpose
`ReflectsClosures`	src/Traits/ReflectsClosures.php14-90	Closure parameter type inspection
`TransformsToResourceCollection`	src/Traits/TransformsToResourceCollection.php17-125	Transform collections to API resources

Sources: src/Collection.php1-20 src/Environment.php1-87 src/HigherOrderTapProxy.php1-12 src/Traits/ReflectsClosures.php1-91 src/Traits/TransformsToResourceCollection.php1-126 src/ProcessUtils.php1-72

Performance and Best Practices

Memoization Strategy

The once() function src/helpers.php233-241 provides automatic memoization based on call context. Results are cached using WeakMap storage, allowing garbage collection when objects are no longer referenced.

Delegation Pattern

Many helper functions delegate to optimized Hyperf framework implementations:

data_get(), data_set(), data_fill(), data_forget() → Hyperf\Collection\*
env(), optional(), with(), class_basename() → Hyperf\Support\*

This delegation ensures performance while maintaining API compatibility.

Recommended Patterns

Use data_get() for nested access - Safer and more readable than chained null checks
Use once() for expensive computations - Automatic memoization per call site
Use tap() for fluent side effects - Maintains chainability while executing side effects
Use optional() for null safety - Prevents "call to member function on null" errors
Use retry() with conditional checks - Only retry transient failures, not permanent errors

Sources: src/helpers.php1-420

URL: https://deepwiki.com/hypervel/support/9-utilities-and-helpers