Download the PHP package pavlyuts/php-string-key-arrays without Composer

Array-like class with only strings used as keys

Purpose

PHP arrays may be veery frustrating with it's mess in key string/integer and associated probems.

It was need to ensure the keys will work predictable as string, but the class still be used as a regular array with $a['key'] syntax, foreach use and all other staff. So, this what it do!

Installation

In the Composer storage. Just add proper require section:

"require": {
    "pavlyuts/php-string-key-arrays": "*"
}

I do not think there be a version compatibility problem as it is too simple thing and expected to be stable. However, I recommend to inspect CHANGELOG.md for changes.

Use

Basics

Basic use about the same as array but with some limitations described below.

Some useful functions also available in the section below

Examples

Limitations

• It will throw SKArrayException if you try to use null or empty string as a key. This mean $stringKeyArray[] = 'value'; is illegal
• By default it also will throw SKArrayException if you try to read an unknown key. Use $a = new SKArray(false) to change behaviour from exception to PHP notice and return null. Or, even better, use $var = $stringKeyArray[] ?? null; - this works fine.
• Indirect midification like $stringKeyArray['Level1Key']['Level2key'] = 'value'; will not work:
  • Will throw Exception/Notice for unknown key if the first key is not exist
  • If the key exist - no error but also no effect and PHP notice. Data will not change.

Useful functions

keys() aka array_keys()

Call of $stringKeyArray->keys() or it's synonym array_keys() returns keys as array of strings, same as PHP analogue.

values() aka array_values()

Call of $stringKeyArray->values() or it's synonym array_values() returns values as array of mixed, same as PHP analuue.

merge()

Merges another iterable into SKArray about the same way as array_merge(), but all kays handled as string type

column()

About the same like array_column but... a bit different!

it always returm SKArray class, containing the same string keys and result for each element's 'column' as:

• If the element is an array, it will try to retrive array value by key $column
• If the element is an object, then:
  • if property named $column exist, it will try to read it.
  • elseif method $column exist, it will try to call it unpacking all the next $args, like $element->$column(...$args)

The returned dataset will only include keys and values successfully retrieved, no nulls, no errors. If yo try to access protected method or property it will be silently passed without returning any result or any kind of problem indication.

setSubarrayItem()

Helper to work with SKArray elements type of array, do the same as illegal operaton $stringKeyArray['Level1Key']['Level2key'] = 'value'

If the element of SKArray collection at $offset is not an array or does not exist it will overwrite/create it as an empty array. Then, it will add to array, if key is given, it will add with $key, if null or missed - add as []

Testing

Was tested with PHPUnit 8.5 under PHP 7.2. The code is very simple so expected to work 7.x and up.

If you have doubts about your environment, install it with --dev composer optiion and then run composer test from library source root.