PHPackages cardinal-collections/array-with-secondary-keys - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. cardinal-collections/array-with-secondary-keys ActiveLibrary[Utility & Helpers](/categories/utility) cardinal-collections/array-with-secondary-keys ============================================== Array with Secondary Indexes v1.0.0(2y ago)18.1k↓34.6%1MITPHPPHP >=7.1 Since Jun 5Pushed 2y ago1 watchersCompare [ Source](https://github.com/vrza/array-with-secondary-keys)[ Packagist](https://packagist.org/packages/cardinal-collections/array-with-secondary-keys)[ RSS](/packages/cardinal-collections-array-with-secondary-keys/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (2)Versions (5)Used By (1) Array with Secondary Keys ========================= [](#array-with-secondary-keys) [![Build Status (GitHub Actions)](https://github.com/vrza/array-with-secondary-keys/actions/workflows/ci.yml/badge.svg)](https://github.com/vrza/array-with-secondary-keys/actions) Wraps a PHP array and maintains secondary lookup maps, for fast retrieval of items by nested field values. This is conceptually similar to how secondary keys in databases work. Features -------- [](#features) Implements `ArrayAccess`, `Iterator` and `Countable` interfaces, so you can use it like you would a standard PHP array: ``` $a[] = ['foo' => 'bar']; $value = $a[0]; unset($a[0]); count($a); foreach ($a as $key => $value); ``` Implemented in pure PHP. Secondary indexes are implemented as PHP associative arrays — hash tables with O(1) average lookup time. Since the secondary index is a hash index, its keys are by design unique. While it is possible to have the same secondary key value in multiple documents in the collection, in such cases the secondary key will get overwritten and will point to the last added/modified document. API Reference ------------- [](#api-reference) A "document" is the value associated to a primary key. It can be of any type. If the document is an array, secondary indexes can be specified using the "dot" notation. All created secondary key indexes are automatically updated when adding/removing/updating values. ### Constructor [](#constructor) ``` ArrayWithSecondaryKeys(array $array = []) ``` Creates a new `ArrayWithSecondaryKeys` collection, initialized from the given array. If called without arguments, an empty collection is created. containsPrimaryKey ------------------ [](#containsprimarykey) ``` containsPrimaryKey($key): bool ``` Checks if the specified primary key is present in the collection. containsSecondaryKey -------------------- [](#containssecondarykey) ``` containsSecondaryKey($index, $key): bool ``` Checks if the specified secondary key is present in the specified index. ### count [](#count) ``` count(): int ``` Returns the number of documents in the collection. ### get [](#get) ``` get($key, $default = null): mixed ``` Retrieves a document by key. If the key is given in "dot" notation, the corresponding nested part of the document is returned. If the key is not a string that includes a dot, it is treated as a primary key. ### has [](#has) ``` has($key): bool ``` Check if an item or items exist in the collection using "dot" notation. ### isEmpty [](#isempty) ``` isEmpty(): bool ``` Returns `true` if there are no primary keys in the collection, `false` otherwise. ### put [](#put) ``` put($key, $document): ArrayWithSecondaryKeys ``` Adds a new document to the collection under the given key. If the key is given in "dot" notation, and the top level primary key exists, a nested part is added to the existing document. If the key is not a string that includes a dot, it is treated as a primary key. ### add [](#add) ``` add($key, $document): ArrayWithSecondaryKeys ``` An alias for `put`. ### remove [](#remove) ``` remove($key): ArrayWithSecondaryKeys ``` Removes the document associated with the given primary key, or removes a nested part of the document if key is given in "dot" notation. If the key is given in "dot" notation, the corresponding nested part of the document is removed. If the key is not a string that includes a dot, it is treated as a primary key. ### updateSecondaryKey [](#updatesecondarykey) ``` updateSecondaryKey($index, $existingValue, $newValue) ``` Finds the document by existing value of secondary key and updates the existing value of secondary key in the document to new value. Returns the primary key of the updated document, or `null` if a document with existing value is not found. ### append [](#append) ``` append($document): ArrayWithSecondaryKeys ``` Appends a document (using `[]=`). ### createIndex [](#createindex) ``` createIndex($index) ``` Creates a new index and indexes existing documents. Index is given as string in "dot" notation (e.g. `state.pid`). ### getPrimaryKeyByIndex [](#getprimarykeybyindex) ``` getPrimaryKeyByIndex($index, $secondaryKey): mixed ``` Retrieves a primary key by secondary key. Index is given as string in "dot" notation (e.g. `state.pid`). Returns `null` if no document in collection matches the given secondary key. Throws `VladimirVrzic\ArrayWithSecondaryKeys\NoSuchIndexException` if the given index does not exist. ### getByIndex [](#getbyindex) ``` getByIndex($index, $secondaryKey, $default = null): mixed ``` Retrieves a document by index (secondary key). Index is given as string in "dot" notation (e.g. `state.pid`). Throws `VladimirVrzic\ArrayWithSecondaryKeys\NoSuchIndexException` if the given index does not exist. ### updateByIndex [](#updatebyindex) ``` updateByIndex($index, $secondaryKey, $document) ``` Updates a document by index (secondary key). Index is given as string in "dot" notation (e.g. `state.pid`). Throws `VladimirVrzic\ArrayWithSecondaryKeys\NoSuchIndexException` if the given index does not exist. Returns `true` if the existing document associated with the given secondary key was found and replaced. Returns `false` if the document associated with the given secondary key was not found. ### removeByIndex [](#removebyindex) ``` removeByIndex($index, $secondaryKey) ``` Removes a document by index (secondary key). Index is given as string in "dot" notation (e.g. `state.pid`). Throws `VladimirVrzic\ArrayWithSecondaryKeys\NoSuchIndexException` if the given index does not exist. Returns `true` if the document associated with the given secondary key was found and removed. Returns `false` if a document associated with the given secondary key was not found. ### putIfAbsent [](#putifabsent) ``` putIfAbsent($key, $document): mixed ``` If the key doesn’t exist, adds the new key associated with the given document and returns `null`. If the key exists, returns the current document. ### asArray [](#asarray) ``` asArray(): array ``` Returns a copy of the array as a normal PHP array (without secondary indexes). ### primaryKeys [](#primarykeys) ``` primaryKeys(): array ``` Returns an array of all primary keys. ### secondaryKeys [](#secondarykeys) ``` secondaryKeys($index): array ``` Returns an array of all secondary keys associated with the given index. Installation ------------ [](#installation) Assuming you have PHP Composer installed, and that the `composer` executable is in your `$PATH`: ``` composer require cardinal-collections/array-with-secondary-keys ``` Name ideas ---------- [](#name-ideas) - <\[associative\] array | map | dictionary> with secondary keys - multi-index <\[associative\] array | map | dictionary> ### Health Score 29 — LowBetter than 59% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity25 Limited adoption so far Community9 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~55 days Total 3 Last Release 783d ago Major Versions v0.9.1 → v1.0.02024-03-26 ### Community Maintainers ![](https://www.gravatar.com/avatar/b842fcccb4fa8eb90b6d6645e9fe1066b59ca01b3c38aa90c3b80a5ce07d02fe?d=identicon)[vrza](/maintainers/vrza) --- Top Contributors [![vrza](https://avatars.githubusercontent.com/u/1699472?v=4)](https://github.com/vrza "vrza (79 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/cardinal-collections-array-with-secondary-keys/health.svg) ``` [![Health](https://phpackages.com/badges/cardinal-collections-array-with-secondary-keys/health.svg)](https://phpackages.com/packages/cardinal-collections-array-with-secondary-keys) ``` ### Alternatives [php-lrpm/php-lrpm PHP Long Running Process Manager 187.8k1](/packages/php-lrpm-php-lrpm) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)