Resolve merge conflict; improve chain-selection coverage

bashgeek · bashgeek · commit bc2b9b223fea · 2026-04-17T13:44:23.000+08:00
diff --git a/README.md b/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)
@@ -538,6 +539,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.
@@ -661,10 +703,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:
@@ -768,7 +808,6 @@ $coyote->revoke($cert, RevocationReason::AffiliationChanged);
 $coyote->revoke($cert, RevocationReason::Superseded);
 $coyote->revoke($cert, RevocationReason::CessationOfOperation);
 $coyote->revoke($cert, RevocationReason::CertificateHold);
-$coyote->revoke($cert, RevocationReason::RemoveFromCrl);
 $coyote->revoke($cert, RevocationReason::PrivilegeWithdrawn);
 $coyote->revoke($cert, RevocationReason::AaCompromise);
 ```
@@ -921,6 +960,8 @@ CoyoteCert::with(AcmeProviderInterface $provider)  // factory — select the CA
 | `->preferredChain(string)` | fluent | `''` | Preferred chain issuer CN/O (RFC 8555 §7.4.2); falls back to default chain if no match |
 | `->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` |
diff --git a/src/CoyoteCert.php b/src/CoyoteCert.php
@@ -58,6 +58,10 @@ class CoyoteCert
     private bool                       $localTest        = true;
     private bool                       $skipCaaCheck     = false;
     private string                     $preferredChain   = '';
+    /** @var callable[] */
+    private array $onIssuedCallbacks = [];
+    /** @var callable[] */
+    private array $onRenewedCallbacks = [];
 
     private function __construct(private readonly AcmeProviderInterface $provider) {}
 
@@ -198,6 +202,31 @@ public function preferredChain(string $issuer): 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.
@@ -295,7 +324,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 ───────────────────────────────────────────────
@@ -377,6 +409,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.
      */
diff --git a/src/Enums/RevocationReason.php b/src/Enums/RevocationReason.php
@@ -11,7 +11,6 @@ enum RevocationReason: int
     case Superseded           = 4;
     case CessationOfOperation = 5;
     case CertificateHold      = 6;
-    case RemoveFromCrl        = 8;
     case PrivilegeWithdrawn   = 9;
     case AaCompromise         = 10;
 }
diff --git a/tests/Unit/CoyoteCertTest.php b/tests/Unit/CoyoteCertTest.php
@@ -79,6 +79,11 @@ public function cleanup(string $d, string $tok): void {}
     expect($c->skipCaaCheck())->toBe($c);
 });
 
+it('preferredChain() returns self (fluent)', function () {
+    $c = makeCoyote();
+    expect($c->preferredChain('ISRG Root X1'))->toBe($c);
+});
+
 it('profile() returns self (fluent)', function () {
     $c = makeCoyote();
     expect($c->profile('shortlived'))->toBe($c);
@@ -393,6 +398,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 () {
diff --git a/tests/Unit/Endpoints/EndpointsTest.php b/tests/Unit/Endpoints/EndpointsTest.php
@@ -1480,6 +1480,61 @@ function certOrderData(): OrderData
     expect($parsed['subject']['CN'])->toBe('Default Root CA');
 });
 
+it('Certificate::getBundle() skips alternate chains that return non-200 and falls back to primary', function () {
+    $storage       = withKeyStorage();
+    $primaryBundle = makeCertBundle('Default Root CA');
+
+    $mock = closureMock(
+        getHandler: fn($url) => new Response([], $url, 200, directoryBody()),
+        postHandler: function ($url) use ($primaryBundle) {
+            if (str_contains($url, '/alt')) {
+                return new Response([], $url, 503, 'Service Unavailable');
+            }
+
+            return new Response(
+                ['link' => '<https://acme.example/cert/1/alt>;rel="alternate"'],
+                $url,
+                200,
+                $primaryBundle,
+            );
+        },
+    );
+
+    $bundle = makeEndpointApi($mock, $storage)->certificate()->getBundle(certOrderData(), 'ISRG Root X1');
+
+    preg_match_all('~(-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----)~i', $bundle->caBundle, $m);
+    $parsed = openssl_x509_parse($m[1][0]);
+    expect($parsed['subject']['CN'])->toBe('Default Root CA');
+});
+
+it('Certificate::getBundle() skips alternate chains whose caBundle is empty', function () {
+    $storage        = withKeyStorage();
+    $primaryBundle  = makeCertBundle('Default Root CA');
+    $leafOnlyBundle = "-----BEGIN CERTIFICATE-----\nMIIBtest==\n-----END CERTIFICATE-----\n";
+
+    $mock = closureMock(
+        getHandler: fn($url) => new Response([], $url, 200, directoryBody()),
+        postHandler: function ($url) use ($primaryBundle, $leafOnlyBundle) {
+            if (str_contains($url, '/alt')) {
+                return new Response([], $url, 200, $leafOnlyBundle);
+            }
+
+            return new Response(
+                ['link' => '<https://acme.example/cert/1/alt>;rel="alternate"'],
+                $url,
+                200,
+                $primaryBundle,
+            );
+        },
+    );
+
+    $bundle = makeEndpointApi($mock, $storage)->certificate()->getBundle(certOrderData(), 'ISRG Root X1');
+
+    preg_match_all('~(-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----)~i', $bundle->caBundle, $m);
+    $parsed = openssl_x509_parse($m[1][0]);
+    expect($parsed['subject']['CN'])->toBe('Default Root CA');
+});
+
 it('Certificate::getBundle() handles multiple Link headers (comma-separated) and selects matching chain', function () {
     $storage          = withKeyStorage();
     $primaryBundle    = makeCertBundle('Default Root CA');

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,6 @@ enum RevocationReason: int`
`11`	`11`	`case Superseded = 4;`
`12`	`12`	`case CessationOfOperation = 5;`
`13`	`13`	`case CertificateHold = 6;`
`14`		`- case RemoveFromCrl = 8;`
`15`	`14`	`case PrivilegeWithdrawn = 9;`
`16`	`15`	`case AaCompromise = 10;`
`17`	`16`	`}`