PermissionTables
in package
Admin reads and writes for the permission tables.
Grants are the rows an administrator hands out. Revoke keeps the row. A second active grant for the same user, system scope, and permission is rejected. Applications are listed and can be removed. A user has at most one application in progress for a permission, either pending or sent back for revision. The system scope row is read-only here.
Table of Contents
Constants
- JUSTIFICATION_MAX : mixed = 4000
- Justification column is TEXT. This is the form limit.
- PAGE_LENGTH : mixed = 20
- Admin list page size. One extra row is fetched to know if another page exists.
- SOURCE_APPLICATION : mixed = 'application'
- Grant row written when an application is approved.
- STATUS_APPROVED : mixed = 'approved'
- STATUS_DENIED : mixed = 'denied'
- STATUS_PENDING : mixed = 'pending'
- STATUS_REVISION : mixed = 'revision'
- Sent back so the applicant can edit the same row and resubmit.
- SYSTEM_SCOPE_ID : mixed = 1
Methods
- adminEmails() : array<int, string>
- Addresses in $CFG->adminemails, lowercased, with blanks dropped.
- applicationNotice() : array{subject: string, message: string, title: string, text: string}
- Subject and body for an admin notice about a new application.
-
applications()
: array{rows: array
>, start: int, more: bool, length: int} - One page of applications, newest first.
- decisionNotice() : array{title: string, text: string, url: string}
- Title, text, and link for the applicant's decision notice.
- deleteApplication() : array{ok: true}|array{ok: false, error: string}
- deleteGrant() : array{ok: true}|array{ok: false, error: string}
- findUser() : array{user_id: int}|array{error: string}
-
grants()
: array{rows: array
>, start: int, more: bool, length: int} - One page of grants, newest first.
- handGrant() : array{ok: true, grant_id: int}|array{ok: false, error: string}
- Hand out a system-scope grant. No application row.
- isActive() : mixed
- A grant still allows the permission.
- latestApplication() : array<string, mixed>|false
- Newest application for this user and permission, any status.
- notifyAdmins() : mixed
- Email every admin address, and notify each matching user account.
- openApplication() : array<string, mixed>|false
- The application still in progress: pending, or sent back for revision.
- parseExpires() : array{at: string|null}|array{error: string}
- pendingApplication() : array<string, mixed>|false
- The user's pending application for this permission, or false.
- registry() : array<string, array<string, mixed>>
- resubmitApplication() : array{ok: true, application_id: int}|array{ok: false, error: string}
- Put a sent-back application back in the queue with a new justification.
- reviewApplication() : array{ok: true, status: string}|array{ok: false, error: string}
- Approve, reject, or send back a pending application.
- revokeGrant() : array{ok: true}|array{ok: false, error: string}
- scopes() : array<int, array<string, mixed>>
- submitApplication() : array{ok: true, application_id: int}|array{ok: false, error: string}
- Store a pending application and tell the admin emails.
- syncCourseCreateFlag() : bool
- Keep a course.create grant in step with lti_user.create_courses.
- userLabel() : string
- Name, email, and user id for an application or grant row.
- withdrawApplication() : array{ok: true}|array{ok: false, error: string}
- Delete the user's own in-progress application.
- connection() : mixed
- notifyApplicant() : mixed
- In-app notice to the applicant. A failed send leaves the decision in place.
- openSlot() : mixed
- Unique while a request is in progress. Cleared after approve or reject.
-
pageResult()
: array{rows: array
>, start: int, more: bool, length: int} - saveGrant() : int
- Insert one system-scope grant, or refresh the row that is already there.
- usersByEmail() : array<int, int>
- Site-login accounts (the google.com key) whose email is in the list.
Constants
JUSTIFICATION_MAX
Justification column is TEXT. This is the form limit.
public
mixed
JUSTIFICATION_MAX
= 4000
PAGE_LENGTH
Admin list page size. One extra row is fetched to know if another page exists.
public
mixed
PAGE_LENGTH
= 20
SOURCE_APPLICATION
Grant row written when an application is approved.
public
mixed
SOURCE_APPLICATION
= 'application'
STATUS_APPROVED
public
mixed
STATUS_APPROVED
= 'approved'
STATUS_DENIED
public
mixed
STATUS_DENIED
= 'denied'
STATUS_PENDING
public
mixed
STATUS_PENDING
= 'pending'
STATUS_REVISION
Sent back so the applicant can edit the same row and resubmit.
public
mixed
STATUS_REVISION
= 'revision'
SYSTEM_SCOPE_ID
public
mixed
SYSTEM_SCOPE_ID
= 1
Methods
adminEmails()
Addresses in $CFG->adminemails, lowercased, with blanks dropped.
public
static adminEmails() : array<int, string>
Return values
array<int, string>applicationNotice()
Subject and body for an admin notice about a new application.
public
static applicationNotice(array<string, mixed> $application, array<string, mixed> $applicant[, bool $resubmit = false ]) : array{subject: string, message: string, title: string, text: string}
Parameters
- $application : array<string, mixed>
- $applicant : array<string, mixed>
- $resubmit : bool = false
-
True after the applicant revises a sent-back request.
Return values
array{subject: string, message: string, title: string, text: string}applications()
One page of applications, newest first.
public
static applications([int $start = 0 ]) : array{rows: array>, start: int, more: bool, length: int}
Parameters
- $start : int = 0
Return values
array{rows: arraydecisionNotice()
Title, text, and link for the applicant's decision notice.
public
static decisionNotice(array<string, mixed> $application, string $status) : array{title: string, text: string, url: string}
Parameters
- $application : array<string, mixed>
- $status : string
-
approved, denied, or revision
Return values
array{title: string, text: string, url: string}deleteApplication()
public
static deleteApplication(int $applicationId) : array{ok: true}|array{ok: false, error: string}
Parameters
- $applicationId : int
Return values
array{ok: true}|array{ok: false, error: string}deleteGrant()
public
static deleteGrant(int $grantId) : array{ok: true}|array{ok: false, error: string}
Parameters
- $grantId : int
Return values
array{ok: true}|array{ok: false, error: string}findUser()
public
static findUser(string $lookup) : array{user_id: int}|array{error: string}
Parameters
- $lookup : string
Return values
array{user_id: int}|array{error: string}grants()
One page of grants, newest first.
public
static grants([int $start = 0 ]) : array{rows: array>, start: int, more: bool, length: int}
Parameters
- $start : int = 0
Return values
array{rows: arrayhandGrant()
Hand out a system-scope grant. No application row.
public
static handGrant(string $userLookup, string $permission, string $expiresRaw, int $grantorId) : array{ok: true, grant_id: int}|array{ok: false, error: string}
Parameters
- $userLookup : string
-
User id or email.
- $permission : string
- $expiresRaw : string
-
Empty, or a datetime-local value.
- $grantorId : int
-
Logged-in admin, or 0.
Return values
array{ok: true, grant_id: int}|array{ok: false, error: string}isActive()
A grant still allows the permission.
public
static isActive(array<string, mixed> $row[, int|null $now = null ]) : mixed
Parameters
- $row : array<string, mixed>
- $now : int|null = null
-
Unix time. Tests pass this.
latestApplication()
Newest application for this user and permission, any status.
public
static latestApplication(int $userId, string $permission) : array<string, mixed>|false
Parameters
- $userId : int
- $permission : string
Return values
array<string, mixed>|falsenotifyAdmins()
Email every admin address, and notify each matching user account.
public
static notifyAdmins(array<string, mixed> $application, array<string, mixed> $applicant[, bool $resubmit = false ]) : mixed
Mail is skipped when $CFG->OFFLINE is true, or when mail is not configured. A failed send does not undo the application.
A resubmit uses its own notice so it does not replace the original one.
Parameters
- $application : array<string, mixed>
- $applicant : array<string, mixed>
- $resubmit : bool = false
openApplication()
The application still in progress: pending, or sent back for revision.
public
static openApplication(int $userId, string $permission) : array<string, mixed>|false
Parameters
- $userId : int
- $permission : string
Return values
array<string, mixed>|falseparseExpires()
public
static parseExpires(string $raw) : array{at: string|null}|array{error: string}
Parameters
- $raw : string
Return values
array{at: string|null}|array{error: string}pendingApplication()
The user's pending application for this permission, or false.
public
static pendingApplication(int $userId, string $permission) : array<string, mixed>|false
Parameters
- $userId : int
- $permission : string
Return values
array<string, mixed>|falseregistry()
public
static registry() : array<string, array<string, mixed>>
Return values
array<string, array<string, mixed>>resubmitApplication()
Put a sent-back application back in the queue with a new justification.
public
static resubmitApplication(int $userId, int $applicationId, string $justification) : array{ok: true, application_id: int}|array{ok: false, error: string}
Parameters
- $userId : int
- $applicationId : int
- $justification : string
Return values
array{ok: true, application_id: int}|array{ok: false, error: string}reviewApplication()
Approve, reject, or send back a pending application.
public
static reviewApplication(int $applicationId, string $decision, int $reviewerId[, string $response = '' ]) : array{ok: true, status: string}|array{ok: false, error: string}
Approval writes the grant in the same transaction as the status change. Sending it back keeps the same row so the applicant can edit and resubmit. A reply is required for that. Each decision notifies the applicant. A second review of the same row is refused.
Parameters
- $applicationId : int
- $decision : string
-
approved, denied, or revision
- $reviewerId : int
- $response : string = ''
-
Note included in the notification. Required for revision.
Return values
array{ok: true, status: string}|array{ok: false, error: string}revokeGrant()
public
static revokeGrant(int $grantId, int $revokedBy) : array{ok: true}|array{ok: false, error: string}
Parameters
- $grantId : int
- $revokedBy : int
Return values
array{ok: true}|array{ok: false, error: string}scopes()
public
static scopes() : array<int, array<string, mixed>>
Return values
array<int, array<string, mixed>>submitApplication()
Store a pending application and tell the admin emails.
public
static submitApplication(int $userId, string $permission, string $justification) : array{ok: true, application_id: int}|array{ok: false, error: string}
A denied or approved row stays. A second in-progress row is refused. A racing second insert updates that same row. The open_slot unique key makes the later write win instead of adding another request.
Parameters
- $userId : int
- $permission : string
- $justification : string
Return values
array{ok: true, application_id: int}|array{ok: false, error: string}syncCourseCreateFlag()
Keep a course.create grant in step with lti_user.create_courses.
public
static syncCourseCreateFlag(int $userId, bool $enabled[, bool $dieOnError = true ]) : bool
Turning the flag on adds a system-scope grant when the user has no active one. Turning it off revokes grants that came from that flag. A hand grant is left alone.
Parameters
- $userId : int
- $enabled : bool
- $dieOnError : bool = true
-
When false, a failed write returns false instead of stopping the request.
Return values
bool —False only when a write was attempted and failed and $dieOnError is false.
userLabel()
Name, email, and user id for an application or grant row.
public
static userLabel(array<string, mixed> $row) : string
Parameters
- $row : array<string, mixed>
Return values
stringwithdrawApplication()
Delete the user's own in-progress application.
public
static withdrawApplication(int $userId, int $applicationId) : array{ok: true}|array{ok: false, error: string}
Parameters
- $userId : int
- $applicationId : int
Return values
array{ok: true}|array{ok: false, error: string}connection()
private
static connection() : mixed
notifyApplicant()
In-app notice to the applicant. A failed send leaves the decision in place.
private
static notifyApplicant(array<string, mixed> $application, string $status) : mixed
Parameters
- $application : array<string, mixed>
- $status : string
openSlot()
Unique while a request is in progress. Cleared after approve or reject.
private
static openSlot(int $userId, string $permission) : mixed
Parameters
- $userId : int
- $permission : string
pageResult()
private
static pageResult(array<int, array<string, mixed>> $rows, int $start) : array{rows: array>, start: int, more: bool, length: int}
Parameters
- $rows : array<int, array<string, mixed>>
- $start : int
Return values
array{rows: arraysaveGrant()
Insert one system-scope grant, or refresh the row that is already there.
private
static saveGrant(int $uid, string $permission, string $source, int $grantorId, string|null $expiresAt[, int|null $applicationId = null ][, bool $dieOnError = true ]) : int
The unique key is (user_id, scope_id, permission). A second insert for that triple updates the same row and clears revocation.
Parameters
- $uid : int
- $permission : string
- $source : string
- $grantorId : int
- $expiresAt : string|null
- $applicationId : int|null = null
- $dieOnError : bool = true
Return values
int —Grant id, or 0 when $dieOnError is false and the write failed.
usersByEmail()
Site-login accounts (the google.com key) whose email is in the list.
private
static usersByEmail(array<int, string> $emails) : array<int, int>
An LMS launch can store the same address on another key. Those rows are not notified.
Parameters
- $emails : array<int, string>
-
Lowercased addresses.