Tsugi

Badges
in package

Open Badges 2.0 and 3.0 JSON generation utilities

This class provides methods for generating Open Badges assertion, badge class, and issuer JSON in both OB2 and OB3 formats.

Table of Contents

Constants

DEFAULT_ISSUER_EMAIL  : mixed = "badge_issuer_email_not_set@example.com"
OB2_CONTEXT  : mixed = "https://w3id.org/openbadges/v2"
OB3_CREDENTIALS_CONTEXT  : mixed = "https://www.w3.org/ns/credentials/v2"
OB3_OPENBADGES_CONTEXT  : mixed = "https://purl.imsglobal.org/spec/ob/v3p0/contex...

Methods

checkBadgeConfig()  : string|false
Check if badge configuration is properly set up.
contextIdFromAssertion()  : int
Course id stored in an unpublished assertion id, or 0.
getOb2Assertion()  : string
Get OB2 Assertion JSON
getOb2Badge()  : string
Get OB2 BadgeClass JSON
getOb2Issuer()  : string
Get OB2 Issuer JSON
getOb3Achievement()  : string
Get OB3 Achievement JSON
getOb3Assertion()  : string
Get OB3/VC Assertion JSON (Verifiable Credential)
getOb3Issuer()  : string
Get OB3 Issuer JSON
liveImageUrl()  : string
Live image URL for a badge that has not been published yet.
parseAssertionId()  : mixed
assertionResourceUrl()  : mixed
badgeFromLessons()  : object|null
Badge definition from the current lessons list, or null.
buildAssertionUrl()  : string
Build assertion URL
buildBadgeUrl()  : string
Build badge class URL (OB2 - no query params)
buildBadgeUrlWithFormat()  : string
Build badge class URL with format (OB3 only)
buildEvidenceNarrative()  : string
Build evidence narrative
buildIssuerUrl()  : string
Build issuer URL (OB2 - no query params)
buildIssuerUrlWithFormat()  : string
Build issuer URL with format (OB3 only)
claimImage()  : string
claimNarrative()  : mixed
courseScopedResource()  : string|null
Manifest badges are fetched from the assertion id, which names the course.
frozenString()  : mixed
getIssuerEmail()  : string
Get the issuer email from config or return default
issuerFields()  : array{name: string, url: string, email: string, logo: string, linkedin_url: string}
Issuer profile fields. Frozen values win for a published badge.
needsBadgeFiles()  : bool
Site badge folder is required only for an unpublished file-based image.
normalizeDateToZ()  : string
Normalize ISO8601 date to Z format (required by Badgr/Credly) Converts +00:00 to Z
pngBytes()  : string|null
PNG bytes for baking. Public files come from the course. Otherwise badge_path.
useFrozen()  : mixed
A published badge carries its claims. Unminted badges keep reading config.

Constants

DEFAULT_ISSUER_EMAIL

public mixed DEFAULT_ISSUER_EMAIL = "badge_issuer_email_not_set@example.com"

OB2_CONTEXT

public mixed OB2_CONTEXT = "https://w3id.org/openbadges/v2"

OB3_CREDENTIALS_CONTEXT

public mixed OB3_CREDENTIALS_CONTEXT = "https://www.w3.org/ns/credentials/v2"

OB3_OPENBADGES_CONTEXT

public mixed OB3_OPENBADGES_CONTEXT = "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json"

Methods

checkBadgeConfig()

Check if badge configuration is properly set up.

public static checkBadgeConfig([bool $requireFiles = true ]) : string|false

Identity (encrypt password and salt) is always required. The site badge folder is required for file-based badge images. Manifest badges that use Files Public do not need it.

Returns an error message string if configuration is missing, or false if OK.

Parameters
$requireFiles : bool = true

When false, badge_path and badge_url are not required

Return values
string|false —

Error message string or false if OK

contextIdFromAssertion()

Course id stored in an unpublished assertion id, or 0.

public static contextIdFromAssertion(mixed $encrypted) : int
Parameters
$encrypted : mixed
Return values
int

getOb2Assertion()

Get OB2 Assertion JSON

public static getOb2Assertion(string $encrypted, string $date, string $code, object $badge, string $title, string $email[, array<string, mixed>|null $frozen = null ]) : string
Parameters
$encrypted : string

The encrypted assertion ID

$date : string

The issuance date (ISO 8601)

$code : string

The badge code

$badge : object

The badge object

$title : string

The course title

$email : string

The recipient email

$frozen : array<string, mixed>|null = null

Published-badge snapshot. Null reads live config.

Return values
string —

JSON-encoded assertion

getOb2Badge()

Get OB2 BadgeClass JSON

public static getOb2Badge(string|null $encrypted, string $code, object $badge, string $title[, array<string, mixed>|null $frozen = null ]) : string
Parameters
$encrypted : string|null

The encrypted assertion ID (optional, for per-badge issuer)

$code : string

The badge code

$badge : object

The badge object

$title : string

The course title

$frozen : array<string, mixed>|null = null

Published-badge snapshot. Null reads live config.

Return values
string —

JSON-encoded badge class

getOb2Issuer()

Get OB2 Issuer JSON

public static getOb2Issuer([string|null $encrypted = null ][, string|null $code = null ][, object|null $badge = null ][, string|null $title = null ][, array<string, mixed>|null $frozen = null ]) : string
Parameters
$encrypted : string|null = null

The encrypted assertion ID (optional, for per-badge issuer)

$code : string|null = null

The badge code (optional)

$badge : object|null = null

The badge object (optional)

$title : string|null = null

The course title (optional)

$frozen : array<string, mixed>|null = null

Published-badge snapshot. Null reads live config.

Return values
string —

JSON-encoded issuer

getOb3Achievement()

Get OB3 Achievement JSON

public static getOb3Achievement(string|null $encrypted, string $code, object $badge, string $title[, array<string, mixed>|null $frozen = null ]) : string
Parameters
$encrypted : string|null

The encrypted assertion ID (optional)

$code : string

The badge code

$badge : object

The badge object

$title : string

The course title

$frozen : array<string, mixed>|null = null

Published-badge snapshot. Null reads live config.

Return values
string —

JSON-encoded achievement

getOb3Assertion()

Get OB3/VC Assertion JSON (Verifiable Credential)

public static getOb3Assertion(string $encrypted, string $date, string $code, object $badge, string $title, string $email[, array<string, mixed>|null $frozen = null ]) : string
Parameters
$encrypted : string

The encrypted assertion ID

$date : string

The issuance date (ISO 8601)

$code : string

The badge code

$badge : object

The badge object

$title : string

The course title

$email : string

The recipient email

$frozen : array<string, mixed>|null = null

Published-badge snapshot. Null reads live config.

Return values
string —

JSON-encoded credential

getOb3Issuer()

Get OB3 Issuer JSON

public static getOb3Issuer([string|null $encrypted = null ][, string|null $code = null ][, object|null $badge = null ][, string|null $title = null ][, array<string, mixed>|null $frozen = null ]) : string
Parameters
$encrypted : string|null = null

The encrypted assertion ID (optional)

$code : string|null = null

The badge code (optional)

$badge : object|null = null

The badge object (optional)

$title : string|null = null

The course title (optional)

$frozen : array<string, mixed>|null = null

Published-badge snapshot. Null reads live config.

Return values
string —

JSON-encoded issuer

liveImageUrl()

Live image URL for a badge that has not been published yet.

public static liveImageUrl(object|null $badge, string $code[, int $contextId = 0 ]) : string

A course Public image stays on that course's file. A missing Public file does not fall through to the site badge folder.

Parameters
$badge : object|null
$code : string
$contextId : int = 0
Return values
string

parseAssertionId()

public static parseAssertionId(mixed $encrypted, mixed $lesson) : mixed
Parameters
$encrypted : mixed
$lesson : mixed

assertionResourceUrl()

private static assertionResourceUrl(mixed $guid, mixed $resource) : mixed
Parameters
$guid : mixed
$resource : mixed

badgeFromLessons()

Badge definition from the current lessons list, or null.

private static badgeFromLessons(object $lesson, string $code) : object|null
Parameters
$lesson : object
$code : string
Return values
object|null

buildAssertionUrl()

Build assertion URL

private static buildAssertionUrl(string $encrypted) : string
Parameters
$encrypted : string

The encrypted assertion ID

Return values
string —

The assertion URL

buildBadgeUrl()

Build badge class URL (OB2 - no query params)

private static buildBadgeUrl(string $code) : string
Parameters
$code : string

The badge code

Return values
string —

The badge class URL

buildBadgeUrlWithFormat()

Build badge class URL with format (OB3 only)

private static buildBadgeUrlWithFormat(string $code, string $format) : string
Parameters
$code : string

The badge code

$format : string

Format parameter (e.g., 'ob3')

Return values
string —

The badge class URL with format

buildEvidenceNarrative()

Build evidence narrative

private static buildEvidenceNarrative(object $badge, string $title) : string
Parameters
$badge : object

The badge object

$title : string

The course title

Return values
string —

The evidence narrative

buildIssuerUrl()

Build issuer URL (OB2 - no query params)

private static buildIssuerUrl() : string
Return values
string —

The issuer URL

buildIssuerUrlWithFormat()

Build issuer URL with format (OB3 only)

private static buildIssuerUrlWithFormat(string $format) : string
Parameters
$format : string

Format parameter (e.g., 'ob3')

Return values
string —

The issuer URL with format

claimImage()

private static claimImage(object|null $badge, mixed $code, array<string, mixed>|null $frozen[, mixed $encrypted = null ]) : string
Parameters
$badge : object|null
$code : mixed
$frozen : array<string, mixed>|null
$encrypted : mixed = null
Return values
string

claimNarrative()

private static claimNarrative(mixed $badge, mixed $title, array<string, mixed>|null $frozen) : mixed
Parameters
$badge : mixed
$title : mixed
$frozen : array<string, mixed>|null

courseScopedResource()

Manifest badges are fetched from the assertion id, which names the course.

private static courseScopedResource(mixed $encrypted, object|null $badge, string $resource) : string|null
Parameters
$encrypted : mixed
$badge : object|null
$resource : string
Return values
string|null

frozenString()

private static frozenString(array<string, mixed>|null $frozen, mixed $key, mixed $default) : mixed
Parameters
$frozen : array<string, mixed>|null
$key : mixed
$default : mixed

getIssuerEmail()

Get the issuer email from config or return default

private static getIssuerEmail() : string
Return values
string —

The issuer email address

issuerFields()

Issuer profile fields. Frozen values win for a published badge.

private static issuerFields(array<string, mixed>|null $frozen) : array{name: string, url: string, email: string, logo: string, linkedin_url: string}
Parameters
$frozen : array<string, mixed>|null
Return values
array{name: string, url: string, email: string, logo: string, linkedin_url: string}

needsBadgeFiles()

Site badge folder is required only for an unpublished file-based image.

private static needsBadgeFiles(object|null $badge, array<string, mixed>|null $frozen) : bool
Parameters
$badge : object|null
$frozen : array<string, mixed>|null
Return values
bool

normalizeDateToZ()

Normalize ISO8601 date to Z format (required by Badgr/Credly) Converts +00:00 to Z

private static normalizeDateToZ(string $date) : string
Parameters
$date : string

ISO8601 date string

Return values
string —

Date string ending with Z

pngBytes()

PNG bytes for baking. Public files come from the course. Otherwise badge_path.

private static pngBytes(object|null $badge, string $code, int $contextId) : string|null
Parameters
$badge : object|null
$code : string
$contextId : int
Return values
string|null

useFrozen()

A published badge carries its claims. Unminted badges keep reading config.

private static useFrozen(array<string, mixed>|null $frozen) : mixed
Parameters
$frozen : array<string, mixed>|null

        
On this page

Search results