BTree

BTree class provides a B-Tree implementation for storing key-value pairs.

class BTree implements \IteratorAggregate

Implements: IteratorAggregate

It supports basic operations like insert, delete, and search.

Constants

BTREE_HEADER_SIZE

private const BTREE_HEADER_SIZE = 12

VERSION_STRING

private const VERSION_STRING = '1.0'

Properties

version

The version object representing the BTree version.

private Version $version

Type: Hazaar\Util\Version

slotSize

Size of each node slot in bytes.

private int $slotSize = 16

Type: int

keySize

Maximum size of each key in bytes.

private int $keySize = 32

Type: int

filePath

Path to the BTree file.

private string $filePath

Type: string

file

private mixed $file

Type: mixed

rootNode

public Node $rootNode

Type: Hazaar\Util\BTree\Node

readOnly

Indicates if the BTree is opened in read-only mode.

private bool $readOnly

Type: bool

lockDepth

How many withLock() calls are active, so nested operations share one lock.

private int $lockDepth

Type: int

lockMode

The lock currently held (LOCK_SH or LOCK_EX), or 0.

private int $lockMode

Type: int

Methods

__construct

Constructs a new BTree instance.

public __construct(string $filePath, bool $readOnly, int $keySize = 32, int $slotSize = 16): void

Initializes the BTree with the specified file path, key size, and slot size. If the BTree file does not exist, it will be created. Loads the root node from the file.

The header will be written to the file in the format:

• Major version (2 bytes)
• Minor version (2 bytes)
• Slot size (2 bytes)
• Key size (2 bytes)
• Pointer to the root node (4 bytes)

If the file already exists, it will read the header to determine the BTree's configuration.

Parameters

Parameter	Type	Description
$filePath	string	path to the BTree file
$readOnly	bool	if true, the BTree will be opened in read-only mode; otherwise, it will be opened in read-write mode
$keySize	int	Size of the key in bytes. Default is 32.
$slotSize	int	Size of the slot in bytes. Default is 16.

__destruct

Destructor for the BTree class.

public __destruct(): void

Ensures that the BTree file resource is closed when the object is destroyed.

isValid

Checks if the BTree instance is valid.

public isValid(): bool

Returns: bool

Validity is determined by:

• The file property being set and a valid resource.
• The rootNode property being set.

reset

Resets the B-Tree by reloading the root node from the file.

public reset(): bool

Returns: bool

set

Sets the value for the specified key in the B-Tree.

public set(string $key, mixed $value): bool

Returns: bool

Parameters

Parameter	Type	Description
$key	string	the key to set in the B-Tree
$value	mixed	the value to associate with the key

get

Gets the value for the specified key from the B-Tree.

public get(string $key): mixed

Returns: mixed

Parameters

Parameter	Type	Description
$key	string	the key to get from the B-Tree

has

public has(string $key): bool

Returns: bool

Parameters

Parameter	Type	Description
$key	string

remove

Removes the specified key from the B-Tree.

public remove(string $key): bool

Returns: bool

Parameters

Parameter	Type	Description
$key	string	the key to remove from the B-Tree

compact

Compacts the B-Tree file to reduce its size.

public compact(float $fillFactor = 0.5): bool

Returns: bool

Parameters

Parameter	Type	Description
$fillFactor	float	the fill factor for compacting the B-Tree, default is 0.5 This is used to determine how full the nodes should be after compaction. * A fill factor of 0.5 means that nodes will be 50% full after compaction. * A fill factor of 0.8 means that nodes will be 80% full after compaction.

count

Returns the total number of elements in the B-tree.

public count(): int

Returns: int

getIterator

Returns a generator that yields all records in the B-Tree.

public getIterator(): \Generator

Returns: Generator

This method traverses the B-Tree and yields each record's key and value.

keys

Returns an array of all keys in the B-Tree.

public keys(): array

Returns: array

Empties the B-Tree by creating a new root node.

public (): bool

Returns: bool

toArray

Return the entire B-Tree as an array.

public toArray(): array

Returns: array

verify

Verifies the integrity of the B-Tree.

public verify(): bool

Returns: bool

doSet

Sets a value. Must be called with an exclusive lock held.

private doSet(string $key, mixed $value): bool

Returns: bool

Parameters

Parameter	Type	Description
$key	string
$value	mixed

doCompact

Compacts the file. Must be called with an exclusive lock held.

private doCompact(float $fillFactor): bool

Returns: bool

Parameters

Parameter	Type	Description
$fillFactor	float

doEmpty

Empties the tree. Must be called with an exclusive lock held.

private doEmpty(): bool

Returns: bool

addLeafToTree

Adds a new leaf node to the B-Tree.

private addLeafToTree(array $nodeTree, mixed $file, Node $newLeafNode): void

Returns: void

This method is used internally to add a new leaf node to the B-Tree structure. It checks if the new leaf node is full and adds it to the tree if necessary.

Parameters

Parameter	Type	Description
$nodeTree	array	The current node tree
$file	mixed	The file resource for the B-Tree
$newLeafNode	Hazaar\Util\BTree\Node	The new leaf node to be added

propagateNodeTree

Adds a node to the B-Tree.

private propagateNodeTree(array $nodeTree, mixed $file, int $fillCount): void

Returns: void

This method is used internally to add a new node to the B-Tree structure. It checks if the new node is full and propagates it upwards in the tree if necessary.

Parameters

Parameter	Type	Description
$nodeTree	array	The current node tree
$file	mixed	The file resource for the B-Tree
$fillCount	int	The fill count for the nodes

readHeader

Loads the root node from the B-Tree file.

private readHeader(): bool

Returns: bool

writeHeader

Writes the header to the B-Tree file.

private writeHeader(mixed $file, ?Node $rootNode): bool

Returns: bool

Parameters

Parameter	Type	Description
$file	mixed
$rootNode	Hazaar\Util\BTree\Node

openFile

Opens the BTree file in the configured mode.

private openFile(): mixed

Returns: mixed

withLock

Runs an operation while holding a lock on the file, after bringing the in-memory tree up to date.

private withLock(int $mode, callable $operation): mixed

Returns: mixed

Parameters

Parameter	Type	Description
$mode	int
$operation	callable

lock

Takes (or upgrades to) a lock, then makes sure the in-memory tree matches the file.

private lock(int $mode): void

Returns: void

Another process may have written to the file, which updates nodes in place, or compacted it, which replaces the file. So on the outermost lock the node and record caches are dropped and the header and root node are read again, after reopening the file if it was replaced.

Parameters

Parameter	Type	Description
$mode	int

unlock

Releases the lock once the outermost operation finishes.

private unlock(): void

Returns: void

refresh

Drops cached nodes and records and reloads the root node from the file's header.

private refresh(): void

Returns: void

fileWasReplaced

Checks whether the file at the path is no longer the one our handle has open.

private fileWasReplaced(): bool

Returns: bool

---

Generated by Hazaar API Doc Generator on Thu, 22 Oct 2026 05:05:29 +0000