README

SplFixedArrays are an implementation of a traditional, bounded array in the PHP standard library.

While they require manual resizing, they're significantly faster than regular arrays or collections when working with large sets of data.

Requirements

Currently, requires PHP 8.4 or above, and Laravel 12+.

Installation

You can install the package via Composer:

composer require petrobolos/fixed-array-functions

Quick Start

Fluent interface

FixedArray is best used with its fluent interface. If you're familiar with Illuminate collections, you'll feel right at home. Provide it an SplFixedArray to get started, or a standard array or collection that will be automatically converted.

use Petrobolos\FixedArray\FixedArrayable;

// Create using various methods
$array = new FixedArrayable([1, 2, 3]);
$array = fixedArray([1, 2, 3]);  // Helper function
$array = FixedArrayable::fromCollection(collect([1, 2, 3]));

// Chain methods just like Laravel Collections
$result = fixedArray([1, 2, 3, 4, 5, 6])
    ->filter(fn ($value) => $value % 2 === 0)
    ->map(fn ($value) => $value * 2)
    ->sum();  // Returns 24 (2*2 + 4*2 + 6*2)

Static methods

You aren't forced to use the fluent interface and can access methods directly by calling them. This is useful if you only need to do one or two operations on a fixed array.

use Petrobolos\FixedArray\FixedArray;

$arr = FixedArray::fromArray([1, 2, 3, 4, 5]);

// Aggregate functions
$sum = FixedArray::sum($arr);           // 15
$avg = FixedArray::avg($arr);           // 3
$min = FixedArray::min($arr);           // 1
$max = FixedArray::max($arr);           // 5

// Higher-order functions
$doubled = FixedArray::map($arr, fn($v) => $v * 2);
$evens = FixedArray::filter($arr, fn($v) => $v % 2 === 0);

// Conditional operations
$result = FixedArray::when(
    $arr,
    fn($a) => FixedArray::count($a) > 3,
    fn($a) => FixedArray::push($a, 6)
);

Real-World Examples

Processing Large Datasets

// Efficiently process 100,000 records
$data = FixedArray::create(100000);

for ($i = 0; $i < 100000; $i++) {
    FixedArray::offsetSet($data, $i, fetchRecordFromDatabase($i));
}

$processed = fixedArray($data)
    ->filter(fn($record) => $record->isActive)
    ->map(fn($record) => $record->transform())
    ->toCollection(); // Convert back to Collection for further Laravel operations

Data Aggregation

$orders = fixedArray($orderArray)
    ->pluck('total')
    ->sum();

$averageAge = fixedArray($users)
    ->avg('age');

$oldestUser = fixedArray($users)
    ->max('created_at');

Conditional Transformations

$processed = fixedArray($items)
    ->when(
        $shouldFilter,
        fn($arr) => $arr->filter(fn($item) => $item->isValid())
    )
    ->unless(
        $skipSorting,
        fn($arr) => $arr->sort()
    )
    ->tap(fn($arr) => logger()->info('Processed items', ['count' => $arr->count()]))
    ->toArray();

Partitioning Data

[$valid, $invalid] = fixedArray($records)
    ->partition(fn($record) => $record->validate())
    ->toArray();

// $valid contains all validated records
// $invalid contains all failed records

Performance Benefits

SplFixedArray offers significant performance advantages over standard PHP arrays for large datasets:

• Memory Efficiency: Uses approximately 50% less memory than standard arrays
• Faster Access: Direct memory access without hash table overhead
• Predictable Performance: O(1) access time for all operations

When to use SplFixedArray:

• Working with large datasets (10,000+ elements)
• Memory-constrained environments
• Performance-critical array operations
• Known array size at creation time

When to stick with regular arrays/Collections:

• Small datasets (< 1,000 elements)
• Dynamic sizing with frequent additions/removals
• Need associative keys or complex key types

Full list of available methods

Testing

Tests are run using Pest. You can run the suite like so:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

We welcome pull requests, especially those improving the package's optimisation and speed, and new features to bring it into parity with Collection.

Please ensure any functionality submitted has adequate test coverage and documentation (at least in English.)

License

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