README

A PHP utility class for manipulating nested arrays using dot notation.

Features

• 🎯 Dot Notation: Access nested array values with simple dot notation (user.profile.name)
• 🔢 Numeric Keys: Work seamlessly with array indices
• 🔄 Bulk Operations: Set multiple values at once with merge support
• 🎨 Typed Getters: Type-safe retrieval with getBool(), getInt(), getArray()
• 🔗 Method Chaining: Fluent interface for elegant code
• 🎭 Null Handling: Optional null value preservation
• ✅ Type Safe: Full PHP 8.0+ type declarations

Installation

composer require jdz/data

Requirements

• PHP 8.0 or higher

Quick Start

use JDZ\Utils\Data;

$data = new Data();

// Set values using dot notation
$data->set('user.name', 'John Doe');
$data->set('user.email', 'john@example.com');
$data->set('user.settings.theme', 'dark');

// Get values
echo $data->get('user.name'); // "John Doe"
echo $data->get('user.age', 30); // 30 (default value)

// Check existence
if ($data->has('user.email')) {
    echo "Email exists!";
}

// Work with arrays
$data->set('users.0.name', 'John');
$data->set('users.1.name', 'Jane');

// Get typed values
$isActive = $data->getBool('user.active', true);
$count = $data->getInt('user.login_count', 0);
$tags = $data->getArray('user.tags', []);

Documentation

Setting Values

set(string $path, mixed $value): self

Set a single value using dot notation.

$data->set('app.name', 'MyApp');
$data->set('app.version', '1.0.0');
$data->set('config.database.host', 'localhost');

sets(array $data, bool $merge = true): self

Set multiple values at once.

// Merge with existing data
$data->sets([
    'api.endpoint' => 'https://api.example.com',
    'api.timeout' => 30,
], true);

// Set without merging
$data->sets([
    'config.debug' => true,
], false);

Getting Values

get(string $path, mixed $default = null): mixed

Get a value with an optional default.

$name = $data->get('user.name');
$country = $data->get('user.country', 'USA');

getBool(string $path, bool $default = false): bool

Get a boolean value. Converts 1, '1', and true to true.

$isEnabled = $data->getBool('features.api');
$hasAccess = $data->getBool('user.premium', false);

getInt(string $path, int $default = 0): int

Get an integer value with automatic type conversion.

$timeout = $data->getInt('config.timeout');
$retries = $data->getInt('config.retries', 3);

getArray(string $path, array $default = []): array

Get an array value. Non-array values are cast to arrays.

$tags = $data->getArray('post.tags');
$items = $data->getArray('list.items', ['default']);

Checking and Removing

has(string $path): bool

Check if a key exists.

if ($data->has('user.email')) {
    // Email is set
}

erase(string $path): self

Remove a value.

$data->erase('user.temporary_token');
$data->erase('cache.expired');

def(string $path, mixed $default = ''): self

Set a value only if it doesn't already exist.

$data->def('config.timeout', 30); // Sets if not exists
$data->def('config.retries', 3);  // Sets if not exists

Utility Methods

all(): array

Get all data as an array.

$allData = $data->all();

preserveNulls(bool $preserve = true): self

Enable or disable null value preservation.

$data->preserveNulls(true);
$data->set('user.optional', null); // Null is preserved

Working with Arrays

Access array elements using numeric keys:

$data->set('items.0', 'First');
$data->set('items.1', 'Second');
$data->set('items.2', 'Third');

echo $data->get('items.0'); // "First"

Build complex structures:

$data->set('users.0.name', 'John');
$data->set('users.0.email', 'john@example.com');
$data->set('users.1.name', 'Jane');
$data->set('users.1.email', 'jane@example.com');

$users = $data->getArray('users');
// [
//   ['name' => 'John', 'email' => 'john@example.com'],
//   ['name' => 'Jane', 'email' => 'jane@example.com']
// ]

Method Chaining

All mutating methods return $this for fluent chaining:

$config = (new Data())
    ->set('app.name', 'MyApp')
    ->set('app.version', '1.0.0')
    ->def('app.debug', false)
    ->def('app.timeout', 30)
    ->erase('app.temporary');

Examples

See the examples directory for detailed examples:

• 01-basic-usage.php - Basic operations
• 02-typed-getters.php - Typed getter methods
• 03-array-keys.php - Working with arrays
• 04-bulk-operations.php - Bulk setting operations
• 05-erase-and-def.php - Removing and defaulting values
• 06-null-handling.php - Null value handling
• 07-method-chaining.php - Method chaining examples

Run example:

php examples/01-basic-usage.php

Testing

Run all tests:

composer test
# or
vendor/bin/phpunit

Run tests with coverage report (HTML):

composer test-coverage
# Coverage report will be generated in the coverage/ directory

License

This project is licensed under the MIT License - see the LICENSE file for details.