README

A PHP toolkit to create, inspect, renew, revoke, and delete Let’s Encrypt certificates by driving the Certbot CLI. It provides typed option objects, convenient helpers, and traits you can mix into your own services.

Built on top of the Oihana PHP Commands library.

✨ Why this library?

Strongly-typed options for Certbot subcommands (certonly, certificates, renew, revoke, delete)
Simple trait-based API you can add to your existing classes
Helpers to parse certbot certificates output and build domains lists safely
Sensible defaults, optional verbose and dry-run modes, and automatic sudo execution

Requirements

PHP 8.4+
A Unix-like environment where certbot is installed and available in PATH
Sufficient privileges to run Certbot (commands are executed with sudo)

📦 Installation

Install via Composer:

composer require oihana/php-certbot

🚀 Quick start

Mix the provided traits into your own service. The CommandTrait brings process execution utilities; CertbotTrait bundles all Certbot subcommand traits at once.

<?php

use oihana\commands\traits\CommandTrait;
use oihana\certbot\traits\CertbotTrait;

final class CertbotService
{
    use CommandTrait;
    use CertbotTrait;

    public function __construct()
    {
        // Optional: set sensible defaults for future calls
        $this->initializeCertbotOptions([
            'certbot' => [
                'certonly' => [
                    'email'          => 'admin@example.com',
                    'agreeTos'       => true,
                    'nonInteractive' => true,
                ],
            ],
        ]);
    }
}

Use it in your application:

$svc = new CertbotService();

// 1) Obtain a certificate using webroot
$svc->certbotCertOnly
([
    'webrootPath' => '/var/www/example',
    'domains'     => ['example.com', 'www.example.com'],
    'rsaKeySize'  => 4096,
], verbose: true);

// 2) List all managed certificates
$certs = $svc->certbotCertificates();

// 3) Check if a certificate exists and is valid
$exists = $svc->certbotCertificateExists('example.com');
$isValid = $svc->certbotCertificateIsValid('example.com');

// 4) Renew certificates (optionally target a single cert-name)
$svc->certbotRenew('example.com');

// 5) Revoke or delete
$svc->certbotRevoke('example.com', deleteAfter: true);
$svc->certbotDelete('example.com');

ℹ️ API overview

All methods below are available when you include oihana\certbot\traits\CertbotTrait (or pick the specific sub-traits you need).

Certificates inspection
- certbotCertificates(array|CertbotCertificatesOptions $options = null, bool $verbose = false, bool $silent = false, bool $dryRun = false): array<CertbotCertificate>
- certbotCertificate(null|string|array $needs, array|CertbotCertificatesOptions $options = null, ...): ?CertbotCertificate
- certbotCertificateExists(null|string|array $needs, ...): bool
- certbotCertificateIsValid(null|string|array|CertbotCertificate $needs, ...): bool
Obtain certificate
- initializeCertbotCertOnlyOptions(array $init): static
- certbotCertOnly(array|CertbotCertOnlyOptions $options = null, bool $verbose = false, bool $silent = false, bool $dryRun = false): int
Renew
- initializeCertbotRenewOptions(array $init): static
- certbotRenew(null|string|array $domains = null, array|CertbotRenewOptions $options = null, bool $verbose = false, bool $silent = false, bool $assertable = false, bool $dryRun = false): int
Revoke
- initializeCertbotRevokeOptions(array $init): static
- certbotRevoke(null|string|array $domains = null, ?bool $deleteAfter = null, array|CertbotRevokeOptions $options = null, bool $verbose = false, bool $silent = false, bool $dryRun = false): int
Delete
- initializeCertbotDeleteOptions(array $init): static
- certbotDelete(null|string|array $domains = null, array|CertbotDeleteOptions $options = null, bool $verbose = false, bool $silent = false, bool $dryRun = false): int

Options

Each subcommand has a dedicated options class (CertbotCertOnlyOptions, CertbotRenewOptions, CertbotRevokeOptions, CertbotDeleteOptions, CertbotCertificatesOptions) extending CertbotOptions. You can either:

Pass an associative array (flat or nested under ['certbot' => ['<subcommand>' => [...]] ]).
Instantiate the options object directly and pass it.

Common options include:

domains (array|string): domains to include in the certificate
certName (string): the Certbot internal name
dryRun (bool): test mode for certonly/renew
nonInteractive, agreeTos, email, verbose, etc.

Plugins and webroot:

Webroot support via CertbotWebrootOptions (webrootPath, webrootMap)
Additional plugin traits for manual, nginx, and webroot

Return types

Commands return process exit codes (int), where 0 indicates success.
Inspection commands return arrays of oihana\certbot\entities\CertbotCertificate with parsed fields: name, domains, expires, validDays, paths, etc.

Helpers

oihana\certbot\helpers\getCertbotDomains(string $domain, ?string $subdomain, bool $throw = true): ?array – builds a safe domain list (e.g. example.com + www.example.com).
oihana\certbot\helpers\parseCertbotCertificates(string $source, ?string $timezone = 'Europe/Paris', ?string $dateFormat = 'Y-m-d\\TH:i:s'): array – parses the output of certbot certificates into CertbotCertificate instances.

CLI behavior

Commands are executed with sudo.
Use the $verbose, $silent, and $dryRun flags on methods to adjust behavior.
Ensure certbot is installed and your environment has the necessary permissions.

✅ Running Unit Tests

composer test

🤝 Contributing

Bug reports and PRs are welcome. Please try to include tests when fixing a bug or adding a feature. Make sure to run the test suite before submitting.

🧾 License

This project is licensed under the Mozilla Public License 2.0 (MPL‑2.0).

👤 About the author

Author : Marc ALCARAZ (aka eKameleon)
Mail : marc@ooop.fr
Website : http://www.ooop.fr

🔗 Related Packages

oihana/php-core – core helpers and utilities used by this library: https://github.com/BcommeBois/oihana-php-core
oihana/php-exceptions – a curated set of reusable custom exception classes for PHP: https://github.com/BcommeBois/oihana-php-exceptions
oihana/php-reflect – reflection and hydration utilities: https://github.com/BcommeBois/oihana-php-reflect
oihana/php-files – filesystem helpers: https://github.com/BcommeBois/oihana-php-files
oihana/php-system – common helpers of the Oihana PHP framework: https://github.com/BcommeBois/oihana-php-system
oihana/php-schema – object‑oriented implementation of the Schema.org vocabulary: https://github.com/BcommeBois/oihana-php-schema
oihana/php-standards – constants and helpers based on major international standards: https://github.com/BcommeBois/oihana-php-standards
oihana/php-commands – scriptable command-line tooling for servers and web applications: https://github.com/BcommeBois/oihana-php-commands

oihana / php-certbot

Maintainers

Details