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.

Install

Included in every project created by the installer (https://semitexa.com/install.sh).

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
  • the scaffold phase covers bin/semitexa, the compose and PHPStan files, and the agent docs (AGENTS.md, CLAUDE.md, AI_*.md): a file that matches a released version is replaced (with a .bak), an edited one gets the new version beside it as .new
• 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.

How the composer phase picks versions

The release set is the require map of the latest stable semitexa/ultimate. Every release cut republishes ultimate with the exact version of every package, tested together. A cut tags only the packages that changed, so no other package can stand in for the set. An up-to-date project normally spans several release dates, and that is not drift.

• An exact pin moves to its version in the set. A package outside the set moves to its own latest release. A pin is never moved lower than it is declared.
• A package Packagist has never heard of (a private VCS or path package) keeps its pin, and composer resolves it from the project's repositories. Only an unreachable registry blocks the run (override: --allow-partial-composer-update).
• --dry-run asks composer whether the plan resolves, against a scratch copy of composer.json (COMPOSER=composer.semitexa-update-plan.json). The project's files are never written.
• If composer update fails, composer.json and composer.lock are restored byte for byte. vendor/ is reinstalled from them if composer had already moved it.
• When semitexa/update itself moves, the run continues in a fresh PHP process on the new code. It does not ask you to rerun.

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:

Run it from the project root (/srv/semitexa/my-project). The systemd wrapper (vendor/semitexa/update/tools/run-auto-deploy-systemd.sh, copied into the project's tools/) 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:

The refresh pair only applies to the host that serves the public installer. On any other project the refresh script refuses to run (there is no packages/semitexa-ultimate checkout), so disable it after installing the units: sudo systemctl disable --now semitexa-refresh-install-sh.timer.

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: