ext-ds

Native Data Structures for PHP

A PHP language extension that provides specialized data structures as efficient alternatives to the PHP array.

v2.0 introduces a simplified API with fewer types and copy-on-write (COW) semantics for safe iteration during mutation. The core types are Seq, Map, Set, Heap, Pair, and Key.

You can read about the original motivation for this project in this blog post.

Documentation

Documentation is available on php.net. Note that the php.net docs may not yet reflect the v2.0 changes. The v2.0 types are:

• Ds\Seq -- unified sequence (replaces Vector, Deque, Stack, and Queue)
• Ds\Map -- ordered dictionary with support for arbitrary keys
• Ds\Set -- ordered set of unique values
• Ds\Heap -- configurable heap with optional comparator (replaces PriorityQueue)
• Ds\Pair -- readonly key-value pair
• Ds\Key -- interface for custom key equality (replaces Hashable)

getIterator() on Seq, Map, Set, and Heap returns an InternalIterator supporting the standard Iterator methods.

You should also include the polyfill in your project for IDE integration.

Installation

Requires PHP >= 8.2.

The easiest way to install the extension is to use PECL:

pecl install ds

If you're on Windows, you can download a compiled .dll on PECL or under releases.

Enabling the extension

You'll need to add extension=ds.so to your primary php.ini file.

If you encounter an "undefined symbol" error, see #2.

# To see where .ini files are located
php -i | grep "\.ini"

You can also enable the extension temporarily using the command line:

php -d extension=ds.so

Note: Windows would use php_ds.dll instead.

Testing

Tests are split between PHPT tests and PHPUnit shared tests.

# PHPT tests (native extension tests)
make test

# PHPUnit shared tests (requires Composer)
composer install
composer test

Compatibility

You may include the polyfill as a dependency in your project. This allows your codebase to still function in an environment where the extension is not installed.

Contributing

For local development, I'm using Docker:

./dev.sh  # opens a shell into a development environment

phpize
./configure
make
make install

composer install
composer test

Please see CONTRIBUTING for more information.

Credits

• Rudi Theunissen
• Joe Watkins

License

The MIT License (MIT). Please see LICENSE for more information.