overthink / array-item

v1.0.0 2026-09-01 09:41 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^10.48
• illuminate/support: ^10.48
• spatie/laravel-package-tools: ^1.14.0

Requires (Dev)

• ext-intl: *
• laravel/pint: ^1.0
• nunomaduro/collision: ^7.8
• nunomaduro/larastan: ^2.0.1
• orchestra/testbench: ^8.8
• pestphp/pest: ^2.20
• pestphp/pest-plugin-arch: ^2.0
• pestphp/pest-plugin-laravel: ^2.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• spatie/laravel-ray: ^1.26

Suggests

• ext-intl: Required to use Number::spell(), Number::ordinal(), Number::currency() and Number::percentage().

MIT

• Marko Zagar

• laravel
• overthink
• array-item

Published on Packagist.org on 2026-09-01 09:41 UTC

README

A fluent, typed accessor for reading and manipulating array data in Laravel apps. Wrap any array (API response, JSON column, config, ...) in an ArrayItem to get dot-notation access, typed getters (string, float, date, number, collection, JSON), and a small set of array manipulation helpers, without giving up ArrayAccess.

Requirements

• PHP ^8.3
• Laravel ^11.0 || ^12.0 || ^13.0

Need Laravel 10 / PHP 8.2? Use ^1.0 instead — it won't get new features, but it's still there.

Installation

You can install the package via composer:

composer require overthink/array-item

You can publish the config file with:

php artisan vendor:publish --tag="array-item-config"

Usage

use Overthink\ArrayItem\ArrayItem;

$item = ArrayItem::make([
    'name' => 'Widget',
    'price' => '1.234,56',
    'created_at' => '10.10.2020',
    'meta' => ['color' => 'red'],
]);

$item->get('name');                 // 'Widget'
$item->get('missing', 'default');   // 'default'
$item->getOr('missing', fn () => 'computed'); // 'computed'
$item->has('meta.color');           // true

$item->string('name');              // Illuminate\Support\Stringable
$item->float('price');              // 1234.56
$item->number('price')->currency(); // '€1,234.56'
$item->numberFormat('price');       // '1234,56'
$item->collect('meta');             // Illuminate\Support\Collection

$item->date('created_at');                  // Carbon\Carbon
$item->dateFormat('created_at', 'Y-m-d');    // '2020-10-10'
$item->timestamp('created_at');              // Carbon\Carbon (unix timestamp input)

$item->set('meta.size', 'M');
$item->merge(fn ($item) => ['extra' => true]);
$item->only(['name', 'price']);
$item->remove('meta');

$item['name'];                       // ArrayAccess is supported too
$item->toArray();
$item->toCollection();
$item->toJson();

Available methods

Method	Description
make(array|ArrayItem $attributes = [])	Create a new instance (static).
default(array $attributes): array	Overridable hook to seed default attributes on construction.
get(string|callable $key, mixed $default = null)	Dot-notation get, or resolve a callable against the item.
getOr(string|callable $key, mixed $default = null)	Like get(), but falls back to $default when the value is empty().
has(string $key): bool	Dot-notation existence check.
set(string|callable $key, mixed $value = null, bool $merge = false)	Dot-notation set; a callable replaces (or merges into) all attributes.
merge(string|callable $key, mixed $value = null)	Shorthand for set(..., merge: true).
only(string|array|Collection $keys)	Keep only the given keys (supports ['from' => 'to'] remapping).
remove(string|array|Collection $keys)	Remove the given keys.
string(string|callable $key, string $default = '')	Get the value as an Illuminate\Support\Stringable.
float(string|callable $key, ?string $default = null): float	Parse the value as a float, handling "1.234,56"-style European numbers.
number(string|callable $key, ?string $default = null): Number	Get the value wrapped in a Number helper (see below).
numberFormat(string|callable $key, ?int $decimals, ?string $decimalSeparator, ?string $thousandsSeparator, ?string $default): string	number_format() over float(), using the static defaults below when omitted.
collect(string|callable $key, mixed $default = []): Collection	Get the value as a Collection.
json(string|callable $key, mixed $default = null): mixed	json_decode() the value.
jsonItem(string|callable $key, mixed $default = null): ArrayItem	Decode the value and wrap it in a new ArrayItem.
date(string|callable $key, ?string $default = null): ?Carbon	Parse the value as a Carbon date.
dateFrom(string|callable $key, string $from, ?string $default = null): ?Carbon	Parse the value with an explicit input format.
dateFormat(string|callable $key, ?string $format = null, ?string $default = null): ?string	Format a date value, defaulting to static::$dateFormat.
timestamp(string|callable $key, ?string $default = null): ?Carbon	Parse the value as a unix timestamp.
timestampFormat(string|callable $key, ?string $format = null, ?string $default = null): ?string	Format a timestamp value, defaulting to static::$dateFormat.
convert(string|callable $key, Convertable $converter, mixed $default = null)	Pass the value through a custom Convertable implementation.
getAttributes(): array / toArray(): array	Get the raw underlying array.
toCollection(): Collection	Get the underlying array as a Collection.
toJson($options = 0): string / __toString()	JSON-encode the item.

ArrayItem also implements ArrayAccess ($item['key']), Illuminate\Contracts\Support\Arrayable, Jsonable, JsonSerializable, and uses Laravel's Conditionable (when()/unless()) and Macroable traits.

Conditionable

Conditionally apply logic while staying in the fluent chain:

$item = ArrayItem::make(['name' => 'Widget', 'stock' => 0])
    ->when($item->get('stock') === 0, fn (ArrayItem $item) => $item->set('status', 'out_of_stock'))
    ->unless($item->has('sku'), fn (ArrayItem $item) => $item->set('sku', 'N/A'));

Macroable

Register your own methods on ArrayItem at boot time:

use Overthink\ArrayItem\ArrayItem;

ArrayItem::macro('isOutOfStock', function () {
    /** @var ArrayItem $this */
    return $this->get('stock') === 0;
});

$item->isOutOfStock(); // bool

Static configuration, shared across all instances:

ArrayItem::$dateFormat = 'd.m.Y';
ArrayItem::$decimals = 2;
ArrayItem::$decimalSeparator = ',';
ArrayItem::$thousandsSeparator = '';

Number

ArrayItem::number() returns an Overthink\ArrayItem\Number instance, a thin wrapper around Illuminate\Support\Number:

$item->number('price')->format();       // '1,234.56'
$item->number('price')->currency();     // '€1,234.56' (defaults to EUR)
$item->number('price')->percentage();
$item->number('price')->abbreviate();
$item->number('price')->spell();        // requires ext-intl
$item->number('price')->ordinal();      // requires ext-intl

convert() and Convertable

Custom conversion logic can be plugged in via the Convertable interface:

use Overthink\ArrayItem\Convertable;

class UppercaseConverter implements Convertable
{
    public function convert(mixed $value): mixed
    {
        return mb_strtoupper($value);
    }
}

$item->convert('name', new UppercaseConverter()); // 'WIDGET'

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Marko Zagar
• All Contributors

License

The MIT License (MIT). Please see License File for more information.