Merge pull request #4 from blendbyte/event-hooks-callbacks

Add onIssued/onRenewed event callbacks

Author: bashgeek

README.md

@@ -120,6 +120,7 @@ echo $cert->caBundle;    // PEM intermediate chain
 - [Challenge handlers](#challenge-handlers)
 - [Storage backends](#storage-backends)
 - [Issuing certificates](#issuing-certificates)
+- [Event callbacks](#event-callbacks)
 - [CAA pre-check](#caa-pre-check)
 - [Wildcard and multi-domain certificates](#wildcard-and-multi-domain-certificates)
 - [IP address certificates](#ip-address-certificates-rfc-8738)
@@ -537,6 +538,47 @@ Returns `true` when:
 
 ---
 
+## Event callbacks
+
+Register callbacks on the builder to react to certificate lifecycle events without subclassing or parsing log output. Useful for reloading a web server, pushing secrets to a vault, or sending a Slack notification.
+
+### onIssued
+
+Fires after every successful certificate issuance — whether first-time or a renewal.
+
+```php
+CoyoteCert::with(new LetsEncrypt())
+    ->storage(new FilesystemStorage('/var/certs'))
+    ->identifiers('example.com')
+    ->challenge(new Http01Handler('/var/www/html'))
+    ->onIssued(function (StoredCertificate $cert): void {
+        SecretsManager::push('tls/example.com', [
+            'cert'     => $cert->certificate,
+            'key'      => $cert->privateKey,
+            'fullchain'=> $cert->fullchain,
+        ]);
+    })
+    ->issueOrRenew();
+```
+
+### onRenewed
+
+Fires only when an existing certificate is replaced — i.e. storage already held a cert before the new one was issued. Fires _after_ `onIssued` callbacks.
+
+```php
+CoyoteCert::with(new LetsEncrypt())
+    ->storage(new FilesystemStorage('/var/certs'))
+    ->identifiers('example.com')
+    ->challenge(new Http01Handler('/var/www/html'))
+    ->onIssued(fn($cert) => SecretsManager::push('tls/example.com', $cert->toArray()))
+    ->onRenewed(fn($cert) => Nginx::reload())
+    ->issueOrRenew();
+```
+
+Both methods accept any `callable` and can be called multiple times. Callbacks run in registration order, after the certificate has been saved to storage.
+
+---
+
 ## CAA pre-check
 
 [CAA (Certification Authority Authorization)](https://en.wikipedia.org/wiki/DNS_Certification_Authority_Authorization) is a DNS record type that restricts which CAs are allowed to issue certificates for a domain. If `example.com` has `CAA 0 issue "digicert.com"`, Let's Encrypt will refuse the order — but only after you have consumed a rate-limit attempt and waited for the ACME workflow to fail.
@@ -660,10 +702,8 @@ $cert = CoyoteCert::with(new LetsEncrypt())
     ->identifiers(['example.com', 'www.example.com'])
     ->challenge(new Http01Handler('/var/www/html'))
     ->logger($logger)
+    ->onRenewed(fn($cert) => exec('systemctl reload nginx'))
     ->issueOrRenew(daysBeforeExpiry: 30);
-
-// Reload web server only if a new certificate was issued
-// (compare serial or expiry to detect renewal)
 ```
 
 Add to crontab. Daily is sufficient; `issueOrRenew()` skips the CA call when nothing is due:
@@ -893,6 +933,8 @@ CoyoteCert::with(AcmeProviderInterface $provider)  // factory — select the CA
 | `->logger(LoggerInterface)` | fluent | none | PSR-3 logger |
 | `->skipLocalTest()` | fluent | off | Disable pre-flight HTTP/DNS self-check |
 | `->skipCaaCheck()` | fluent | off | Disable CAA DNS pre-check (internal CAs, split-horizon DNS) |
+| `->onIssued(callable)` | fluent | none | Callback fired after every successful issuance; receives `StoredCertificate` |
+| `->onRenewed(callable)` | fluent | none | Callback fired when an existing cert is replaced; receives `StoredCertificate` |
 | `->issue()` | terminal | — | Issue unconditionally; returns `StoredCertificate` |
 | `->renew()` | terminal | — | Alias for `issue()` |
 | `->issueOrRenew(int $days = 30)` | terminal | — | Issue only when needed; returns `StoredCertificate` |

src/CoyoteCert.php

@@ -57,6 +57,10 @@ class CoyoteCert
     private KeyType                    $accountKeyType   = KeyType::EC_P256;
     private bool                       $localTest        = true;
     private bool                       $skipCaaCheck     = false;
+    /** @var callable[] */
+    private array $onIssuedCallbacks = [];
+    /** @var callable[] */
+    private array $onRenewedCallbacks = [];
 
     private function __construct(private readonly AcmeProviderInterface $provider) {}
 
@@ -180,6 +184,31 @@ public function skipCaaCheck(): self
         return $this;
     }
 
+    /**
+     * Register a callback invoked after every successful certificate issuance.
+     * The callback receives the issued StoredCertificate as its sole argument.
+     * Multiple callbacks may be registered; they run in registration order.
+     */
+    public function onIssued(callable $callback): self
+    {
+        $this->onIssuedCallbacks[] = $callback;
+
+        return $this;
+    }
+
+    /**
+     * Register a callback invoked after a certificate is renewed (i.e. an existing
+     * certificate was replaced). Fires in addition to onIssued callbacks.
+     * The callback receives the new StoredCertificate as its sole argument.
+     * Multiple callbacks may be registered; they run in registration order.
+     */
+    public function onRenewed(callable $callback): self
+    {
+        $this->onRenewedCallbacks[] = $callback;
+
+        return $this;
+    }
+
     /**
      * Set the HTTP timeout in seconds for the built-in curl client.
      * No-op when a custom PSR-18 client is configured.
@@ -277,7 +306,10 @@ public function issue(): StoredCertificate
         // Refresh order — status transitions pending → ready after all challenges pass
         $order = $api->order()->refresh($order);
 
-        return $this->fetchAndStoreCertificate($api, $order);
+        $stored = $this->fetchAndStoreCertificate($api, $order);
+        $this->fireIssuedCallbacks($stored, isRenewal: $existingCert !== null);
+
+        return $stored;
     }
 
     // ── Private issue() helpers ───────────────────────────────────────────────
@@ -359,6 +391,19 @@ private function fetchAndStoreCertificate(
         return $stored;
     }
 
+    private function fireIssuedCallbacks(StoredCertificate $cert, bool $isRenewal): void
+    {
+        foreach ($this->onIssuedCallbacks as $cb) {
+            $cb($cert);
+        }
+
+        if ($isRenewal) {
+            foreach ($this->onRenewedCallbacks as $cb) {
+                $cb($cert);
+            }
+        }
+    }
+
     /**
      * Alias for issue() — forces a fresh certificate regardless of expiry.
      */

tests/Unit/CoyoteCertTest.php

@@ -393,6 +393,120 @@ public function sendRequest(\Psr\Http\Message\RequestInterface $r): \Psr\Http\Me
     expect($timeoutRef->getValue($client))->toBe(30);
 });
 
+// ── onIssued() / onRenewed() ──────────────────────────────────────────────────
+
+it('onIssued() returns self (fluent)', function () {
+    $c = makeCoyote();
+    expect($c->onIssued(fn($cert) => null))->toBe($c);
+});
+
+it('onRenewed() returns self (fluent)', function () {
+    $c = makeCoyote();
+    expect($c->onRenewed(fn($cert) => null))->toBe($c);
+});
+
+it('onIssued() registers multiple callbacks', function () {
+    $c = makeCoyote();
+    $c->onIssued(fn($cert) => null);
+    $c->onIssued(fn($cert) => null);
+
+    $ref = new \ReflectionProperty(CoyoteCert::class, 'onIssuedCallbacks');
+    expect($ref->getValue($c))->toHaveCount(2);
+});
+
+it('onRenewed() registers multiple callbacks', function () {
+    $c = makeCoyote();
+    $c->onRenewed(fn($cert) => null);
+    $c->onRenewed(fn($cert) => null);
+
+    $ref = new \ReflectionProperty(CoyoteCert::class, 'onRenewedCallbacks');
+    expect($ref->getValue($c))->toHaveCount(2);
+});
+
+it('fireIssuedCallbacks() invokes onIssued callbacks with the certificate', function () {
+    $cert     = makeCoyoteCert();
+    $coyote   = makeCoyote();
+    $received = null;
+
+    $coyote->onIssued(function ($c) use (&$received) {
+        $received = $c;
+    });
+
+    $method = new \ReflectionMethod(CoyoteCert::class, 'fireIssuedCallbacks');
+    $method->invoke($coyote, $cert, false);
+
+    expect($received)->toBe($cert);
+});
+
+it('fireIssuedCallbacks() does not invoke onRenewed callbacks when isRenewal is false', function () {
+    $cert   = makeCoyoteCert();
+    $coyote = makeCoyote();
+    $called = false;
+
+    $coyote->onRenewed(function () use (&$called) {
+        $called = true;
+    });
+
+    $method = new \ReflectionMethod(CoyoteCert::class, 'fireIssuedCallbacks');
+    $method->invoke($coyote, $cert, false);
+
+    expect($called)->toBeFalse();
+});
+
+it('fireIssuedCallbacks() invokes onRenewed callbacks when isRenewal is true', function () {
+    $cert     = makeCoyoteCert();
+    $coyote   = makeCoyote();
+    $received = null;
+
+    $coyote->onRenewed(function ($c) use (&$received) {
+        $received = $c;
+    });
+
+    $method = new \ReflectionMethod(CoyoteCert::class, 'fireIssuedCallbacks');
+    $method->invoke($coyote, $cert, true);
+
+    expect($received)->toBe($cert);
+});
+
+it('fireIssuedCallbacks() invokes both onIssued and onRenewed when isRenewal is true', function () {
+    $cert   = makeCoyoteCert();
+    $coyote = makeCoyote();
+    $log    = [];
+
+    $coyote->onIssued(function () use (&$log) {
+        $log[] = 'issued';
+    });
+    $coyote->onRenewed(function () use (&$log) {
+        $log[] = 'renewed';
+    });
+
+    $method = new \ReflectionMethod(CoyoteCert::class, 'fireIssuedCallbacks');
+    $method->invoke($coyote, $cert, true);
+
+    expect($log)->toBe(['issued', 'renewed']);
+});
+
+it('fireIssuedCallbacks() invokes callbacks in registration order', function () {
+    $cert   = makeCoyoteCert();
+    $coyote = makeCoyote();
+    $log    = [];
+
+    $coyote->onIssued(function () use (&$log) {
+        $log[] = 1;
+    });
+    $coyote->onIssued(function () use (&$log) {
+        $log[] = 2;
+    });
+    $coyote->onIssued(function () use (&$log) {
+        $log[] = 3;
+    });
+
+    $method = new \ReflectionMethod(CoyoteCert::class, 'fireIssuedCallbacks');
+    $method->invoke($coyote, $cert, false);
+
+    expect($log)->toBe([1, 2, 3]);
+});
+
 // ── extractTokenAndKeyAuth() ──────────────────────────────────────────────────
 
 it('extractTokenAndKeyAuth() returns [name, value] for Dns01ValidationData', function () {