Tsugi

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_REVISION

Sent back so the applicant can edit the same row and resubmit.

public mixed STATUS_REVISION = 'revision'

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: array>, start: int, more: bool, length: int}

decisionNotice()

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: array>, start: int, more: bool, length: int}

handGrant()

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>|false

notifyAdmins()

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>|false

parseExpires()

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>|false

registry()

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
string

withdrawApplication()

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}

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: array>, start: int, more: bool, length: int}

saveGrant()

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.

Return values
array<int, int>

        
On this page

Search results