PREFIX
PREFIX = 'branches'
Key prefix branch metadata is written under.
Creates, lists and removes branches in the object store.
A branch is a ref, so the tip is a ref and nothing here invents a second naming scheme for it. What a ref cannot hold is where the branch was cut from, who cut it and when, and those three are what makes a branch listing readable, so they go in a small JSON object beside the ref.
That split is what keeps the local index derivable. If the fork point lived only in
strata_branch, dropping the table would lose it and strata:reindex could not put it back; with
the metadata in the bucket the table is a cache over objects that already exist, exactly like every
other table this module installs.
The tip is the ref, never the metadata. A copy of the tip in the metadata object would be a second answer to the same question, and a crash between the two writes would leave them disagreeing with nothing saying which is right.
$provider : \Drupal\strata\Storage\StorageProviderInterface
$refs : \Drupal\strata\Tree\RefStore
__construct(\Drupal\strata\Storage\StorageProviderInterface $provider, \Drupal\strata\Tree\RefStore $refs) : mixed
Constructs a branch store.
| \Drupal\strata\Storage\StorageProviderInterface | $provider | Where branch metadata is written. |
| \Drupal\strata\Tree\RefStore | $refs | Where the tips live. |
read(string $name) : \Drupal\strata\Branch\Branch|null
One branch.
| string | $name | The branch name. |
When the name is not usable.
When the ref exists but does not hold a commit id.
The branch, or NULL when no ref of that name exists.
all() : array<string,\Drupal\strata\Branch\Branch>
Every branch the store holds, trunk included.
The trunk is listed because an operator merging into it needs to see where it is, and leaving it out would make the one ref that always exists the one the listing never mentions.
When a ref holds something that is not a commit id.
Branch name keyed to the branch, in name order.
create(string $name, string $from, int|null $actor = null, int|null $createdAt = null) : \Drupal\strata\Branch\Branch
Cuts a branch off a commit.
| string | $name | The branch name. |
| string | $from | Commit to fork from. |
| int|null | $actor | Drupal user id creating it, or NULL for unattended work. |
| int|null | $createdAt | Unix microseconds, or NULL for now. |
When the name is not usable or the commit is not a valid digest.
When a branch of that name already exists, or another writer created one first.
The branch.
advance(\Drupal\strata\Branch\Branch $branch, string $commit) : bool
Moves a branch to another commit, only if it still points where the caller thinks it does.
| \Drupal\strata\Branch\Branch | $branch | The branch as the caller last read it, whose tip is the expected value. |
| string | $commit | The commit to point it at. |
When the commit is not a valid digest.
TRUE when the branch was moved, FALSE when another writer had already moved it.
delete(string $name) : bool
Removes a branch.
The commits it pointed at are untouched; only the name goes away, and a prune collects whatever no surviving ref reaches. The trunk is refused, because deleting the ref every restore resolves through would leave a store full of history nothing can reach.
| string | $name | The branch name. |
When the name is not usable.
When the name is the trunk.
TRUE when a branch was removed, FALSE when there was none of that name.
hydrate(string $name, string $tip) : \Drupal\strata\Branch\Branch
A branch from its ref tip and whatever metadata survives beside it.
A ref with no metadata object is still a branch. The trunk has never had one, an archive import writes refs before anything else, and a ref written by a future release may carry metadata this one cannot read; in all three the tip is its own fork point, which is the honest answer rather than a guess at where it diverged.
| string | $name | The branch name. |
| string | $tip | The commit the ref points at. |
The branch.