Data Manipulation

This page documents the data manipulation helper functions for accessing, modifying, and removing values in nested arrays and objects using dot notation. These helpers provide a consistent, expressive API for working with deeply nested data structures without verbose array index checking or property existence validation.

For general helper functions, see Helper Functions. For collection operations, see Collections.

Overview

The hypervel/support package provides five core data manipulation helpers that operate on nested arrays and objects:

Function	Purpose	Overwrite Behavior
data_get()	Retrieve values from nested structures	N/A (read-only)
data_set()	Set values in nested structures	Overwrites by default
data_fill()	Set values only if missing	Never overwrites
data_forget()	Remove values from nested structures	N/A (deletion)
object_get()	Retrieve values from nested objects	N/A (read-only)

These functions use "dot notation" to specify paths through nested data structures, allowing expressions like 'user.address.city' instead of verbose array access chains.

Sources: src/helpers.php112-150 src/helpers.php202-222

Data Manipulation Function Ecosystem

Sources: src/helpers.php112-150 src/helpers.php202-222

Dot Notation Syntax

All data manipulation helpers use dot notation to specify paths through nested structures. The dot (.) character separates levels of nesting:

Notation	Meaning
'name'	Top-level key 'name'
'user.name'	Key 'name' inside 'user'
'users.0.name'	Key 'name' in first element of 'users' array
'config.database.connections.mysql.host'	Deep nesting through multiple levels

The notation works with:

• Associative arrays: $array['user']['name']
• Numeric arrays: $array['users'][0]['name']
• Objects: $object->user->name
• Mixed structures: $array['user']->address['city']

Dot Notation Resolution Flow:

Sources: src/helpers.php122-130 src/helpers.php202-222

data_get: Reading Nested Data

The data_get() function retrieves values from nested arrays or objects using dot notation.

Function Signature

Parameters:

Parameter	Type	Description
$target	mixed	The array, object, or ArrayAccess instance to search
$key	array|int|string|null	Dot notation path or array of paths; null returns entire target
$default	mixed	Value to return if key doesn't exist; supports closures

Usage Examples

Basic array access:

Numeric array indices:

Object property access:

Multiple keys (returns array):

Null key returns entire target:

Implementation Details

The function delegates to \Hyperf\Collection\data_get() which:

1. Returns the entire target if key is null or empty string
2. Handles array of keys by recursively calling itself
3. Uses wildcard (*) support for accessing all items at a level
4. Evaluates closure defaults with the target as argument
5. Supports ArrayAccess implementations

Sources: src/helpers.php122-130

data_set: Writing Nested Data

The data_set() function sets values in nested arrays or objects, creating intermediate structures as needed.

Function Signature

Parameters:

Parameter	Type	Description
$target	mixed	Array or object to modify (passed by reference)
$key	array|string	Dot notation path or array of paths
$value	mixed	Value to set
$overwrite	bool	Whether to overwrite existing values (default: true)

Usage Examples

Basic nested array creation:

Deep nesting with auto-creation:

Array index assignment:

Object property modification:

Overwrite control:

Multiple keys:

Implementation Details

The function delegates to \Hyperf\Collection\data_set() which:

1. Splits the dot notation path into segments
2. Traverses existing structure, creating missing levels
3. Creates arrays for numeric keys, objects for string keys
4. Respects the $overwrite parameter to preserve existing values
5. Handles ArrayAccess implementations
6. Returns the modified target

Sources: src/helpers.php132-140

data_fill: Conditional Writing

The data_fill() function sets values in nested structures only if the key doesn't already exist or is null.

Function Signature

Parameters:

Parameter	Type	Description
$target	mixed	Array or object to modify (passed by reference)
$key	array|string	Dot notation path or array of paths
$value	mixed	Value to set if key is missing

Usage Examples

Fill missing values:

Nested structure initialization:

Default value population:

Implementation Details

The function is implemented as a wrapper around data_set() with $overwrite set to false:

This means it inherits all the behavior of data_set() including:

• Creating nested structures for missing paths
• Supporting both arrays and objects
• Handling multiple keys
• ArrayAccess support

Sources: src/helpers.php112-120

data_forget: Removing Nested Data

The data_forget() function removes values from nested arrays or objects using dot notation.

Function Signature

Parameters:

Parameter	Type	Description
$target	mixed	Array or object to modify (passed by reference)
$key	array|int|string|null	Dot notation path or array of paths to remove

Usage Examples

Basic key removal:

Nested key removal:

Array element removal:

Multiple keys:

Object property removal:

Implementation Details

The function delegates to \Hyperf\Collection\data_forget() which:

1. Splits the dot notation into segments
2. Traverses to the parent of the target key
3. Unsets the final segment using unset() or property deletion
4. Handles arrays, objects, and ArrayAccess implementations
5. Gracefully handles non-existent paths (no error)
6. Returns the modified target

Sources: src/helpers.php142-150

object_get: Object-Specific Access

The object_get() function provides a specialized helper for accessing nested object properties using dot notation, with a custom implementation.

Function Signature

Parameters:

Parameter	Type	Description
$object	object	The object to traverse
$key	string|null	Dot notation path; null returns entire object
$default	mixed	Value to return if property doesn't exist

Usage Examples

Basic object access:

Null key behavior:

Missing property handling:

Implementation Details

Unlike the other data helpers, object_get() has its own implementation in the codebase:

Algorithm:

1. If key is null or empty string, return the entire object
2. Split key by . into segments
3. For each segment:
   • Check if current value is an object
   • Check if property exists on object
   • If either fails, return the default value
   • Otherwise, traverse to that property
4. Return the final value

Key difference from data_get():

• Only works with objects (not arrays or ArrayAccess)
• Uses isset($object->{$segment}) for property checks
• Direct property access via $object->{$segment}
• Evaluates closure defaults with the target as argument via value($default)

Sources: src/helpers.php202-222

Comparison of Data Manipulation Functions

Sources: src/helpers.php112-150 src/helpers.php202-222

Common Use Cases

Configuration Management

API Response Processing

Request Data Manipulation

Model Data Transformation

Dynamic Form Processing

Session Data Management

Sources: src/helpers.php112-150 src/helpers.php202-222

Performance Considerations

Delegation to Hyperf

Most data manipulation functions delegate to Hyperf's implementation in \Hyperf\Collection namespace:

Function	Implementation
data_get()	Delegates to \Hyperf\Collection\data_get()
data_set()	Delegates to \Hyperf\Collection\data_set()
data_fill()	Delegates to \Hyperf\Collection\data_set() with overwrite=false
data_forget()	Delegates to \Hyperf\Collection\data_forget()
object_get()	Custom implementation in hypervel/support

This delegation means:

• Performance characteristics depend on Hyperf's implementation
• Bug fixes and optimizations in Hyperf automatically benefit these helpers
• The API remains stable across Hyperf versions

When to Use Each Function

Use data_get() when:

• Reading from arrays, objects, or mixed structures
• You need wildcard support (*)
• Default values are required
• The key might not exist

Use data_set() when:

• Creating or modifying nested structures
• You need control over overwrite behavior
• Working with dynamic paths

Use data_fill() when:

• Setting default values only
• Preserving existing data is critical
• Initializing configuration or session data

Use data_forget() when:

• Removing sensitive data
• Cleaning up temporary values
• Deleting nested keys

Use object_get() when:

• Working exclusively with objects (not arrays)
• You prefer the specialized object-only implementation
• Reading properties without modification

Sources: src/helpers.php112-150 src/helpers.php202-222

Related Functions

The data manipulation helpers work alongside other utility functions:

• value() - Used internally by several helpers to evaluate closures; see Control Flow Helpers
• collect() - Create Collection instances which have similar methods; see Collections
• blank() / filled() - Check if values are empty before manipulation; see Helper Functions
• transform() - Apply transformations to values conditionally; see Control Flow Helpers
• tap() - Modify data and return original; see Control Flow Helpers

Sources: src/helpers.php15-351