Traits and Helpers

Traits and Helpers#

This page covers reusable building blocks outside the core helper classes:

  • DTOTrait for data-transfer object hydration

  • HookTrait for key-based get/set transforms

  • namespaced helper functions (autoloaded by default)

  • optional global helper functions from src/functions.php

DTOTrait#

Namespace: Infocyph\ArrayKit\traits\DTOTrait

Main methods:

  • create(array $values): static (static constructor)

  • fromArray(array $values): static (hydrate current instance)

  • hydrate(array $values, array $mapping = [], bool $coerce = false): static

  • hydrateNested(array $values, array $mapping = [], bool $coerce = false): static

  • toArray(): array (export public properties)

  • toArrayDeep(): array (recursive export)

  • replaceFromArray(array $values, array $mapping = [], bool $coerce = false): static

Basic DTO Flow#

<?php
use Infocyph\ArrayKit\traits\DTOTrait;

class UserDTO
{
    use DTOTrait;

    public string $name = '';
    public string $email = '';
    public int $age = 0;
}

$user = UserDTO::create([
    'name' => 'Alice',
    'email' => '[email protected]',
    'age' => 30,
]);

$arr = $user->toArray();

Incremental Hydration#

<?php
$user = new UserDTO();
$user->fromArray(['name' => 'Bob']);
$user->fromArray(['age' => 32]);

Unknown Keys#

Unknown keys are ignored (no dynamic properties are created):

<?php
$user = UserDTO::create([
    'name' => 'Alice',
    'unknown_field' => 'ignored',
]);

// toArray() contains only declared properties

HookTrait#

Namespace: Infocyph\ArrayKit\traits\HookTrait

Main methods:

  • onGet(string $offset, callable $callback): static

  • onSet(string $offset, callable $callback): static

HookTrait is used internally by:

  • Infocyph\ArrayKit\Collection\HookedCollection

  • Infocyph\ArrayKit\Config\Config

  • Infocyph\ArrayKit\Config\LazyFileConfig

HookedCollection Integration#

<?php
use Infocyph\ArrayKit\Collection\HookedCollection;

$c = new HookedCollection(['name' => 'alice']);

// get-time transform
$c->onGet('name', fn ($v) => strtoupper((string) $v));

// set-time transform
$c->onSet('role', fn ($v) => "Role: $v");

echo $c['name']; // ALICE
$c['role'] = 'admin';
echo $c['role']; // Role: admin

Config Integration#

<?php
use Infocyph\ArrayKit\Config\Config;

$config = new Config();
$config->onSet('user.email', fn ($v) => trim((string) $v));
$config->onGet('user.email', fn ($v) => strtolower((string) $v));

$config->setWithHooks('user.email', '  [email protected]  ');
echo $config->getWithHooks('user.email'); // [email protected]

Multiple Hooks on Same Key#

Hooks run in registration order:

<?php
$config->onSet('username', fn ($v) => trim((string) $v));
$config->onSet('username', fn ($v) => strtolower((string) $v));

$config->setWithHooks('username', '  ALICE  '); // becomes "alice"

Helper Functions#

By default, Composer autoloads the namespaced helper functions (Infocyph\ArrayKit\*). Global helper functions are optional.

Namespaced helpers (autoloaded):

  • Infocyph\ArrayKit\compare(mixed $retrieved, mixed $value, ?string $operator = null): bool

  • Infocyph\ArrayKit\array_get(array $array, int|string|array|null $key = null, mixed $default = null): mixed

  • Infocyph\ArrayKit\array_set(array &$array, string|array|null $key, mixed $value = null, bool $overwrite = true): bool

  • Infocyph\ArrayKit\collect(mixed $data = []): Collection

  • Infocyph\ArrayKit\chain(mixed $data): Pipeline

Optional global helpers (manual include):

  • compare(mixed $retrieved, mixed $value, ?string $operator = null): bool

  • array_get(array $array, int|string|array|null $key = null, mixed $default = null): mixed

  • array_set(array &$array, string|array|null $key, mixed $value = null, bool $overwrite = true): bool

  • collect(mixed $data = []): Collection

  • chain(mixed $data): Pipeline

To enable optional global helpers:

<?php
require_once __DIR__ . '/vendor/infocyph/arraykit/src/functions.php';

array_get / array_set#

<?php
use function Infocyph\ArrayKit\array_get;
use function Infocyph\ArrayKit\array_set;

$data = ['user' => ['name' => 'Alice']];

$name = array_get($data, 'user.name');            // Alice
$missing = array_get($data, 'user.email', 'n/a'); // n/a

array_set($data, 'user.email', '[email protected]');
array_set($data, [
    'user.role' => 'admin',
    'user.active' => true,
]);

collect / chain#

<?php
use function Infocyph\ArrayKit\chain;
use function Infocyph\ArrayKit\collect;

$c = collect([1, 2, 3, 4]);
$evens = $c->filter(fn ($v) => $v % 2 === 0)->all(); // [1 => 2, 3 => 4]

$sum = chain([1, 2, 3])->sum(); // 6

compare Helper#

<?php
use function Infocyph\ArrayKit\compare;

compare(10, 5, '>');   // true
compare(10, 10, '==='); // true
compare('5', 5, '!=='); // true
compare(10, 10);        // true (default ==)

When to Use These Helpers#

  • Use DTOTrait for lightweight request/response data objects.

  • Use HookTrait consumers when you need transparent value transforms.

  • Use namespaced helper functions by default; include global helpers only when explicitly desired.

Laravel Compatibility Layer#

ArrayKit also ships optional Laravel-style wrappers:

  • Infocyph\ArrayKit\LaravelCompat\Arr

  • Infocyph\ArrayKit\LaravelCompat\Collection

<?php
use Infocyph\ArrayKit\LaravelCompat\Arr;
use Infocyph\ArrayKit\LaravelCompat\Collection as CompatCollection;

$data = ['user' => ['name' => 'Alice']];
Arr::set($data, 'user.role', 'admin');
$name = Arr::get($data, 'user.name');

$c = new CompatCollection([1, 2, 3]);
$all = $c->all();