PHPackages                             yomy/datastructures - 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. yomy/datastructures

ActiveLibrary[Utility & Helpers](/categories/utility)

yomy/datastructures
===================

Data structures

1.1(5y ago)015.9k↓80%1Apache-2.0PHPPHP >=7.0CI failing

Since Oct 15Pushed 5y ago1 watchersCompare

[ Source](https://github.com/yomy/datastructures)[ Packagist](https://packagist.org/packages/yomy/datastructures)[ Docs](https://github.com/yomy/datastructures)[ RSS](/packages/yomy-datastructures/feed)WikiDiscussions master Synced 4d ago

READMEChangelog (3)Dependencies (1)Versions (5)Used By (0)

datastructures
==============

[](#datastructures)

Common data structures for PHP

[![Build Status](https://camo.githubusercontent.com/329b3b20a6e411b99ba4783e8d9746e9d00552203778b23d94d8400915f3078d/68747470733a2f2f7472617669732d63692e6f72672f796f6d792f64617461737472756374757265732e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/yomy/datastructures)

Installation and documentation
------------------------------

[](#installation-and-documentation)

- Available as \[Composer\] package \[yomy/datastructures\].

What is this library about
--------------------------

[](#what-is-this-library-about)

This library adds data structure classes that can be used for better organisation of your objects

Examples of value object
------------------------

[](#examples-of-value-object)

Creating an object:

```
use YomY\DataStructures\ValueObject\ValueObject;
$object = ValueObject::instance(1);
```

Getting value from the object

```
$value = $object->getValue();
```

Objects with the same value are going to be the same object

```
$object1 = ValueObject::instance(1);
$object2 = ValueObject::instance(1);
//These two are the same objects ($object1 === $object2)
```

You can use type hinting in methods

```
public function doSomething(ValueObject $valueObject) {
    $value = $valueObject->getValue();
    ...
}
```

You can extend the object for more detailed type hinting

```
class UserId extends ValueObject {}
class DataId extends ValueObject {}
...
public function doSomething(UserId $userId, DataId $dataId) {
    ...
}
```

Objects of different class or variable type are different

```
$object1 = ValueObject::instance('');
$object2 = ValueObject::instance(null);
$object3 = ValueObject::instance(false);
$object4 = ExtendedValueObject::instance('');
$object5 = ExtendedValueObject::instance(null);
$object6 = ExtendedValueObject::instance(false);
//All of the above are different
```

Instead of a strong (===) comparison operator, you could also use the equals() method

```
$object1 = ValueObject::instance(1);
$object2 = ValueObject::instance(1);
$same = $object1->equals($object2); //true
```

Generally, unserialize of a value object is prohibited, as this would break the ability to compare objects by reference. However, you might have a case you don't care about strict comparison, and need to unserialize the object. You can add a WeakValueObjectTrait usage to your custom object, which will allow unserializing it, and also compare objects by the values instead of reference when using equals() method

```
class MyWeakObject extends ValueObject {
    use WeakValueObjectTrait;
}
...
$weakObject1 = MyWeakObject::instance(1);
$serializedWeakObject = serialize($weakObject1);
$weakObject2 = unserialize($serializedWeakObject);
//These two objects are "equal" but not the same
$weakObject1->equals($weakObject2); //true
//On regular value objects this would be false
```

Examples of Enum value object
-----------------------------

[](#examples-of-enum-value-object)

Creating an enum object

```
use YomY\DataStructures\ValueObject\EnumValueObject;
class Category extends EnumValueObject {
    const FIRST = 1;
    const SECOND = 2;
    const THIRD = 3;
}
```

Creating enum objects

```
$category = Category::instance(Category::FIRST);
```

or by referring referring to key

```
$category = Category::FIRST();
```

You will get an error if you try to instantiate invalid value

```
$category = Category::instance('missing_value');
$category = Category::MISSING();
```

Examples of Positive Integer value object
-----------------------------------------

[](#examples-of-positive-integer-value-object)

As value objects are commonly used as identifiers for database entities with an integer key, positive int value object ensures a valid key object for this purpose

Creating an object:

```
use YomY\DataStructures\ValueObject\PositiveIntValueObject;
$object1 = PositiveIntValueObject::instance(1);
$object2 = PositiveIntValueObject::instance('1');
//These two are the same objects ($object1 === $object2)
```

Usually, the id key in the db cannot be a 0, so these objects are invalid:

```
$object = PositiveIntValueObject::instance(0);
$object = PositiveIntValueObject::instance('0');
```

Of course, as with a basic value object, it is intended to use these in extended classes.

```
class UserId extends PositiveIntValueObject {}
class DataId extends PositiveIntValueObject {}
$user = UserId::instance(42);
$data = DataId::instance(42);
//these two are not the same
```

Examples of GenericCollection usage
-----------------------------------

[](#examples-of-genericcollection-usage)

Creating a collection object:

```
use YomY\DataStructures\Collection\GenericCollection;
$collection = new GenericCollection();
```

Adding objects to the collection

```
$collection->add(1);
$collection->add(2);
$collection->add(3);
$collection->add('string');
$collection->add(true);
$collection->add(false);
$collection->add(null);
$collection->add($anObject);
$collection->add(['an', 'array']);
```

You could also add objects by using array syntax

```
$collection[] = 1;
```

Objects can be added multiple times

```
$collection->add(1);
$collection->add(1);
$collection->add(1);
```

Collection supports adding an array of values at once

```
$values = [1, 2, 3];
$collection->addArray($values);
```

Removing objects from a collection - removes all occurrences of the object

```
$collection->remove(1);
```

Getting objects from the collection

```
$objects = $collection->getAll();
```

Note that you ***cannot*** get objects with array syntax

```
$object = $collection[3]; //This will throw an exception
```

You can also iterate trough the collection itself

```
foreach ($collection as $object) {
    ...
}
```

Count the number of objects in a collection

```
$count = $collection->count();
```

Verify that the collection is empty

```
$empty = $collection->isEmpty();
```

Verify that the collection contains an object

```
$contains = $collection->contains(1);
```

You can shallow copy the collection

```
$copy = $collection->copy();
```

You can append another collection to the collection

```
$collection->append($collection2);
//$collection now has gets items from $collection2 along it's own items
```

Collection supports custom sort of its objects.

```
$values = [9, 8, 7, 6, 5, 4, 3, 2, 1];
$collection = new GenericCollection();
$collection->addArray($values);
$collection->sort(function($object1, $object2) {
    return $object1 > $object2;
});
//Collection will now have an array like
//[1, 2, 3, 4, 5, 6, 7, 8, 9];
```

Collection can be filtered to get a new collection with filtered objects

```
$values = [1, 2, 3, 4, 5, 6, 7, 8, 9];
$collection = new GenericCollection();
$collection->addArray($values);
$filtered = $collection->filter(function($object) {
    return $object > 5;
});
//$filtered contains [6, 7, 8, 9]
//original collection is not affected
```

Collection can be transformed to array with a callback method. This allows extracting underlying data from objects or doing custom calculations

```
$values = [1, 2, 3, 4, 5, 6, 7, 8, 9];
$collection = new GenericCollection();
$collection->addArray($values);
$transformed = $collection->transformToArray(function($object) {
    //Here we decide what to return in place of each item
    return new CustomWrapper($object);
});
```

Collection can be transformed (appended) to another collection

```
$values = [1, 2, 3, 4, 5, 6, 7, 8, 9];
$collection = new GenericCollection();
$collection->addArray($values);
$destinationCollection = new GenericCollection();
$destinationCollection->addArray($values);
$collection->transformToCollection($destinationCollection);
//$destinationCollection now has appended items from $collection
```

Examples of ObjectCollection usage
----------------------------------

[](#examples-of-objectcollection-usage)

ObjectCollection is an extension of GenericCollection that is intended to contain only objects of specific class.

Creating an ObjectCollection of specific type

```
$objectCollection = new ObjectCollection(ExampleObject1::class);
```

All of the methods from GenericCollection work almost the same, except for the fact that only objects of the exact type that was passed in the Collection constructor are allowed.

```
$objectCollection = new ObjectCollection(ExampleObject1::class);
$objectCollection->add(new ExampleObject1());
```

Trying to add an object of wrong type will throw an InvalidArgumentException

```
$objectCollection = new ObjectCollection(ExampleObject1::class);
$objectCollection->add(new DifferentObject());
//This will throw an InvalidArgumentException
```

Collection will work with extended objects as well

```
class ExtendedExampleObject1 extends ExampleObject1 {}
$objectCollection = new ObjectCollection(ExampleObject1::class);
$objectCollection->add(new ExampleObject1());
$objectCollection->add(new ExtendedExampleObject1());
```

The primary intent of the ObjectCollection is to have a custom named collection

```
class User {...}
class UserCollection extends ObjectCollection {
    public function __construct() {
        parent::__construct(User::class);
    }
}
```

Having a collection such as this allows for type hinting in the code and we're sure that a collection only consists of objects of specific type

```
function someMethod(UserCollection $userCollection) {
    foreach ($userCollection as $user) {
        //Here we can use individual users from collection
    }
}

...

$userCollection = new UserCollection();
$userCollection->add($user1);
$userCollection->add($user2);
$userCollection->add($user3);

someMethod($userCollection);
```

In some cases, we need to "try" and fill a collection from an unknown array of objects. tryAddArray() method will allow for safely trying to add all objects of correct type and provide an array of objects that have failed to be added.

```
$failed = $objectCollection->tryAddArray($objects);
//the $failed array will contain objects that were not added to collection
```

Examples of KeyValueCollection usage
------------------------------------

[](#examples-of-keyvaluecollection-usage)

KeyValueCollection is a collection that is intended to contain Key=>Value pairs. Internally, this collection holds objects of Pair type, but the intention is not to use these Pair objects directly, but trough setting a key and value directly on a collection object.

```
$keyValueCollection = new KeyValueCollection();
```

A KeyValueCollection should be used via put() and get() methods.

```
$keyValueCollection->put('key', 'value');
$value = $keyValueCollection->get('key');
//$value will contain the string 'value'
```

You can also use the array syntax when using KeyValueCollection

```
$keyValueCollection['key'] = 'value';
$value = $keyValueCollection['key'];
//$value will contain the string 'value'
```

KeyValueCollection has unique keys. This means that putting something on a key that already exists will owerwrite the value in the collection

```
$keyValueCollection->put('key', 'value');
$keyValueCollection->put('key', 'newValue');
$value = $keyValueCollection->get('key');
//$value will contain the string 'newValue'
```

Now, you might think that this is simply emulating an associative array, so why would you use this instead?

The power of KeyValueCollection is that it can hold objects as keys, so you can have:

```
class UserId {...} //A Value Object class
class User {...} //A user details object class

class UserCollection extends KeyValueCollection {
    public function __construct() {
        parent::__construct(UserId::class, User::class);
    }
}

...

//Just for example. These would probably have been built and used inside your application
$userId = new UserId();
$user = new User();

...

$userCollection = new UserCollection();
$userCollection->put($userId, $user);
$user = $userCollection->get($userId);
```

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity23

Limited adoption so far

Community5

Small or concentrated contributor base

Maturity60

Established project with proven stability

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 ~392 days

Total

3

Last Release

1985d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3044904?v=4)[yomy](/maintainers/yomy)[@yomy](https://github.com/yomy)

---

Tags

collectiondatastructuresddd

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/yomy-datastructures/health.svg)

```
[![Health](https://phpackages.com/badges/yomy-datastructures/health.svg)](https://phpackages.com/packages/yomy-datastructures)
```

###  Alternatives

[phpcollection/phpcollection

General-Purpose Collection Library for PHP

1.0k64.0M34](/packages/phpcollection-phpcollection)[league/period

Time range API for PHP

7335.4M21](/packages/league-period)[loophp/collection

A (memory) friendly, easy, lazy and modular collection class.

745663.8k13](/packages/loophp-collection)[athari/yalinqo

YaLinqo, a LINQ-to-objects library for PHP

4561.2M5](/packages/athari-yalinqo)[lorisleiva/lody

Load files and classes as lazy collections in Laravel.

956.6M9](/packages/lorisleiva-lody)[pragmarx/coollection

Laravel Illuminate collection with objectified properties

943.4M11](/packages/pragmarx-coollection)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)