AlpmTransaction

AlpmTransaction

Represents an install/remove/upgrade transaction against a handle's root and database. This is the least exercised part of php-alpm — read carefully, test on a throwaway root first, and expect to need write permission on $root/$dbpath or you'll hit exceptions.

You get one from AlpmHandle::init_transaction(), never new:

$trans = $handle->init_transaction(nodeps: true);

Lifecycle

init_transaction() -> add_pkg()/remove_pkg()/system_upgrade() -> prepare() -> commit() -> release()

A transaction can be release()d at any point without being committed. Only one transaction can be open on a handle at a time.

$pkg = $handle->load_pkg($pwd . "/pkg-1.0-1-x86_64.pkg.tar.zst");
$trans = $handle->init_transaction(nodeps: true);
$trans->add_pkg($pkg);

$err = $trans->prepare();
if ($err !== null) {
    // resolve $err (see prepare() below), then release and bail
    $trans->release();
} else {
    $trans->commit();
    $trans->release();
}

Methods

add_pkg() / remove_pkg()

public function add_pkg(AlpmPkg $pkg): bool
public function remove_pkg(AlpmPkg $pkg): bool

Queue a package to be installed/upgraded, or removed. Returns success — does not throw. Once added, the AlpmPkg you passed in is consumed (don't keep using your local $pkg variable afterward).

system_upgrade()

public function system_upgrade(bool $do_downgrade = false): bool

Queues every installed package that has a newer version in a registered sync database for upgrade. $do_downgrade also allows moving to a lower version if that's what the sync database has. Throws AlpmTransactionException if the underlying libalpm call fails.

prepare()

public function prepare(): ?array

Resolves dependencies and checks for conflicts. Returns null on success. On failure, returns an array describing what went wrong instead of throwing:

[
  "errno" => int,        // ALPM_ERR_* from libalpm
  "offenders" => array,  // shape depends on errno, see below
]

offenders is populated for these errno values (and empty otherwise):

errno	offenders shape
ALPM_ERR_PKG_INVALID_ARCH	string[] of "pkgname-version-arch"
ALPM_ERR_UNSATISFIED_DEPS	AlpmDepMissing[]
ALPM_ERR_CONFLICTING_DEPS	AlpmConflict[]

ALPM_ERR_* constants aren't currently registered as PHP constants by this extension — compare errno against libalpm's alpm_errno_t values directly, or just branch on whether offenders came back empty.

commit()

public function commit(): ?array

Actually writes the transaction to disk. Returns null — currently always, on both success and failure. If you need to know why a commit failed, check AlpmHandle::$logcb/$eventcb output rather than relying on commit()'s return value; surfacing structured failure data here (file conflicts, invalid packages) is planned but not wired up yet (see the repo's TODO file for other pending libalpm bindings).

get_add() / get_remove()

public function get_add(): ?array
public function get_remove(): ?array

Returns the AlpmPkg[] currently queued to be installed/removed in this transaction.

get_flags()

public function get_flags(): int

Returns the transaction's flags as a bitmask of ALPM_TRANS_FLAG_* (see Constants) — set when the transaction was created via AlpmHandle::init_transaction().

interrupt()

public function interrupt(): bool

Signals libalpm to interrupt a transaction. Throws AlpmTransactionException if it can't be interrupted.

release()

public function release(): ?bool

Releases the transaction, freeing it. Returns null on success. Throws AlpmTransactionException if release fails — the transaction is left in an undefined state at that point.

Exceptions

AlpmTransactionException (extends Exception) is thrown by system_upgrade(), interrupt(), and release() on failure, with a short fixed message and code 0. add_pkg()/remove_pkg() never throw (they return false); prepare()/commit() never throw either — they communicate failure through their return value (or, for commit(), currently don't communicate it at all — see above).