Tsugi

BadgeService
in package

Service for minted badge operations (OB2/OB3).

Handles badge minting, lookup, baked images, and assertion data. Does not touch legacy /badges/ endpoints.

Table of Contents

Constants

GUID_LENGTH  : mixed = 33
GUID format: m + 32 hex chars
GUID_PREFIX  : mixed = 'm'
MAX_IMAGE_BYTES  : mixed = 5242880
Original badge files at or under this size are stored whole.

Methods

backfillMissingAccomplishments()  : void
Fill accomplishments for rows published before the column existed.
backfillStoredImages()  : void
Copy the site badge file onto rows that do not yet point at badge_images.
captureAccomplishments()  : array<string, mixed>
Snapshot of the badge definition and its assignment list.
clearSnapshotsMissingImageHash()  : int
Clear snapshots that were written before the image URL and hash were stored.
getAssertionDataForGuid()  : array{row: array, pieces: array, badge: object, frozen: array, image_id: int}|null
Assertion data for a minted GUID, from the badge row only.
getAssignmentsForEvidence()  : array<int, array{resource_link_id: string, title: string, href: ?string}>
Assignment list for the Evidence section, from the current lessons.
getByGuid()  : array<string|int, mixed>|null
Load minted badge by GUID.
getMintedGuidIfExists()  : string|null
Get minted badge GUID if it exists (no minting).
imageContentForGuid()  : array{mime_type: string, file_size: int, image_blob: string}|null
Bytes for a published badge, joined from badges.image_id.
isMintedGuid()  : bool
Check if an id is a minted badge GUID.
issuerSnapshot()  : array{name: string, url: string, email: string, logo?: string, linkedin_url?: string}
Issuer profile frozen at publish. Signing keys stay in config.
lessonsForAssertion()  : LessonsService|null
Lessons for the course named inside an unpublished assertion id.
lessonsForContext()  : LessonsService|null
linkedInDestinationUrl()  : string|null
Build the external LinkedIn URL for a minted badge (credential add or share post).
linkedInTrackingUrl()  : string
URL that records a LinkedIn click then redirects to LinkedIn.
mintedDisplayRow()  : array{displayname: string, email: string, user_key: string, login_at: string, title: string, badge_title: string}|null
Display row for a baked or legacy assertion after the course membership is gone.
mintOrGet()  : string|false
Mint a badge or refresh the snapshot on the existing row.
recordLinkedInClick()  : bool
Increment linkedin_clicks for a minted badge.
storeImageBytes()  : array{image_id: int, sha256: string, mime_type: string, file_size: int}|null
Copy image bytes into badge_images once, keyed by SHA-256.
syntheticBadge()  : object
Badge object from stored title when the course lessons no longer list this image.
tableExists()  : bool
Check if the badges table exists.
accomplishmentsForRow()  : array<string, mixed>
badgeDefinition()  : object|null
credentialIdFromRow()  : string|null
decodeAccomplishments()  : array<string, mixed>|null
encodeAccomplishments()  : string
findImageBySha()  : array{image_id: int, sha256: string, mime_type: string, file_size: int}|null
imageColumnsReady()  : bool
imageSnapshot()  : array{image_url: string, image_sha256: string}
Public image URL and the SHA-256 of the PNG bytes.
minimalAccomplishments()  : array<string, mixed>
Snapshot from the scalars already on the row, when lessons are gone.
siteLessons()  : LessonsService|null
storedImageForBadgeCode()  : array{image_id: ?int, sha256: string}|null
Read the PNG for this code.

Constants

GUID_LENGTH

GUID format: m + 32 hex chars

public mixed GUID_LENGTH = 33

MAX_IMAGE_BYTES

Original badge files at or under this size are stored whole.

public mixed MAX_IMAGE_BYTES = 5242880

Methods

backfillMissingAccomplishments()

Fill accomplishments for rows published before the column existed.

public static backfillMissingAccomplishments() : void

Uses the course manifest when the context still has one, otherwise the site lessons file. A row whose lessons are already gone gets a snapshot from the scalars already stored on it.

backfillStoredImages()

Copy the site badge file onto rows that do not yet point at badge_images.

public static backfillStoredImages() : void

A missing file is left alone so a later upgrade can try again. A file over the cap records its hash and does not store the bytes.

captureAccomplishments()

Snapshot of the badge definition and its assignment list.

public static captureAccomplishments(mixed $lessons, object $badge, string $context_title[, int $context_id = 0 ]) : array<string, mixed>

Called at publish, while lessons and the course still exist.

Parameters
$lessons : mixed
$badge : object

A lessons badge object

$context_title : string
$context_id : int = 0
Return values
array<string, mixed>

clearSnapshotsMissingImageHash()

Clear snapshots that were written before the image URL and hash were stored.

public static clearSnapshotsMissingImageHash() : int

A later upgrade leaves a row alone once image_sha256 is present, including when that hash is an empty string because the PNG was missing.

Return values
int —

Rows cleared

getAssertionDataForGuid()

Assertion data for a minted GUID, from the badge row only.

public static getAssertionDataForGuid(string $guid) : array{row: array, pieces: array, badge: object, frozen: array, image_id: int}|null
Parameters
$guid : string
Return values
array{row: array, pieces: array, badge: object, frozen: array, image_id: int}|null

getAssignmentsForEvidence()

Assignment list for the Evidence section, from the current lessons.

public static getAssignmentsForEvidence(string $badge_code, mixed $lessons[, int $contextId = 0 ]) : array<int, array{resource_link_id: string, title: string, href: ?string}>
Parameters
$badge_code : string
$lessons : mixed
$contextId : int = 0
Return values
array<int, array{resource_link_id: string, title: string, href: ?string}>

getByGuid()

Load minted badge by GUID.

public static getByGuid(string $guid) : array<string|int, mixed>|null
Parameters
$guid : string
Return values
array<string|int, mixed>|null —

Row data or null if not found

getMintedGuidIfExists()

Get minted badge GUID if it exists (no minting).

public static getMintedGuidIfExists(int $user_id, int $context_id, string $badge_code) : string|null
Parameters
$user_id : int
$context_id : int
$badge_code : string
Return values
string|null —

Badge GUID or null if not minted

imageContentForGuid()

Bytes for a published badge, joined from badges.image_id.

public static imageContentForGuid(string $guid) : array{mime_type: string, file_size: int, image_blob: string}|null
Parameters
$guid : string
Return values
array{mime_type: string, file_size: int, image_blob: string}|null

isMintedGuid()

Check if an id is a minted badge GUID.

public static isMintedGuid(string $id) : bool
Parameters
$id : string
Return values
bool

issuerSnapshot()

Issuer profile frozen at publish. Signing keys stay in config.

public static issuerSnapshot() : array{name: string, url: string, email: string, logo?: string, linkedin_url?: string}
Return values
array{name: string, url: string, email: string, logo?: string, linkedin_url?: string}

lessonsForAssertion()

Lessons for the course named inside an unpublished assertion id.

public static lessonsForAssertion(string $encrypted[, LessonsService|null $fallback = null ]) : LessonsService|null

A manifest course wins. Otherwise the current file-based lessons.

Parameters
$encrypted : string
$fallback : LessonsService|null = null
Return values
LessonsService|null

linkedInDestinationUrl()

Build the external LinkedIn URL for a minted badge (credential add or share post).

public static linkedInDestinationUrl(string $guid, bool $share) : string|null
Parameters
$guid : string
$share : bool
Return values
string|null —

LinkedIn URL or null if the badge cannot be shared this way

linkedInTrackingUrl()

URL that records a LinkedIn click then redirects to LinkedIn.

public static linkedInTrackingUrl(string $guid[, bool $share = false ]) : string
Parameters
$guid : string
$share : bool = false
Return values
string

mintedDisplayRow()

Display row for a baked or legacy assertion after the course membership is gone.

public static mintedDisplayRow(int $user_id, string $badge_code, int $context_id) : array{displayname: string, email: string, user_key: string, login_at: string, title: string, badge_title: string}|null

Prefers a row that still has this context_id, then a row detached by course delete (context_id NULL). Name, email, course title, and issue time come from the badge row.

Parameters
$user_id : int
$badge_code : string
$context_id : int
Return values
array{displayname: string, email: string, user_key: string, login_at: string, title: string, badge_title: string}|null

mintOrGet()

Mint a badge or refresh the snapshot on the existing row.

public static mintOrGet(int $user_id, int $context_id, string $badge_code, string $user_displayname, string $user_email, string $context_title, string $badge_title[, array<string, mixed>|null $accomplishments = null ]) : string|false

The GUID and issued_at stay put on republish. Name, email, course title, badge title, and accomplishments are rewritten from the live course.

Parameters
$user_id : int
$context_id : int
$badge_code : string
$user_displayname : string
$user_email : string
$context_title : string
$badge_title : string
$accomplishments : array<string, mixed>|null = null
Return values
string|false —

The badge GUID, or false if table missing/error

recordLinkedInClick()

Increment linkedin_clicks for a minted badge.

public static recordLinkedInClick(string $guid) : bool
Parameters
$guid : string
Return values
bool

storeImageBytes()

Copy image bytes into badge_images once, keyed by SHA-256.

public static storeImageBytes(string $bytes) : array{image_id: int, sha256: string, mime_type: string, file_size: int}|null

A later call with the same bytes returns the existing row. Files larger than MAX_IMAGE_BYTES are not stored.

Parameters
$bytes : string
Return values
array{image_id: int, sha256: string, mime_type: string, file_size: int}|null

syntheticBadge()

Badge object from stored title when the course lessons no longer list this image.

public static syntheticBadge(string $badge_code, string $badge_title) : object
Parameters
$badge_code : string
$badge_title : string
Return values
object

tableExists()

Check if the badges table exists.

public static tableExists() : bool
Return values
bool

accomplishmentsForRow()

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

badgeDefinition()

private static badgeDefinition(LessonsService|null $lessons, string $badge_code) : object|null
Parameters
$lessons : LessonsService|null
$badge_code : string
Return values
object|null

credentialIdFromRow()

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

decodeAccomplishments()

private static decodeAccomplishments(mixed $raw) : array<string, mixed>|null
Parameters
$raw : mixed
Return values
array<string, mixed>|null

encodeAccomplishments()

private static encodeAccomplishments(array<string, mixed> $accomplishments) : string
Parameters
$accomplishments : array<string, mixed>
Return values
string

findImageBySha()

private static findImageBySha(string $sha) : array{image_id: int, sha256: string, mime_type: string, file_size: int}|null
Parameters
$sha : string
Return values
array{image_id: int, sha256: string, mime_type: string, file_size: int}|null

imageColumnsReady()

private static imageColumnsReady() : bool
Return values
bool

imageSnapshot()

Public image URL and the SHA-256 of the PNG bytes.

private static imageSnapshot(string $code[, string $imagePath = '' ][, int $contextId = 0 ]) : array{image_url: string, image_sha256: string}

A Public files path is read from that course. Anything else is the site badge folder. An empty hash means the file was not readable when the snapshot was written. The key is still stored so a later upgrade does not clear the row again.

Parameters
$code : string
$imagePath : string = ''
$contextId : int = 0
Return values
array{image_url: string, image_sha256: string}

minimalAccomplishments()

Snapshot from the scalars already on the row, when lessons are gone.

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

storedImageForBadgeCode()

Read the PNG for this code.

private static storedImageForBadgeCode(string $code[, int $contextId = 0 ]) : array{image_id: ?int, sha256: string}|null

A manifest badge whose image is in Files Public is copied from that file. Otherwise the site badge folder is used. Null means the file is not there yet. image_id is null when the file is over the cap; sha256 is still set so the row is not retried.

Parameters
$code : string
$contextId : int = 0
Return values
array{image_id: ?int, sha256: string}|null

        
On this page

Search results