Control Flow Helpers

This document covers the control flow utility functions provided by the support package. These helpers facilitate common programming patterns including value transformation, conditional execution, retry logic, and exception handling. They enable more expressive and concise code when managing execution flow, handling optional values, and applying transformations.

For data manipulation functions like data_get() and data_set(), see Data Manipulation. For environment configuration helpers, see Environment Configuration. For the complete list of all helper functions, see Helper Functions.

Overview

The support package provides nine primary control flow helpers that fall into four categories:

Category	Functions	Purpose
Value Handling	value(), with(), optional()	Resolve values and handle null-safe access
Transformation	tap(), transform()	Apply operations while maintaining or transforming values
Execution Control	once(), retry()	Control how and when code executes
Conditional Exceptions	throw_if(), throw_unless(), when()	Throw exceptions based on conditions

All helpers are defined as global functions in src/helpers.php and are automatically available throughout the application.

Sources: src/helpers.php15-418 src/HigherOrderTapProxy.php1-11

Value Resolution: value()

The value() helper resolves a given value, automatically calling it if it's a callable. This provides a consistent way to handle values that may be static or dynamically computed.

Behavior

src/helpers.php15-22 defines the value() function which delegates to \Hypervel\Support\value():

• If the value is a Closure or callable, it is invoked with any additional arguments
• Otherwise, the value is returned as-is
• Supports variadic arguments that are passed through to callables

Usage Patterns

Sources: src/helpers.php15-22

Value Passing: with()

The with() helper provides a fluent way to work with values, optionally transforming them through a callback while maintaining clean, readable code.

Behavior

src/helpers.php344-351 defines with(), which delegates to \Hyperf\Support\with():

• When called with just a value, returns the value unchanged
• When called with a value and callback, passes the value to the callback and returns the callback's result
• Useful for inline transformations and method chaining

Usage Patterns

Sources: src/helpers.php344-351

Null-Safe Access: optional()

The optional() helper provides null-safe property and method access, preventing errors when working with potentially null values.

Behavior

src/helpers.php244-251 defines optional(), delegating to \Hyperf\Support\optional():

• Wraps a value to enable safe property/method access
• Returns null if the value is null, preventing null reference errors
• Can accept a callback that only executes if the value is not null

Usage Patterns

Sources: src/helpers.php244-251

Transformation Pipeline: tap()

The tap() helper enables side-effect operations on a value while returning the original value, facilitating debugging, logging, and object initialization without breaking method chains.

Behavior and Modes

src/helpers.php294-307 defines two modes of operation:

1. With callback: Executes the callback with the value, then returns the original value
2. Without callback: Returns a HigherOrderTapProxy that enables method chaining

HigherOrderTapProxy

src/HigherOrderTapProxy.php1-11 extends HyperfHigherOrderTapProxy to enable method chaining on the tapped value. When used without a callback, you can call methods on the returned proxy, and the original value will be returned.

Usage Patterns

Sources: src/helpers.php294-307 src/HigherOrderTapProxy.php1-11

Conditional Transformation: transform()

The transform() helper applies a transformation callback only when a value is "filled" (not blank), providing a clean way to conditionally process values.

Behavior

src/helpers.php326-341 implements the following logic:

1. Checks if the value is filled using filled() helper
2. If filled, applies the transformation callback
3. If not filled, returns the default value (optionally calling it if it's a callable)

Usage Patterns

Sources: src/helpers.php326-341

Memoization: once()

The once() helper ensures a callable is executed only once per unique call location, caching and returning the same result on subsequent calls. This is useful for expensive operations that should only run once.

Behavior and Implementation

src/helpers.php224-241 implements memoization using the backtrace to identify unique call locations:

1. Extracts calling context from debug_backtrace()
2. Creates an Onceable instance representing this unique call location
3. Uses the Once singleton to store and retrieve cached results
4. Returns cached result if available, otherwise executes callback and caches result

Supporting Classes

• Onceable src/helpers.php12: Represents a unique callable location derived from backtrace
• Once src/helpers.php11: Singleton that stores cached results keyed by Onceable instances

Usage Patterns

Call Location Identification

The helper uses debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT, 2) to identify the exact location where once() is called. This means the same once() call in different methods or classes will have separate caches.

Sources: src/helpers.php224-241

Retry Logic: retry()

The retry() helper attempts to execute a callback multiple times with configurable backoff strategies, catching exceptions and retrying until success or exhaustion of attempts.

Function Signature and Behavior

src/helpers.php254-291 provides flexible retry capabilities:

Execution Flow

Backoff Strategies

The helper supports multiple backoff strategies:

Strategy	Configuration	Behavior
No delay	$sleepMilliseconds = 0	Immediate retry
Fixed delay	$sleepMilliseconds = 1000	1 second between attempts
Dynamic delay	$sleepMilliseconds = fn($attempts) => $attempts * 1000	Increasing delay
Explicit backoff	$times = [100, 200, 500]	Specific delays per attempt

Sleep Implementation

src/helpers.php286 uses Sleep::usleep() which converts milliseconds to microseconds. The sleep duration can be:

• A static integer value
• A Closure that receives ($attempts, $exception) and returns milliseconds

Conditional Retry

The optional $when parameter src/helpers.php279 allows selective retry based on the exception:

Usage Patterns

Sources: src/helpers.php254-291

Conditional Exception Throwing

Three helpers provide expressive ways to throw exceptions based on conditions: throw_if(), throw_unless(), and when().

throw_if()

src/helpers.php354-377 throws an exception when a condition is truthy:

Behavior:

1. If $condition is truthy, throws the exception
2. Exception can be a string (class name), Throwable instance, or generic message
3. Returns the condition value if no exception is thrown

throw_unless()

src/helpers.php380-403 throws an exception when a condition is falsy:

Behavior:

1. If $condition is falsy, throws the exception
2. Same exception handling as throw_if()
3. Returns the condition value if no exception is thrown

Decision Tree

when()

src/helpers.php406-418 provides conditional value resolution:

Behavior:

1. Evaluates $expr using value() helper
2. If truthy, returns $value (calling it if it's a Closure)
3. If falsy, returns $default (calling it if it's a Closure)
4. If result is a Closure, calls it with $expr as argument

Usage Patterns

Sources: src/helpers.php354-418

Helper Function Reference Map

The following table maps each control flow helper to its location and key dependencies:

Helper	Location	Return Behavior	Dependencies
value()	src/helpers.php15-22	Resolves value or calls callable	\Hypervel\Support\value()
with()	src/helpers.php344-351	Returns value or callback result	\Hyperf\Support\with()
optional()	src/helpers.php244-251	Null-safe wrapper	\Hyperf\Support\optional()
tap()	src/helpers.php294-307	Returns original value	HigherOrderTapProxy
transform()	src/helpers.php326-341	Conditional transformation	filled(), value()
once()	src/helpers.php224-241	Memoized result	Onceable, Once
retry()	src/helpers.php254-291	Callback result or throws	Sleep, value()
throw_if()	src/helpers.php354-377	Condition or throws	None
throw_unless()	src/helpers.php380-403	Condition or throws	None
when()	src/helpers.php406-418	Conditional value	value()

Sources: src/helpers.php15-418

Common Usage Patterns

Fluent Method Chaining

Combine helpers to create expressive, fluent code:

Error Handling with Retry

Use retry() with conditional exception handling:

Initialization and Side Effects

Use tap() for object initialization without breaking fluent chains:

Defensive Programming

Use exception helpers for clear validation:

Sources: src/helpers.php15-418