PHPackages mistralys/application-utils-collections - 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. mistralys/application-utils-collections ActiveLibrary[Utility & Helpers](/categories/utility) mistralys/application-utils-collections ======================================= Interfaces, traits and classes for handling static item collections, similar to Enums and with useful getter methods. 1.2.2(2mo ago)046.7k—2.8%5MITPHPPHP >=7.4 Since Oct 16Pushed 2mo ago2 watchersCompare [ Source](https://github.com/Mistralys/application-utils-collections)[ Packagist](https://packagist.org/packages/mistralys/application-utils-collections)[ RSS](/packages/mistralys-application-utils-collections/feed)WikiDiscussions main Synced 2d ago READMEChangelog (10)Dependencies (6)Versions (16)Used By (5) AppUtils - Collections ====================== [](#apputils---collections) Interfaces, traits and classes for handling item collections, similar to Enums but with useful getter methods. > This is part of the [Application Utils](https://github.com/Mistralys/application-utils) ecology. Feature Overview ---------------- [](#feature-overview) The collection classes come in several flavors: - Separate collections for records with string and integer IDs. - Class loader collections that instantiate classes from one or more folders. - Basket-like collections that allow freely adding and removing items. Basic Example ------------- [](#basic-example) Let's say you want to create a collection of herbs. A string-based collection is ideal in this case, each herb being an object that can easily be extended with additional properties and methods. ``` $basil = Herbs::getInstance()->getByID(Herbs::BASIL); echo $basil->getID(); // basil echo $basil->getName(); // Basil ``` ``` foreach(Herbs::getInstance()->getAll() as $herb) { echo $herb->getName(); } ``` The Principle ------------- [](#the-principle) The basic principle is to have a collection class for a data type, which knows all the possible values for that type, and a record class that represents a single value of that type. The collections and records are distinguished by the return type of their `getID()` method (`int` or `string`). Implementation -------------- [](#implementation) There are two ways to implement collections: 1. By extending the abstract base classes (e.g. `BaseStringPrimaryCollection`) 2. By implementing the interface and trait (e.g. `StringPrimaryCollectionTrait`) > The second way is useful when working with classes that already extend another class. The records have no abstract base class, only an interface that contains the `getID()` method with the relevant return type, e.g. `StringPrimaryRecordInterface`. Usage ----- [](#usage) There are example implementations of the string and integer collections in the unit test classes: ### Items with an integer-based ID [](#items-with-an-integer-based-id) - [Integer collection](tests/AppUtilsTestClasses/IntegerPrimaryCollectionImpl.php) - [Integer record](tests/AppUtilsTestClasses/IntegerPrimaryRecordImpl.php) - [Non-default-aware collection](tests/AppUtilsTestClasses/IntegerPrimaryCollectionNoDefaultImpl.php) ### Items with a string-based ID [](#items-with-a-string-based-id) - [String collection](tests/AppUtilsTestClasses/IntegerPrimaryCollectionImpl.php) - [String record](tests/AppUtilsTestClasses/IntegerPrimaryRecordImpl.php) - [Non-default-aware collection](tests/AppUtilsTestClasses/StringPrimaryCollectionNoDefaultImpl.php) ### Removing items from a collection [](#removing-items-from-a-collection) When extending `BaseStringPrimaryCollection` or `BaseIntegerPrimaryCollection`, you can remove registered items from within the subclass using the protected `unregisterItem()` method. It validates that the ID exists (throwing `RecordNotExistsException` if not) and returns `$this` for method chaining. ``` protected function removeObsoleteItem(string $id): self { return $this->unregisterItem($id); } ``` > NOTE: `unregisterItem()` is `protected` — it is intended for use within your subclass only, not as a public API. For publicly removable items, use a basket instead. ### Basket collections [](#basket-collections) These collections allow adding and removing items freely, similar to a basket. They do not contain a fixed set of items, but rather allow dynamically storing and retrieving items. - [String Basket](/src/Collections/StringPrimaryBasket.php) - [Integer Basket](/src/Collections/IntegerPrimaryBasket.php) These classes can be used without extending them, but can be extended to add custom functionality. ``` use AppUtils\Baskets\GenericIntegerPrimaryBasket; $products = GenericIntegerPrimaryBasket::create(); $products->addItem(new Product(289, 'Product A')); $products->addItem(new Product(290, 'Product B')); $products->removeItem(290); ``` ### Dynamic class loading [](#dynamic-class-loading) This specialized collection loads all classes from a folder that match a given interface or class name, instantiates them, and gives access to the resulting objects. Fueled by AppUtils' ClassHelper class loading mechanism, it is a powerful, fire-and-forget tool that helps with building dynamic applications. - [Class folder loading](tests/AppUtilsTestClasses/ClassLoaderCollectionImpl.php) - [Class folder loading (filtered)](tests/AppUtilsTestClasses/ClassLoaderCollectionInstanceOfImpl.php) - [Class folder loading (multiple folders)](tests/AppUtilsTestClasses/ClassLoaderCollectionMultiImpl.php) ### Events [](#events) Items in a collection are initialized on demand. To be able to react to this, the collections offer the `onItemsInitialized()` method, which can be used to register a listener that is called when the items are initialized. ``` use AppUtils\Collections\Events\ItemsInitializedEvent;use AppUtilsTestClasses\StringPrimaryCollectionImpl; $collection = new StringPrimaryCollectionImpl(); // Register listeners before accessing the items $collection->onItemsInitialized(function(ItemsInitializedEvent $event) : void { // Do something }); $collection->getAll(); // This, for example, will trigger the event ``` ### Health Score 48 — FairBetter than 93% of packages Maintenance85 Actively maintained with recent releases Popularity29 Limited adoption so far Community15 Small or concentrated contributor base Maturity51 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 ~65 days Recently: every ~72 days Total 15 Last Release 80d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/8895528?v=4)[Mistralys](/maintainers/Mistralys)[@Mistralys](https://github.com/Mistralys) --- Top Contributors [![Mistralys](https://avatars.githubusercontent.com/u/8895528?v=4)](https://github.com/Mistralys "Mistralys (109 commits)") --- Tags collectionsenumslibraryphpphp-library ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/mistralys-application-utils-collections/health.svg) ``` [![Health](https://phpackages.com/badges/mistralys-application-utils-collections/health.svg)](https://phpackages.com/packages/mistralys-application-utils-collections) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)