CanonicalZoneSql
final class CanonicalZoneSql (View source)
Resolves which zones row a Poweradmin zone ID refers to.
A zone ID reaching the infrastructure layer is zones.domain_id on installs migrated from SQL mode and zones.id on zones this application created, so both have to be matched. The two id spaces overlap, so a single ID can match one row by id and a different row by domain_id - picking the wrong one updates the wrong zone. Every resolver must therefore agree on the same preference, which is why this lives in one place.
Known limit: an extra-ownership row (NULL zone_name) is keyed only by canonical id, so under that collision no query can tell which of the two zones it belongs to.
Methods
Enable the zones.id fallback only for the API backend. In SQL mode domain_id is always populated and zones.id is an unrelated id space, so the fallback must never fire there.
SQL expression for a zones row's canonical id, the value API mode hands to callers.
SELECT that resolves a zone ID to exactly one zones row.
Bind every placeholder selectByZoneId() declares. PDO will not reuse one named placeholder across positions, hence the repetition.
Details
static void
setRowIdFallback(bool $enabled)
Enable the zones.id fallback only for the API backend. In SQL mode domain_id is always populated and zones.id is an unrelated id space, so the fallback must never fire there.
Set once at bootstrap from the configured backend.
static string
canonicalIdColumn(string $alias = '')
SQL expression for a zones row's canonical id, the value API mode hands to callers.
The PHP form of this rule is domain_id ?: id, which treats 0 as absent. A bare
COALESCE does not: it skips NULL only, so a row stranded at domain_id = 0 resolves to
0 rather than to its own id. NULLIF folds that 0 into NULL first, which is what keeps
this expression in step with the PHP rule.
Note the fallback to id assumes API mode, where zones is the source of truth. In SQL mode domain_id is a foreign key into domains and is always populated, so the fallback never fires; it must never be used to repair a SQL-mode row, because the two id spaces overlap and id would point at an unrelated zone.
Bind ids compared against this with PDO::PARAM_INT. An expression carries none of the column's type affinity, so SQLite compares a string-bound id as text and matches nothing, where the bare column would have coerced it.
static string
selectByZoneId(string $columns)
SELECT that resolves a zone ID to exactly one zones row.
Placeholder ownership rows (zone_name IS NULL) never win. Among real rows the order is:
a row whose id and domain_id both match, then a domain_id match, then an id match.
domain_id outranks id because that is the identifier API mode hands to callers - see
ApiDnsBackendProvider::getZones(), which emits domain_id ?: id.
Bind with bindZoneId(). The caller supplies the column list it needs.
static void
bindZoneId(PDOStatement $stmt, int $zoneId)
Bind every placeholder selectByZoneId() declares. PDO will not reuse one named placeholder across positions, hence the repetition.