The SplFixedArray class

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Introduction

The SplFixedArray class provides the main functionalities of array. The main difference between a SplFixedArray and a normal PHP array is that the SplFixedArray must be resized manually and allows only integers within the range as indexes. The advantage is that it uses less memory than a standard array.

Class synopsis

class SplFixedArray implements IteratorAggregate, ArrayAccess, Countable, JsonSerializable {

/* Methods */

public function __construct(int $size = 0)

public function count(): int

public function current(): mixed

public static function fromArray(array $array, bool $preserveKeys = true): SplFixedArray

public function getIterator(): Iterator

public function getSize(): int

public function jsonSerialize(): array

public function key(): int

public function next(): void

public function offsetExists(int $index): bool

public function offsetGet(int $index): mixed

public function offsetSet(int $index, mixed $value): void

public function offsetUnset(int $index): void

public function rewind(): void

public function __serialize(): array

public function setSize(int $size): true

public function toArray(): array

public function __unserialize(array $data): void

public function valid(): bool

#[\Deprecated(
since: '8.4',
message: 'this method is obsolete, as serialization hooks are provided by __unserialize() and __serialize()',
)]
public function __wakeup(): void

}

Changelog

Version	Description
8.4.0	Out of bounds accesses in SplFixedArray now throw exceptions of type OutOfBoundsException instead of RuntimeException. Because OutOfBoundsException is a child class of RuntimeException no behavioural changes are exhibited when attempting to catch those exceptions.
8.2.0	The SplFixedArray::__serialize() and SplFixedArray::__unserialize() magic methods have been added to SplFixedArray.
8.1.0	Using a non-integer key on a SplFixedArray now throws a TypeError instead of a RuntimeException.
8.1.0	SplFixedArray implements JsonSerializable now.
8.0.0	SplFixedArray implements IteratorAggregate now. Previously, Iterator was implemented instead.

Examples

Example #1 SplFixedArray usage example

<?php
// Initialize the array with a fixed length
$array = new SplFixedArray(5);

$array[1] = 2;
$array[4] = "foo";

var_dump($array[0]); // NULL
var_dump($array[1]); // int(2)

var_dump($array["4"]); // string(3) "foo"

// Increase the size of the array to 10
$array->setSize(10);

$array[9] = "asdf";

// Shrink the array to a size of 2
$array->setSize(2);

// The following two blocks throw a RuntimeException: Index invalid or out of range
try {
    var_dump($array[-1]);
} catch(RuntimeException $e) {
    echo "RuntimeException: ".$e->getMessage()."\n";
}

try {
    var_dump($array[5]);
} catch(RuntimeException $e) {
    echo "RuntimeException: ".$e->getMessage()."\n";
}

// As of PHP 8.1.0, using a non-integer key throws a TypeError.
// Prior to PHP 8.1.0, a RuntimeException was thrown instead.
try {
    var_dump($array["non-numeric"]);
} catch(TypeError $e) {
    echo "TypeError: ".$e->getMessage()."\n";
}
?>

The above example will output:

NULL
int(2)
string(3) "foo"
RuntimeException: Index invalid or out of range
RuntimeException: Index invalid or out of range
TypeError: Illegal offset type

Note:
Prior to PHP 8.1.0, accessing a SplFixedArray with a non-integer key threw a RuntimeException instead of a TypeError.

SplFixedArray::__construct — Constructs a new fixed array
SplFixedArray::count — Returns the size of the array
SplFixedArray::current — Return current array entry
SplFixedArray::fromArray — Import a PHP array in a SplFixedArray instance
SplFixedArray::getIterator — Retrieve the iterator to go through the array
SplFixedArray::getSize — Gets the size of the array
SplFixedArray::jsonSerialize — Returns a representation that can be converted to JSON
SplFixedArray::key — Return current array index
SplFixedArray::next — Move to next entry
SplFixedArray::offsetExists — Returns whether the requested index exists
SplFixedArray::offsetGet — Returns the value at the specified index
SplFixedArray::offsetSet — Sets a new value at a specified index
SplFixedArray::offsetUnset — Unsets the value at the specified $index
SplFixedArray::rewind — Rewind iterator back to the start
SplFixedArray::__serialize — Serializes the SplFixedArray object
SplFixedArray::setSize — Change the size of an array
SplFixedArray::toArray — Returns a PHP array from the fixed array
SplFixedArray::__unserialize — Deserializes the data parameter into an SplFixedArray object
SplFixedArray::valid — Check whether the array contains more elements
SplFixedArray::__wakeup — Reinitialises the array after being unserialised

The SplFixedArray class

Introduction

Class synopsis

Changelog

Examples

Table of Contents