All 42 libraries

SugarReleases

Phar self-update engine — verify before the swap, one-shot rollback

first-party self-update ed25519 ext-sodium (optional)

SugarReleases code coverage

The self-update machinery a phar-shipped SugarCraft app needs, extracted from candy-code so every app rides the same laws: pick the right release from a shared GitHub release stream, verify the bytes BEFORE the rename, keep a one-shot .old undo copy, and tell the user at launch when a newer release exists. Everything app-specific — repository, tag prefix, asset names, pinned public key, Composer package, display name — is one ReleaseSource value; the host parses its own argv and supplies its running version. First-party — there is no upstream Go port.

Install

composer require sugarcraft/sugar-releases

Quickstart

use SugarCraft\Releases\ReleaseSource;
use SugarCraft\Releases\SelfUpdate;
use SugarCraft\Releases\UpdateCheck;
use SugarCraft\Releases\UpdateOptions;

$source = ReleaseSource::new('acme/tools', 'widget')   // tags widget/v1.2.3, asset widget.phar
    ->withComposerPackage('acme/widget')
    ->withPublicKey($base64Ed25519PublicKey);          // '' = keyless state

// `widget self-update --check` / bare / --rollback / --channel=latest
$exit = SelfUpdate::new($source)->run(UpdateOptions::new()->withCheck(), $currentVersion);

// at launch: refresh a 24 h cache over the event loop, paint the PREVIOUS check's answer
$check = UpdateCheck::new($source, $stateDir, $currentVersion);
$check->refreshIfStale();
echo $check->cachedNotice() ?? '';

Exit codes: 0 up to date / swapped / rolled back; 1 refusals and failures (and --check finding an update); 2 usage errors. Report lines go to STDERR through a translator seam.

The laws

Verify before renameThe sha256 sidecar is fetched first and must be a lowercase 64-hex digest naming the phar; the phar streams to a temp file beside the target, is hashed with hash_equals(), and only then renamed. Every download leg judges HTTP status.
Pinned-key Ed25519With a key pinned, a release without a verifying signature is refused; the stream-safe signature over the sidecar body is preferred, the legacy raw-bytes asset is accepted behind a deprecation notice. --allow-unsigned never skips the sha256 gate.
Two channelsStable: newest non-draft <app>/v* release carrying both assets, ordered numerically. Dev: the rolling <app>/dev release judged by commit identity against a dev-<sha> stamp — indecidable is a refusal, never a guess.
One-shot rollbackThe running phar is copied to .old before the swap; --rollback renames it back, consuming it, with no network. The live file's mode is carried onto both halves.
Windows relaunch danceNT refuses to rename over a running image, so the verified bytes stage at .new and a detached helper retries the rename until the process exits, logging to .swap.log. The helper source is a fixed literal; paths travel as argv data.
Never blocks, never spamsThe launch notice reads only the previous check's cache (two-launch shape by design), re-validates the cached version at paint time, follows only same-origin release-list links, and degrades every failure to "no notice".

Use it for

  • Phar apps in a shared release stream — per-app tag prefixes keep one tool's releases from being confused with a sibling's.
  • Adopting the same laws in a second app — candy-code is the reference consumer, candy-top the second.

Source

Try the quickstart →

API

API surface
ClassMethodDescription
ReleaseSourcestatic new(string $repo, string $app): selfWhere an app publishes and what its artifacts are called; derives tag prefix <app>/, asset <app>.phar and the sidecar/signature names
ReleaseSourcewithTagPrefix() / withPharAsset() / withPublicKey() / withComposerPackage() / withUserAgent()Immutable overrides; an empty public key is the keyless state
SelfUpdatestatic new(ReleaseSource $source): self / run(UpdateOptions $options, string $currentVersion): intThe verb: verify-before-rename swap, --check, --rollback, channel selection; returns the exit code
SelfUpdatewithHttp() / withReleasesUrl() / withPharPath() / withPublicKey() / withWindows() / withErrorStream() / withTranslator() / withSwapLauncher()Seams for the host and the suite; every one defaults to the production behavior
SelfUpdatecomposerRefusal(?string $rootPackage = null): stringThe loud composer-mode refusal naming the command that fits the install shape
UpdateOptionsnew() / withCheck() / withRollback() / withAllowUnsigned() / withChannel() / withOperands() / validate()The parsed verb flags, free of any CLI framework; validate() names the first usage violation as a translation key
UpdateCheckstatic new(ReleaseSource $source, string $stateDir, string $currentVersion): self / refreshIfStale(): void / cachedNotice(): ?stringThe launch-time notice: async 24 h refresh into <stateDir>/update-check.json (0600), notice read from the previous check's cache
ReleaseSelectorfor(ReleaseSource $source) / selectRelease() / selectDevRelease() / devDecision() / parseSidecar() / sidecarName()Pure selection over a decoded GitHub release list, independent of transport
Versionparse() / compare() / isComparable() / isDev() / devShaOf()Strict v?X.Y.Z ordering (null = cannot order) and the dev-<sha> classifier
SignatureverifyDetached(string $payload, string $signatureBody, string $publicKeyBase64): boolEd25519 detached verification; every malformed shape answers false
WindowsSwaplaunch(int $parentPid, string $new, string $phar, ?\Closure $spawnSpec = null, ?array $env = null): bool / launchCommand()Spawns the detached rename-retry helper (60 s budget, 200 ms cadence)