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
MAX_DEPTH
public
mixed
MAX_DEPTH
= 64
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
OrgScopecontextAncestorScope()
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
OrgScopecreateOrg()
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.
- 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.
- 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.
- 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.
- 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
OrgScopedirectHoldings()
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: arraygetAncestors()
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
boolmoveOrg()
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>>db()
private
static db() : PDOX
Return values
PDOXdeploymentsOnOrg()
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>|nullfinishWalk()
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
intoptionalId()
private
static optionalId(mixed $id) : int|null
Parameters
- $id : mixed
Return values
int|nulloptionalLabel()
private
static optionalLabel(mixed $value, int $max, string $label) : string|null
Parameters
- $value : mixed
- $max : int
- $label : string
Return values
string|nullorgRow()
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
OrgScopeprefix()
private
static prefix() : string
Return values
stringregistrationsOnOrg()
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
intrequireKey()
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
stringrows()
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