Tsugi

OrgService
in package

Tenant-scoped organization tree.

The tenant is an lti_key row. Every org stores that key_id. Hierarchy walks never follow a parent in a different key.

getAncestors() and getDescendants() include the starting org. Ancestors are ordered from the org itself up to the root. Descendants are ordered from the org itself downward. Those methods return rows. ancestorScope() and descendantScope() return the same walk as a SQL relation, so another statement can filter or join it without first loading the ids into PHP.

moveOrg() rejects a cycle, including an org parented to itself. The parent foreign key already rejects a parent from another tenant. MySQL cannot add a CHECK for the self-parent case because org_id is AUTO_INCREMENT.

Table of Contents

Constants

MAX_DEPTH  : mixed = 64

Methods

ancestorScope()  : OrgScope
Ancestors of one org, including itself, as a composable SQL set.
contextAncestorScope()  : OrgScope
Ancestors of a course's organization, including that organization.
createOrg()  : int
deleteOrg()  : void
Remove an organization without deleting the courses, tools, or child orgs that pointed at it.
descendantScope()  : OrgScope
Descendants of one org, including itself, as a composable SQL set.
directHoldings()  : array{courses: array>, deployments: array>, children: array>, registrations: array>, counts: array, empty: bool}
Rows sitting directly on this org.
getAncestors()  : array<int, array<string, mixed>>
Starting org, then its parent, then that parent, up to the root.
getDescendants()  : array<int, array<string, mixed>>
Starting org, then every org below it in the same tenant.
isDescendantOrSelf()  : bool
True when $orgId is $ancestorOrgId or sits below it in the same tenant.
moveOrg()  : void
Move an org under another org in the same tenant, or to the tenant root.
orgsForKey()  : array<int, array<string, mixed>>
Every organization in one tenant, parents before their children.
placeContext()  : void
Place a course in an org, or clear that placement.
updateOrg()  : void
Rename an organization. The tenant and the parent stay as they are.
appendOrgTree()  : void
bubbleDeployments()  : void
childOrgs()  : array<int, array<string, mixed>>
coursesOnOrg()  : array<int, array<string, mixed>>
db()  : PDOX
deploymentsOnOrg()  : array<int, array<string, mixed>>
fail()  : void
findOrg()  : array<string, mixed>|null
finishWalk()  : array<int, array<string, mixed>>
insertId()  : int
optionalId()  : int|null
optionalLabel()  : string|null
orgRow()  : array<string, mixed>
orgScope()  : OrgScope
prefix()  : string
registrationsOnOrg()  : array<int, array<string, mixed>>
releaseRegistrations()  : void
removeOrgRow()  : void
reparentChildren()  : void
requireContext()  : array<string, mixed>
requireId()  : int
requireKey()  : void
requireOrg()  : array<string, mixed>
requireTitle()  : string
rows()  : array<int, array<string, mixed>>
runInTransaction()  : void
Run $work in a transaction this method owns.
walkRows()  : array<int, array<string, mixed>>

Constants

Methods

ancestorScope()

Ancestors of one org, including itself, as a composable SQL set.

public static ancestorScope(int $keyId, int $orgId[, string $name = 'org_ancestors' ]) : OrgScope

The tenant is an lti_key. Both the anchor and the recursive step require that key_id, so the walk stays inside the tenant.

Parameters
$keyId : int

tenant key

$orgId : int

starting organization

$name : string = 'org_ancestors'

CTE name, unique within the statement

Return values
OrgScope

contextAncestorScope()

Ancestors of a course's organization, including that organization.

public static contextAncestorScope(int $contextId[, string $name = 'org_ancestors' ]) : OrgScope

A course with no organization produces an empty set. A caller can still put the scope in one statement and match direct course rows beside it.

Parameters
$contextId : int
$name : string = 'org_ancestors'

CTE name, unique within the statement

Return values
OrgScope

createOrg()

public static createOrg(int $keyId, string $title[, int|null $parentOrgId = null ][, string|null $orgType = null ]) : int
Parameters
$keyId : int

tenant key

$title : string
$parentOrgId : int|null = null

null creates a top-level org

$orgType : string|null = null

label only; the tree does not use it

Return values
int —

new org_id

deleteOrg()

Remove an organization without deleting the courses, tools, or child orgs that pointed at it.

public static deleteOrg(int $orgId) : void

The database cannot express "move this up to the parent, or else to the key." Foreign keys can only cascade, restrict, or null a column. A composite ON DELETE SET NULL would also null key_id, and key_id is the tenant. Those foreign keys are therefore ON DELETE RESTRICT. This method walks the rows off the org, then deletes the org. A raw DELETE of an org that still has children, registrations, or deployments fails.

The transaction is required because the steps are only safe together. Stopping after any one of them leaves tools, scope, or the tree in the wrong place, or it deletes rows the later step was supposed to keep. Do not reorder these steps and do not delete the org from anywhere else.

  1. Reparent child orgs onto this org's parent, or make them roots when this org is a root. This has to happen first. The parent foreign key would otherwise refuse the delete, and the old CASCADE behavior deleted the whole subtree.
  2. Clear registration.owner_org_id for registrations administered by this org. They become tenant-administered and keep key_id. This has to happen before the org row goes away. Deleting the registration would cascade into every deployment of that registration.
  3. Move deployment assignments that point at this org. The deployment row and its deployment_id stay. If the parent org already has this same deployment, drop the assignment. Otherwise point the assignment at the parent. A root has no parent, so the assignment is removed. That does not make the deployment visible to the whole key. This has to happen before the org delete. The assignment foreign key would otherwise refuse the delete.
  4. Delete the org. Courses placed directly in it are left in place by the database: lti_context.org_id is a single-column foreign key with ON DELETE SET NULL, so the course keeps key_id and loses only the org. Courses placed in a child stay on that child, because the child was reparented in step 1.

If this method opened the transaction, a failure rolls it back and closes it. A caller that already has a transaction keeps that transaction; this method does not commit or roll back someone else's work.

Parameters
$orgId : int

descendantScope()

Descendants of one org, including itself, as a composable SQL set.

public static descendantScope(int $keyId, int $orgId[, string $name = 'org_descendants' ]) : OrgScope
Parameters
$keyId : int

tenant key

$orgId : int

starting organization

$name : string = 'org_descendants'

CTE name, unique within the statement

Return values
OrgScope

directHoldings()

Rows sitting directly on this org.

public static directHoldings(int $orgId) : array{courses: array>, deployments: array>, children: array>, registrations: array>, counts: array, empty: bool}

A later delete screen uses this to say how many courses, deployments, child orgs, and registrations are still here, and to list them so a person can move each one. These are direct rows only. A course placed in a child belongs to that child. A deployment assignment on a course, on an ancestor, or on another org is not a holding of this org.

empty is true only when all four lists are empty. That is when a screen may call deleteOrg() without it choosing destinations. deleteOrg() still repairs a non-empty org. That path is for unattended removal.

Parameters
$orgId : int
Return values
array{courses: array>, deployments: array>, children: array>, registrations: array>, counts: array, empty: bool}

getAncestors()

Starting org, then its parent, then that parent, up to the root.

public static getAncestors(int $orgId) : array<int, array<string, mixed>>
Parameters
$orgId : int
Return values
array<int, array<string, mixed>>

getDescendants()

Starting org, then every org below it in the same tenant.

public static getDescendants(int $orgId) : array<int, array<string, mixed>>
Parameters
$orgId : int
Return values
array<int, array<string, mixed>>

isDescendantOrSelf()

True when $orgId is $ancestorOrgId or sits below it in the same tenant.

public static isDescendantOrSelf(int $orgId, int $ancestorOrgId) : bool

isDescendantOrSelf(Computer Science, Engineering) is true. isDescendantOrSelf(Engineering, Engineering) is true. isDescendantOrSelf(Mechanical Engineering, Computer Science) is false.

Parameters
$orgId : int
$ancestorOrgId : int
Return values
bool

moveOrg()

Move an org under another org in the same tenant, or to the tenant root.

public static moveOrg(int $orgId, int|null $parentOrgId) : void

The cycle check and the parent update belong in one transaction. A failure between them must not leave the caller holding a transaction this method opened. This method opens a transaction only when the caller has none, and it commits or rolls back only that transaction. It does not lock the rows the cycle check read. Two simultaneous moves can still each pass that check.

Parameters
$orgId : int
$parentOrgId : int|null

null places the org at the tenant root

orgsForKey()

Every organization in one tenant, parents before their children.

public static orgsForKey(int $keyId) : array<int, array<string, mixed>>

Siblings are ordered by title. depth is 0 for a root. An org whose parent is missing or in another tenant is listed as a root.

Parameters
$keyId : int
Return values
array<int, array<string, mixed>>

placeContext()

Place a course in an org, or clear that placement.

public static placeContext(int $contextId, int|null $orgId) : void

The org must belong to the course's tenant key. A null org leaves the course unplaced, which is how existing courses already work.

Parameters
$contextId : int
$orgId : int|null

updateOrg()

Rename an organization. The tenant and the parent stay as they are.

public static updateOrg(int $orgId, string $title[, string|null $orgType = null ]) : void
Parameters
$orgId : int
$title : string
$orgType : string|null = null

label only; the tree does not use it

appendOrgTree()

private static appendOrgTree(array<int, array<int, array<string, mixed>>> $childrenOf, int $parentId, int $depth, array<int, bool> &$seen, array<int, array<string, mixed>> &$ordered) : void
Parameters
$childrenOf : array<int, array<int, array<string, mixed>>>
$parentId : int
$depth : int
$seen : array<int, bool>
$ordered : array<int, array<string, mixed>>

bubbleDeployments()

private static bubbleDeployments(int $orgId, int $keyId, int|null $parentOrgId) : void
Parameters
$orgId : int
$keyId : int
$parentOrgId : int|null

childOrgs()

private static childOrgs(int $orgId, int $keyId) : array<int, array<string, mixed>>
Parameters
$orgId : int
$keyId : int
Return values
array<int, array<string, mixed>>

coursesOnOrg()

private static coursesOnOrg(int $orgId, int $keyId) : array<int, array<string, mixed>>
Parameters
$orgId : int
$keyId : int
Return values
array<int, array<string, mixed>>

deploymentsOnOrg()

private static deploymentsOnOrg(int $orgId, int $keyId) : array<int, array<string, mixed>>
Parameters
$orgId : int
$keyId : int
Return values
array<int, array<string, mixed>>

fail()

private static fail(object $stmt, string $message) : void
Parameters
$stmt : object
$message : string

findOrg()

private static findOrg(int $orgId) : array<string, mixed>|null
Parameters
$orgId : int
Return values
array<string, mixed>|null

finishWalk()

private static finishWalk(array<int, array<string, mixed>> $rows) : array<int, array<string, mixed>>
Parameters
$rows : array<int, array<string, mixed>>
Return values
array<int, array<string, mixed>>

insertId()

private static insertId() : int
Return values
int

optionalId()

private static optionalId(mixed $id) : int|null
Parameters
$id : mixed
Return values
int|null

optionalLabel()

private static optionalLabel(mixed $value, int $max, string $label) : string|null
Parameters
$value : mixed
$max : int
$label : string
Return values
string|null

orgRow()

private static orgRow(array<string, mixed> $row) : array<string, mixed>
Parameters
$row : array<string, mixed>
Return values
array<string, mixed>

orgScope()

private static orgScope(int $keyId, int $orgId, string $name, bool $upward) : OrgScope
Parameters
$keyId : int
$orgId : int
$name : string
$upward : bool
Return values
OrgScope

prefix()

private static prefix() : string
Return values
string

registrationsOnOrg()

private static registrationsOnOrg(int $orgId, int $keyId) : array<int, array<string, mixed>>
Parameters
$orgId : int
$keyId : int
Return values
array<int, array<string, mixed>>

releaseRegistrations()

private static releaseRegistrations(int $orgId, int $keyId) : void
Parameters
$orgId : int
$keyId : int

removeOrgRow()

private static removeOrgRow(int $orgId, int $keyId) : void
Parameters
$orgId : int
$keyId : int

reparentChildren()

private static reparentChildren(int $orgId, int $keyId, int|null $parentOrgId) : void
Parameters
$orgId : int
$keyId : int
$parentOrgId : int|null

requireContext()

private static requireContext(int $contextId) : array<string, mixed>
Parameters
$contextId : int
Return values
array<string, mixed>

requireId()

private static requireId(mixed $id, string $label) : int
Parameters
$id : mixed
$label : string
Return values
int

requireKey()

private static requireKey(int $keyId) : void
Parameters
$keyId : int

requireOrg()

private static requireOrg(int $orgId) : array<string, mixed>
Parameters
$orgId : int
Return values
array<string, mixed>

requireTitle()

private static requireTitle(mixed $title, string $label) : string
Parameters
$title : mixed
$label : string
Return values
string

rows()

private static rows(string $sql, array<string, mixed> $params) : array<int, array<string, mixed>>
Parameters
$sql : string
$params : array<string, mixed>
Return values
array<int, array<string, mixed>>

runInTransaction()

Run $work in a transaction this method owns.

private static runInTransaction(callable $work) : void

A caller that already opened a transaction keeps it. Beginning another one fails on MySQL, and committing or rolling back that outer transaction would discard the caller's other work. When this method opens the transaction, it closes it: commit after $work, or roll back when $work throws. A rollback failure is reported with the original error so the connection is not left inside an open transaction without a trace.

Parameters
$work : callable

walkRows()

private static walkRows(int $orgId, bool $upward) : array<int, array<string, mixed>>
Parameters
$orgId : int
$upward : bool
Return values
array<int, array<string, mixed>>

        
On this page

Search results