Status & live reports

Two status surfaces answer different questions. Certificates::status() reads the registry — the CertificateStatus of the latest record, or null. Certificates::statusReport() asks the provider live and returns a CertificateStatusReport, cached per status_cache.*:

Certificates::statusReport('app.example.com');               // cached
Certificates::statusReport('app.example.com', fresh: true);  // bypass + refresh
Certificates::for('app.example.com')->fresh()->statusReport();

$report = Certificates::statusReport('app.example.com', driver: 'acme');

$report?->status;       // CertificateStatus
$report?->expiresAt;    // CarbonImmutable|null
$report?->issuer;       // ?string
$report?->serial;       // ?string
$report?->fingerprint;  // ?string
$report?->domains;      // list<string> — SANs

statusReport() returns null for a driver that cannot report status — null, or a custom driver without ReportsCertificateStatus.

Caching

With status_cache.enabled, each report is cached on status_cache.store for status_cache.ttl seconds under a key per driver and certificate name. fresh: true — or ->fresh() on the builder — re-queries the provider and refreshes the cached entry. issue() and renew() drop that certificate’s cached report, so the next statusReport() reads the new state instead of the one cached before the change. To drop an entry yourself, forget it on the resolver:

use RoundlyConsulting\Certificates\Support\CachedStatusResolver;

app(CachedStatusResolver::class)->forget('acme', Certificates::certificateName('app.example.com'));

The CertificateStatus enum

The model’s status column is cast to a string-backed enum with a native state machine:

Case	Value	Colour	Can move to
`Pending`	pending	amber	Requested
`Requested`	requested	amber	Issued, Failed
`Issued`	issued	green	Renewing, Expired, Revoked
`Renewing`	renewing	amber	Renewed, Failed
`Renewed`	renewed	green	Renewing, Expired, Revoked
`Failed`	failed	red	Renewing — a failed row can be renewed again
`Expired`	expired	red	— (terminal)
`Revoked`	revoked	red	— (terminal)

use RoundlyConsulting\Certificates\Enums\CertificateStatus;

CertificateStatus::Issued->isActive();              // true
CertificateStatus::Revoked->isTerminal();           // true
CertificateStatus::Failed->isTerminal();            // false — a failed row can be renewed again
CertificateStatus::Requested->canTransitionTo(CertificateStatus::Issued); // true
CertificateStatus::Failed->canTransitionTo(CertificateStatus::Renewing);  // true
CertificateStatus::Issued->allowedTransitions();    // [Renewing, Expired, Revoked]
CertificateStatus::Issued->color();                 // 'green'
CertificateStatus::Issued->label();                 // 'Issued'

CertificateStatus::toOptions();       // value => label, for selects
CertificateStatus::validationRule();  // 'in:pending,requested,issued,...'

isActive() is true for Issued and Renewed; isTerminal() for Expired and Revoked — only a fresh issue() revives those rows. Failed is not terminal: a failed issuance or renewal can be renewed again. The enum adopts enums-for-laravel’s Helpers trait, adding values(), labels(), options(), toOptions(), validationRule(), tryFromLabel() and more for admin UIs and validation.

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

Get a quote in 48 hours Browse all packages