PHPackages                             tomcan/acmeclient - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tomcan/acmeclient

ActivePackage[Utility & Helpers](/categories/utility)

tomcan/acmeclient
=================

PHP ACME client library

v2.2.0(1y ago)11.1k↓33.3%1Apache-2.0PHPPHP ^8.1

Since May 6Pushed 1y ago1 watchersCompare

[ Source](https://github.com/TomCan/AcmeClient)[ Packagist](https://packagist.org/packages/tomcan/acmeclient)[ Docs](https://github.com/tomcan/acmeclient)[ RSS](/packages/tomcan-acmeclient/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (4)Versions (4)Used By (0)

AcmeClient library
==================

[](#acmeclient-library)

AcmeClient library is PHP library implementing the Automatic Certificate Management Environment (ACME) protocol, used for requesting certificates from services like Let's Encrypt.

The goal of the project is to create a flexible library that allows you to incorporate certificate registration through ACME in your own application (e.g. SaaS service with customer domains), without the need of an external tool or client.

The library uses interfaces for both what it requires as what it returns, so you have the freedom to implement these interfaces into the already existing classes in your own product. If you don't require that much of an integration, you can also use the built-in classes that can provide the required functionality to get the job done.

Note: the actual validation is not part of the scope of this library. It will tell you what http or DNS challenge to provide, but it's up to you to make sure the given values end up where they need to end up.

(in)completeness
================

[](#incompleteness)

This does not aim to be a full implementation of the RFC, but mainly focuses on the flow of obtaining certificate from ACME compatible services (e.g. Let's Encrypt).

Implemented functionality
-------------------------

[](#implemented-functionality)

- Account creation
- Order creation
- Order authorization
    - Get authorizations
    - Get challenges
- Order validation
- Order finalization (get actual certificate)

Getting started
===============

[](#getting-started)

To get started, you'll need to add the library to your composer-based project.

```
composer require tomcan/acmeclient
```

The client requires a HTTP Client that implements the Symfony\\HttpClientInterface (eg. the Symfony HttpClient), as well as the directory URL of the ACME server (defaults to Let's Encrypt), and optionally a logger class implementing the Psr\\LoggerInterface interface.

```
$httpClient = \Symfony\Component\HttpClient\HttpClient::create();
$acmeClient = new \TomCan\AcmeClient\AcmeClient($httpClient, 'https://acme-staging-v02.api.letsencrypt.org/directory');
```

Next, you will need an account on the ACME server. This requires an e-mail address and a RSA key that will be used for signing the requests. If you're using the built-in Account class, it will automatically generate a new key if none is provided. You then need to validate the account with the directory. If it's a new account, it will automatically create the account and return it.

```
// Create new account object
/** @var AccountInterface $account */
$account = new Account('your@email-address.here', null, null);
$acmeClient->getAccount($account);
```

You should save/persist the account information for later use. This could be a simple as writing the info to a json file, or persisting it to database through an ORM. But that's totally up to you to implement that.

```
// Example for your convenience only.

// save Account after having called $acmeClient->getAccount($account) to create the account
$acmeClient->getAccount($account);
file_put_contents('/path/to/account.json', json_encode(['email' => $account->getEmail(), 'url' => $account->getEmail(), 'key' => $account->getKey()]));

// re-loading the account on later requests
$accountData = json_decode(file_get_contents('/path/to/account.json));
$account = new Account($accountData->email, $accountData->url, $accountData->key);
$acmeClient->getAccount($account);
```

Once you have the account, you can create an order, passing an array of domainnames as identifiers. You can then need to authorize the order to obtain the list of authorizations and challenges to complete. You probably want to do some pre-flight checks of your own before authorizing the order, as every authorization needs to be successful in order to get the certificate.

```
/** @var OrderInterface */
$order = $acmeClient->createOrder(['yourdomain.com', 'www.yourdomain.com']);
/** @var AuthorizationInterface[] */
$authorizations = $acmeClient->authorize($order);
```

The returned AuthorizationInterface array contains an autorization object for every requested domain. For each authorization at least one challenge needs to be validated. Although multiple challenges are returned, you only need to validate one challenge for each authorization. This can be a HTTP challenge or a DNS challenge. You need to pass both the autorizations as the choosen challenge as arrays, where the index of the authorizations array corresponds to the index of the challenge.

For HTTP challenges, a request will be made to http://{hostname}/.well-known/acme-challenge/{token}. You can obtain the value of token using the getToken() method on the ChallengeInterface object, and the required content using the getValue() method.

For DNS challenges, a DNS TXT record has to be created as \_acme-challenge.{hostname}. The value of the DNS record can be obtained using the getValue method on the ChallengeInterface object.

```
// example of using the http-01 HTTP challenge
$challenges = [];
foreach ($authorizations as $authorization) {
    $a[] = $authorization;
    foreach ($authorization->getChallenges() as $challenge) {
        if ($challenge->getType() == 'http-01') {
            $challenges[] = $challenge;
            // e.g. write file to documentroot of webserver
            file_put_contents('/path/to/documentroot/.well-known/acme-challenge/'.$challenge->getToken(), $challenge->getValue());
        }
    }
}
$result = $acmeClient->validate($authorizations, $challenges);
```

The validate method will return true when all authorizations have been completed, or false if failed. The authorizations and challenges passed to the method will be updated to reflect the status, so you can use them to determine which ones actually succeeded of failed.

If all authorizations are completed, you can finalize the order and obtain the certificate. The client will generate a new private key and csr and pass that to the ACME server. The private key, csr and complete certificate chain will be returned through the CertificateInterface object.

```
/** @var CertificateInterface
$cert = $acmeClient->finalize($order);
```

References
==========

[](#references)

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance31

Infrequent updates — may be unmaintained

Popularity22

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~197 days

Total

3

Last Release

713d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a525acc6df0983b6cc74121062bc2ec4cfcb163a2252ba1fb27d5e04ff67243d?d=identicon)[TomCan](/maintainers/TomCan)

---

Top Contributors

[![TomCan](https://avatars.githubusercontent.com/u/2892620?v=4)](https://github.com/TomCan "TomCan (41 commits)")

---

Tags

acme-v2letsencryptphpletsencryptACMEacmev2LEtomcanrfc8555

###  Code Quality

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tomcan-acmeclient/health.svg)

```
[![Health](https://phpackages.com/badges/tomcan-acmeclient/health.svg)](https://phpackages.com/packages/tomcan-acmeclient)
```

###  Alternatives

[afosto/yaac

Yet Another ACME client: a decoupled LetsEncrypt client

245500.4k1](/packages/afosto-yaac)[acmephp/acmephp

Let's Encrypt client written in PHP

649155.1k](/packages/acmephp-acmephp)[kelunik/acme

ACME library written in PHP.

121603.9k3](/packages/kelunik-acme)[sensiolabs/minify-bundle

Assets Minifier (CSS, JS) for Symfony & Minify integration in Asset Mapper

5694.9k1](/packages/sensiolabs-minify-bundle)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)