Certificates API

Updated for version 0.9.80+

The Certificates module now uses a shared multi-mode architecture. Bricks Builder, PDF Builder, and Both templates share one certificate issuance pipeline, one snapshot model, and one verification/download system.

Module Status

use BaselMedia\BricksMembers\Core\ModuleRegistry;

if ( ModuleRegistry::is_active( 'certificates' ) ) {
    // Certificates module is available.
}

Template Engines

Bricks Builder

Bricks templates keep using the certificate post type, Bricks rendering, certificate dynamic tags, and DOMPDF export.

PDF Builder

PDF Builder templates store a fixed-canvas document definition and render through TCPDF with direct block composition.

Both

both templates use Bricks Builder for the public digital certificate page and PDF Builder for the downloadable and inline PDF output. The initial Bricks layout is generated from the selected PDF Builder preset.

Both engines share:

the brm_certificate post type
the {prefix}brm_certificates table
snapshot generation
verification / download / QR URLs
rules and manual awards
Open Badges integration

Core Services

CertificateService

Namespace: BaselMedia\BricksMembers\Modules\Certificates\CertificateService

Main issuance, lookup, rule, snapshot, and cache-invalidation service.

$service = \BaselMedia\BricksMembers\Modules\Certificates\CertificateService::get_instance();

$certificate_id = $service->issue_certificate(
    $user_id,
    $template_id,
    $rule_id,
    $scope_type,
    $scope_id,
    $score,
    $expiry_days
);

$certificate = $service->get_certificate( $certificate_id );
$certificate = $service->get_certificate_by_hash( $hash );
$certificates = $service->get_user_certificates( $user_id, array(
    'status'     => 'active',
    'scope_type' => 'post',
    'scope_id'   => 123,
) );

Important responsibilities:

rule normalization and validation
one-rule-per-template enforcement
multi-target support for post and quiz triggers
preview certificate context generation for admin previews
snapshot URL generation through CertificateUrlService

CertificateTemplateService

Normalizes template settings and creates templates from either Bricks starters or PDF Builder presets.

Shared settings include:

render_engine
layout_type
page_size
orientation
public_view_mode
display_page_id
verification_page_id
success_page_id — per-template page shown after a user earns this certificate (e.g. after passing a quiz). Design in Bricks with certificate dynamic tags.
number_format
Open Badges settings

CertificateDesignerService

PDF Builder document storage and normalization service.

Meta key: _brm_certificate_designer_document

Responsibilities:

document schema validation
preset loading
format normalization
block whitelist enforcement
numeric range validation
legacy preset correction/self-heal logic

CertificateDesignerBlockRegistry

Defines supported PDF Builder block types and default payloads.

Supported block types:

text
image
icon
qr
shape

CertificatePlaceholderRegistry

Shared registry for certificate dynamic tags and PDF Builder placeholders.

It resolves:

Bricks dynamic tags such as {brm_cert:student_name}
PDF Builder placeholders such as {{student_name}}
preview values used by the builder preview UI

CertificateUrlService

Builds all certificate-facing URLs.

$urls = \BaselMedia\BricksMembers\Modules\Certificates\CertificateUrlService::get_instance();

$verify   = $urls->get_verification_url( $hash );
$download = $urls->get_download_url( $hash );
$pdf      = $urls->get_pdf_url( $hash );
$qr       = $urls->get_qr_url( $hash );
$display  = $urls->get_display_url_for_template( $template_id, $hash, $settings );

CertificatePdfGenerator

Certificate PDF entrypoint. It selects the correct engine:

Bricks templates → HTML render + DOMPDF
PDF Builder templates → CertificateDesignerPdfComposer + TCPDF

CertificateDesignerPdfComposer

Direct PDF composer for PDF Builder templates.

It renders:

background fill and optional background image
text blocks as real text
image blocks
icon blocks from Bricks icon libraries or media icons
QR blocks
shape blocks with solid fills, gradients, and image fills

CertificateDesignerIconLibrary

Bridges the PDF Builder icon block to Bricks icon libraries and TCPDF font registration.

Supported libraries:

Font Awesome Solid
Font Awesome Regular
Font Awesome Brands
Ionicons
Themify

CertificatePdfFontRegistry

Curated font registry for PDF Builder text blocks.

helvetica
times
courier
dejavu_sans
dejavu_serif

Storage and Meta

Certificate Template Post Type

Post type: brm_certificate

Shared Settings Meta

Meta key: _brm_certificate_settings

Important keys:

render_engine
layout_type
page_size
orientation
public_view_mode
display_page_id
number_format
Open Badges fields

PDF Builder Document Meta

Meta key: _brm_certificate_designer_document

Document root keys:

version
page
background
guides
blocks

Issued Certificates Table

Table: {prefix}brm_certificates

Important columns:

id
user_id
template_id
rule_id
certificate_number
scope_type
scope_id
score
verification_hash
snapshot
status

Public Routes

Route	Purpose
`/certificate/verify/{hash}`	Verification page
`/certificate/download/{hash}`	Attachment download
`/certificate/pdf/{hash}`	Inline/open-in-browser PDF
`/certificate/qr/{hash}`	QR PNG

Admin preview requests also use signed query-arg URLs for:

template preview PDF
template preview QR
template preview Bricks display page

CertificateSystem is responsible for request routing and for injecting certificate context into Bricks pages when brm_cert_hash or preview query args are present.

AJAX Endpoints

Registered by BaselMedia\BricksMembers\Ajax\CertificateActions.

Action	Description
`brm_certificate_create_from_template`	Create template from Bricks starter or PDF Builder preset
`brm_certificate_save_settings`	Save template settings including display mode
`brm_certificate_save_rules`	Save automatic issuance rules
`brm_certificate_save_designer_document`	Save PDF Builder document JSON
`brm_certificate_rename_template`	Rename certificate template inline in the builder
`brm_certificate_issue`	Manual certificate issuance
`brm_certificate_bulk_issue`	Bulk issue
`brm_certificate_revoke`	Revoke certificate
`brm_certificate_bulk_revoke`	Bulk revoke
`brm_certificate_delete`	Delete certificate record
`brm_certificate_regenerate_pdf`	Regenerate cached PDF
`brm_certificate_get_stats`	Fetch template issuance stats

All admin mutations are nonce-protected and use capability checks via the shared Security utility.

Dynamic Tags and Placeholders

Bricks Dynamic Tags

Certificate tags resolve from: (1) brm_cert_hash in the URL (verification page, display page), (2) BRM: User Certificates query loop, or (3) success page context (logged-in user’s most recent certificate).

Core tags include:

{brm_cert:student_name}, {brm_cert:student_first_name}, {brm_cert:student_last_name}, {brm_cert:student_email}, {brm_cert:student_username}, {brm_cert:student_avatar_url}
{brm_cert:scope_title}, {brm_cert:scope_url}, {brm_cert:scope_type}, {brm_cert:scope_featured_image_url}, {brm_cert:scope_video_image_url}
{brm_cert:issued_date}, {brm_cert:expires_date}, {brm_cert:number} (alias: {brm_cert:certificate_number}), {brm_cert:score}, {brm_cert:template_title}, {brm_cert:status}
{brm_cert:site_name}, {brm_cert:site_logo_url}
{brm_cert:verification_url}, {brm_cert:display_url}, {brm_cert:download_url}, {brm_cert:pdf:url}, {brm_cert:qr_url}
Open Badges (when enabled): {brm_cert:badge_image_url}, {brm_cert:badge_assertion_url}, {brm_cert:badge_url}

Verification page: Set verification_page_id in template settings to use a custom Bricks page. Visitors land with ?brm_cert_hash=xxx; all tags resolve. If unset, the built-in verification route is used.

Success page: Set success_page_id in template settings. Context comes from the logged-in user’s most recent certificate (no hash in URL).

Status marker: Template settings also include status_marker_enabled. When enabled, revoked or expired certificates get a shared overlay/banner treatment on public certificate pages and generated PDFs. Leave it off only when the template handles invalid states explicitly.

PDF Builder Placeholders

PDF Builder uses the same data source with {{field_name}} tokens.

{{student_name}}
{{scope_title}}
{{number}}
{{verification_url}}
{{pdf_url}}

Bricks Elements

BRM Certificate PDF — PDF iframe viewer for dashboards or Bricks display pages

All other certificate output in Bricks now uses native Bricks elements plus certificate dynamic tags such as {brm_cert:download_url}, {brm_cert:verification_url}, {brm_cert:qr_url}, and {brm_cert:status}.

Open Badges

Open Badges is still a separate module, but it integrates directly with certificates through template settings and snapshot URLs.

Revoked badge assertions now expose revoked: true, and the badge image endpoint streams raw PNG output for compliant badge consumers.

Key REST endpoints:

/wp-json/bricksmembers/v1/badges/issuer
/wp-json/bricksmembers/v1/badges/class/{template_id}
/wp-json/bricksmembers/v1/badges/class/{template_id}/image
/wp-json/bricksmembers/v1/badges/assertion/{hash}
/wp-json/bricksmembers/v1/badges/assertion/{hash}/image

Hooks and Events

Typed certificate events still fire through the event system:

add_action( 'brm_event_certificate_issued', function ( $event ) {
    $context = $event->get_context();
}, 10, 1 );

add_action( 'brm_event_certificate_revoked', function ( $event ) {
    $context = $event->get_context();
}, 10, 1 );

add_action( 'brm_event_certificate_expired', function ( $event ) {
    $context = $event->get_context();
}, 10, 1 );

Useful extension filters include:

brm_certificate_snapshot
brm_certificate_rules
brm_certificate_number