PREFIX
PREFIX = 'commits'
Key prefix commits are written under.
Reads and appends the history a restore walks.
Commits are immutable objects addressed by their own content; refs are the mutable names that say where a line of history ends. Appending a commit writes the object and then advances the ref, in that order, so a crash between the two leaves an unreferenced commit rather than a ref pointing at nothing. An unreferenced commit is collected by a later prune; a dangling ref would make the whole history unreadable.
$cache : array
Commits read during this request, keyed by id.
A walk revisits the same commit whenever two callers ask about overlapping ranges, and a commit is immutable, so caching it for the request is always safe.
$provider : \Drupal\strata\Storage\StorageProviderInterface
$refs : \Drupal\strata\Tree\RefStore
__construct(\Drupal\strata\Storage\StorageProviderInterface $provider, \Drupal\strata\Tree\RefStore $refs) : mixed
Constructs a log.
| \Drupal\strata\Storage\StorageProviderInterface | $provider | Where commits are written. |
| \Drupal\strata\Tree\RefStore | $refs | The ref store holding the tips. |
head(string $ref = \Drupal\strata\Tree\RefStore::MAIN) : \Drupal\strata\Tree\Commit|null
The commit a ref points at.
| string | $ref | Ref name. |
When the ref points at a commit that is absent or corrupt.
The commit, or NULL when the ref does not exist yet.
read(string $id) : \Drupal\strata\Tree\Commit
Reads one commit.
| string | $id | The commit id. |
When the id is not a valid digest.
When the commit is absent, or its content does not hash to its id.
The commit.
walk(string $from, int|null $limit = null) : \Generator<string,\Drupal\strata\Tree\Commit>
Walks history backwards from a commit.
| string | $from | Commit id to start at. |
| int|null | $limit | Stop after this many commits, or NULL to walk to the root. |
When a commit in the chain is absent or corrupt.
Commit id keyed to the commit, newest first.
replayPath(string $target) : array{anchor: string, path: list<string>, depth: int}
The nearest anchor at or before a commit, and the commits between.
A replay starts from an anchor and applies what follows, so this is the shape of a restore's work. The returned depth is what the UI shows as the cost of a restore point.
| string | $target | Commit id to reach. |
When no anchor is reachable, which means the root of history is missing.
The anchor's id, the commits from just after the anchor up to and including the target in oldest-first order, and how many commits must be replayed.
at(int $microtime, string $ref = \Drupal\strata\Tree\RefStore::MAIN) : \Drupal\strata\Tree\Commit|null
The commit in force at a moment in time.
Walks back from a ref until it finds the newest commit at or before the given time, which is what "restore to 14:32:06" resolves to.
| int | $microtime | Unix microseconds. |
| string | $ref | Ref name to walk from. |
When a commit in the chain is absent or corrupt.
The commit, or NULL when history does not reach that far back.
append(\Drupal\strata\Tree\Commit $commit, string $ref = \Drupal\strata\Tree\RefStore::MAIN) : string
Writes a commit and advances a ref to it.
The commit's parent must be whatever the ref currently points at, so a caller that built on a stale head is told rather than silently discarding the commits in between.
| \Drupal\strata\Tree\Commit | $commit | The commit to append. |
| string | $ref | Ref name to advance. |
When the commit's parent is not the ref's current tip, or the write fails.
The commit id.
write(\Drupal\strata\Tree\Commit $commit) : string
Writes a commit object without touching any ref.
Used by compaction, which writes a rolled-up commit before deciding which ref should point at it, and by a restore, which writes its pre-rollback snapshot before moving anything.
| \Drupal\strata\Tree\Commit | $commit | The commit. |
When the write fails.
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
object that each overwrites.
The commit id.