Download the PHP package sbwerewolf/language-specific without Composer

Safe PHP Arrays

Read nested arrays safely and cast values predictably in PHP 8.4+

Use it when you need to:

• read nested arrays without long isset() (??) chains
• normalize request/config payloads with explicit defaults
• keep the “missing value” state visible instead of leaking null everywhere

Install

Quick example

Code test coverage

Quick navigation

• Killer features
• AdvancedArray
• CommonValue
• ArrayFactory
• CommonArray
• BaseArray
• Factory helpers
• Native PHP interfaces
• Run tests

Killer features

1. Safe nested config access

Use AdvancedArray when you need to walk through deeply nested arrays without isset() chains and still keep explicit control over missing values.

Continue with AdvancedArray.

2. HTTP payload parsing

Use CommonValue conversions to normalize request payloads without sprinkling casts across the whole handler.

Continue with CommonValue.

3. Legacy arrays normalization

Use factories to turn inconsistent old-style data into one predictable API.

Continue with CommonArray.

AdvancedArray

Back to killer features.

Create an AdvancedArray with makeAdvancedArray()

Use AdvancedArrayFactory as the main entry point for nested data.

pull() returns a nested AdvancedArrayInterface

pull() can return the first nested array or a specific nested array by key.

isDummy() marks a missing nested array

Missing nested arrays return a dummy object instead of throwing or leaking null.

get() reads a value and keeps the missing-state visible

get() returns a CommonValueInterface, so you can inspect both the value and whether the key was actually present.

getAny() returns the first value or a dummy for an empty collection

Use getAny() when any first available value is good enough.

has() checks a specific key

Use has() when you want to know whether a given key exists before reading it.

hasAny() checks whether the collection is not empty

Use hasAny() when you only care whether there is at least one item.

arrays() iterates over nested arrays only

This is useful when you need to process nested lists without checking each item.

values() iterates over non-array elements only

This is useful when the collection mixes nested arrays with plain scalar values.

CommonValue

Back to killer features.

asIs() returns the stored value exactly as it is

Use asIs() when you want the original stored value without casting.

isReal() and default() make missing-state explicit

Use default() only for missing values; real values stay untouched.

Scalar casts stay close to native PHP casting rules

Use the typed helpers when you want the cast at the point of reading.

array() turns the current value into an array

This is especially useful when you want one array-shaped read path.

object() returns the stored object value

When the stored value is already an object, object() returns it unchanged.

type() shows all native gettype() results used by this library

This example is meant to be read without running it, so every visible result is listed explicitly.

class() shows all native get_debug_type() results used by this library

This example includes scalars, arrays, named classes, anonymous classes, resources, and closed resources.

ArrayFactory

Back to killer features.

makeBaseArray() wraps any value into a predictable iterable array object

Use BaseArray when you only need the raw iterable container behavior.

makeCommonArray() adds get() and has() on top of the same normalized data

Use CommonArray when the data is mostly flat and you want value wrappers.

CommonArray

Back to killer features.

get() reads a specific value

get() returns a CommonValueInterface, so missing keys stay observable.

getAny() returns the first value or a dummy for an empty collection

This is the flat-array equivalent of AdvancedArray::getAny().

has() checks a specific key

Use it when you want a lightweight presence check before reading the value.

hasAny() checks whether the collection is not empty

Use it when you only need to know whether the collection contains any item.

BaseArray

Back to killer features.

raw() returns the original normalized array

Use raw() when you need the plain array back without wrappers.

Factory helpers

Back to killer features.

makeDummyAdvancedArray() creates a missing nested-array placeholder

Use it when you need a manual dummy object that behaves like a missing nested array.

makeCommonValue() wraps any value into a CommonValueInterface

Use it when you want the value-wrapper behavior without creating an array object.

makeCommonValueAsDummy() creates a missing-value placeholder

Use it when the missing-state itself is part of the control flow.

Native PHP interfaces

Back to killer features.

These features are convenient, but they are not the main reason to use the library.

Read values with []

Iterate with foreach

Serialize the whole object with json_encode()

Run tests

Documentation examples are executable in:

• tests/unit/DocumentationExamplesTest.php

Contacts

• Telegram chat with me
• WhatsApp chat with me