Download the PHP package semitexa/update without Composer

Semitexa Update

semitexa/update owns the update lifecycle of a Semitexa application — package version detection, plan building, ORM schema synchronization, and post-schema data patches. It is not a schema migration system.

Ownership boundary

A data patch must never issue DDL. Schema changes go through ORM. The runner enforces this with a DDL-keyword guard at apply time.

What this package does

• discovers classes annotated with #[AsDataPatch(...)]
• runs phases in strict order: pre, apply, post — relative to the ORM schema sync
• resolves per-phase dependencies through a DAG
• stores pending, applied, and failed state in a per-database journal
• stops on the first failed patch and reports the failure

What this package does not do

• it does not perform schema migrations — see semitexa-orm
• it does not create, alter, drop, rename, or truncate tables or columns
• it does not run inside semitexa-dev — Dev is for developer tooling only

Authoring a data patch

Identity is (module, id) — stable across class renames. The combined form module:id is what the journal and dependency declarations use. Phase ordering is global; dependency ordering is applied within the same phase.

Required attribute fields

Schema compatibility gate

Before the runner executes a patch it consults SchemaCompatibilityChecker. If any of the requires entities or requiresColumns entries are missing from the live database, the patch is skipped (not failed) — no journal row is written, and the operator is told why in the run report. The fix is to bring the schema forward via orm:sync, then re-run update.

DDL guard

DataPatchContext::execute() and query() reject SQL whose first non-comment token is CREATE, ALTER, DROP, RENAME, or TRUNCATE. The runner throws a PatchSafetyException in that case. Schema mutations belong to the ORM.

CLI commands

• update — run the full sweep: preflight → composer → scaffold → patches → orm-sync → health check; --dry-run prints the plan without changing state
• update:plan — compute and display pending patches only
• update:status — updater version, installed release set, last run, and applied/pending/failed patch counts by phase
• update:history — the run journal: past runs with outcome, package deltas, duration; --id=<run> shows one run in full
• update:changelog — package version changes applied here + available upstream, with release-note sections; --package=<name> shows one package's CHANGELOG; --no-remote skips network

Each accepts --connection=<name> and defaults to default.

Run journal & changelog

Every mutating update run and every auto-deploy attempt writes one row to platform_update_run_journal (stages, package version deltas, actor, outcome, duration). update:history and update:changelog read it; a run lock in var/lock/semitexa-update.lock serializes both paths.

Per-package release notes convention: each package keeps a CHANGELOG.md at its root with sections ## <version> — <date> (newest first, v prefix and date optional, ## Unreleased on top). update:changelog resolves a version delta to those sections from vendor/semitexa/<name>/CHANGELOG.md (consumer) or packages/semitexa-<name>/CHANGELOG.md (dev workspace).

When to use this package

• backfilling values after a new column has been added by ORM
• normalizing existing data into a new format
• creating required default rows
• migrating configuration rows
• repairing data that depends on a new schema shape

When not to use this package

• creating, altering, dropping, or renaming tables / columns / indexes / foreign keys → use orm:sync
• adding new entities to the model → declare a [Resource]-attributed class and let ORM pick it up
• versioned numbered schema migrations — Semitexa ORM uses entity attributes as the source of truth, not numbered files

Package update / framework auto-deploy / remote bootstrap

This package also owns the operational commands that detect, plan, and apply Semitexa package updates for a project. Schema changes still flow through ORM; package updates are purely about composer-level version bumps and the orchestration that supports them.

Configuration

Auto-deploy is opt-in:

Remote first-deployment (Ubuntu 20.04+):

Operator commands

Production polling install:

The systemd wrapper (packages/semitexa-update/tools/run-auto-deploy-systemd.sh) calls update:packages:auto and reruns bin/semitexa server:start when restart_required=true, then performs the configured HTTP healthcheck.

Production deploy systemd units

The installer above provisions two independent unit pairs, decoupled on purpose:

semitexa-auto-deploy.service runs composer update 'semitexa/*' --with-all-dependencies --prefer-dist --no-dev --no-interaction --optimize-autoloader. The --prefer-dist flag is mandatory: production vendor/semitexa/* is shipped as dist (no .git/), so without it composer may pick source mode for some packages and fail with GitDownloader.php line 155: The .git directory is missing.

Install / update on production

Verify

Manually trigger

Inspect logs

Removing the legacy ExecStartPost drop-in

Hosts provisioned before the refresh-install-sh units existed may still carry /etc/systemd/system/semitexa-auto-deploy.service.d/10-refresh-install-sh.conf, which refreshed install.sh from inside ExecStartPost. Once the new semitexa-refresh-install-sh.timer is enabled, that drop-in is redundant — remove it so install.sh refresh stops being parasitic on a successful deploy: