\Drupal\strata\Tree Commit

One point in the site's history.

Shaped like a git commit: a parent, a tree, a time, an actor and a message. A restore target is always a commit, and every commit is reachable from a ref by walking parents.

The root commit has no parent and almost every other commit has exactly one, so history is a chain. The single exception is a merge commit, which also names the branch tip it brought in through Commit::$merge, and that is the only way a second line of history becomes reachable from a ref.

merge is serialized only when it is set. A commit is addressed by the bytes of its own JSON, so writing the key as NULL on every commit would change the address of every commit ever written and orphan the whole store. A single-parent commit therefore serializes exactly as it did before merging existed, which CommitTest proves byte for byte.

A commit does not carry an index of the site. It names the anchor its history resolves against, and only the commit that wrote that anchor is marked as one. Writing a per-commit index was measured at 3,989,289 bytes to record a 201-byte change across 50,000 subjects, because the cost scaled with how many subjects the site had rather than with how many changed. So the index belongs to an anchor on its own interval, and the commits between two anchors inherit its address, its chain length and its time - which keeps a flush at four objects whatever the site's size.

Summary

Methods

Properties

Constants

__construct
id
isRoot
isMerge
parents
isAnchor
timestamp
ratio
asBase
jsonSerialize
fromArray

index
parent
microtime
label
actor
operations
rawBytes
storedBytes
level
base
chain
anchoredAt
metadata
merge

No public constants found

No protected methods found

No protected properties found

No protected constants found

No private methods found

No private properties found

No private constants found

final

File: src/Tree/Commit.php
Package: Application
Class hierarchy: \Drupal\strata\Tree\Commit
Implements
See also

Properties

$index

$index : string

Type

string

$parent

$parent : ?string

Type

string|null

$microtime

$microtime : int

Type

int

$label

$label : string

Type

string

$actor

$actor : ?int

Type

int|null

$operations

$operations : int

Type

int

$rawBytes

$rawBytes : int

Type

int

$storedBytes

$storedBytes : int

Type

int

$level

$level : int

Type

int

$base

$base : bool

Type

bool

$chain

$chain : int

Type

int

$anchoredAt

$anchoredAt : int

Type

int

$metadata

$metadata : array

Type

array<string|int, mixed>

$merge

$merge : ?string

Type

string|null

Methods

__construct()

__construct(string  $index, string|null  $parent = null, int  $microtime = 0, string  $label = '', int|null  $actor = null, int  $operations = 0, int  $rawBytes = 0, int  $storedBytes = 0, int  $level = 0, bool  $base = false, int  $chain = 0, int  $anchoredAt = 0, array  $metadata = [], string|null  $merge = null) : mixed

Constructs a commit.

Parameters

string	$index	Address of the base anchor this commit's history resolves against. Its own when this commit is an anchor, otherwise the one it inherited from its parent.
string\|null	$parent	Address of the previous commit, or NULL for the root of history.
int	$microtime	Unix microseconds the commit was sealed at.
string	$label	Short human summary, such as "42 nodes, 3 config objects".
int\|null	$actor	Drupal user id responsible, or NULL for cron and other unattended work.
int	$operations	Captured operations this commit covers.
int	$rawBytes	Decoded bytes the operations described.
int	$storedBytes	Bytes actually written, after deduplication, compression and sealing.
int	$level	Compaction level; 0 for a freshly flushed commit, higher after a rollup.
bool	$base	Whether this commit wrote the anchor it names, so a replay can stop here.
int	$chain	How many anchors stand between the one this commit names and the full anchor behind it, counting the full one. Carried on the commit so a flush can apply the full-anchor policy without reading the chain.
int	$anchoredAt	Unix microseconds the anchor this commit names was written at, so a flush can tell whether the next anchor is due without reading it.
array	$metadata	Anything a capture wants to carry, such as the segment key it came from.
string\|null	$merge	Address of the second parent, which is the branch tip a merge brought in, or NULL for every other commit. Declared last so every existing positional caller is untouched.

Throws

\InvalidArgumentException: When an address is not a valid digest, a count is negative, or a merge parent is named by a commit that has no first parent.

Returns

mixed —

id()

id() : string

This commit's content address.

Derived from the serialized commit, so an identical commit written twice is the same commit.

Throws

\JsonException: When the label or the metadata holds a string JSON cannot represent. (string) false would otherwise address every such commit as Hash::of(''), so two unrelated commits would be one commit and overwrite each other.

Returns

string —

A 64-character lowercase hex digest.

isRoot()

isRoot() : bool

Whether this commit begins the history.

Returns

bool —

TRUE when it has no parent.

isMerge()

isMerge() : bool

Whether this commit joined a second line of history.

Returns

bool —

TRUE when it names a merge parent.

parents()

parents() : list<string>

Every commit this one builds on.

A walk that follows only Commit::$parent stays on the line the ref describes, which is what a replay wants; a walk that has to decide whether one commit is an ancestor of another needs both, which is what a merge base wants.

Returns

list —

Parent addresses, the first parent first, empty for the root of history.

isAnchor()

isAnchor() : bool

Whether a replay can stop at this commit rather than walking further back.

Returns

bool —

TRUE for a base anchor or the root of history.

timestamp()

timestamp() : float

The commit time as a float unix timestamp.

Returns

float —

Seconds since the epoch, with microsecond precision.

ratio()

ratio() : float

How much smaller the stored form is than what it describes.

Returns

float —

Raw bytes divided by stored bytes; 1.0 when either is zero.

asBase()

asBase() : self

The same commit marked as having written its anchor.

Returns

self —

A new commit.

jsonSerialize()

jsonSerialize() : array<string,mixed>

{@inheritdoc}

Returns

array —

The commit as a plain array. The merge parent appears only on a commit that has one, so a single-parent commit hashes to the address it always did.

fromArray()

fromArray(array  $data) : self

Rebuilds a commit from its serialized form.

Parameters

array

$data

The array produced by Commit::jsonSerialize().

Throws

\InvalidArgumentException: When the anchor address is missing or the commit is incoherent.

Returns

self —

The commit.

see
package	Application
uses
method
property
property-read
property-write