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
GUID_PREFIX
public
mixed
GUID_PREFIX
= 'm'
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}|nullgetAssignmentsForEvidence()
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}|nullisMintedGuid()
Check if an id is a minted badge GUID.
public
static isMintedGuid(string $id) : bool
Parameters
- $id : string
Return values
boolissuerSnapshot()
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|nulllessonsForContext()
public
static lessonsForContext(int $context_id[, LessonsService|null $siteLessons = null ]) : LessonsService|null
Parameters
- $context_id : int
- $siteLessons : LessonsService|null = null
Return values
LessonsService|nulllinkedInDestinationUrl()
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
stringmintedDisplayRow()
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}|nullmintOrGet()
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
boolstoreImageBytes()
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}|nullsyntheticBadge()
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
objecttableExists()
Check if the badges table exists.
public
static tableExists() : bool
Return values
boolaccomplishmentsForRow()
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|nullcredentialIdFromRow()
private
static credentialIdFromRow(array<string, mixed> $row) : string|null
Parameters
- $row : array<string, mixed>
Return values
string|nulldecodeAccomplishments()
private
static decodeAccomplishments(mixed $raw) : array<string, mixed>|null
Parameters
- $raw : mixed
Return values
array<string, mixed>|nullencodeAccomplishments()
private
static encodeAccomplishments(array<string, mixed> $accomplishments) : string
Parameters
- $accomplishments : array<string, mixed>
Return values
stringfindImageBySha()
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}|nullimageColumnsReady()
private
static imageColumnsReady() : bool
Return values
boolimageSnapshot()
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>siteLessons()
private
static siteLessons() : LessonsService|null
Return values
LessonsService|nullstoredImageForBadgeCode()
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