README

A Laravel package for easily generating and renewing SSL certificates using Let's Encrypt. This package is especially useful if you have a Laravel application that manages the SSL certificates of many domains. This package is not recommended if you just need to generate a single SSL certificate for your application.

This package is essentially a Laravel-friendly wrapper around Acme PHP.

Installation

You can install the package via composer:

composer require daanra/laravel-lets-encrypt

If you're having installation problems with conflicting dependencies caused by Guzzle then you might want to run:

composer require daanra/laravel-lets-encrypt guzzlehttp/guzzle:^6.0  -w

Publish the configuration file and the migration:

php artisan vendor:publish --provider="Daanra\LaravelLetsEncrypt\LetsEncryptServiceProvider" --tag="lets-encrypt"

Run the migration:

php artisan migrate

Note:

You somehow have to return a stored challenge whenever it it retrieved from the /.well-known/acme-challenge endpoint. You could do this by configuring NGINX/Apache appropriately or by registering a route:

Route::get('/.well-known/acme-challenge/{token}', function (string $token) {
    return \Illuminate\Support\Facades\Storage::get('public/.well-known/acme-challenge/' . $token);
})

Sometimes the /.well-known/ prefix is disabled by default in the NGINX/Apache config (see #4). Make sure it is forwarded to your Laravel application if you want Laravel to return the challenge.

Usage

Creating a new SSL certificate for a specific domain is easy:

// Puts several jobs on the queue to handle the communication with the lets-encrypt server
[$certificate, $pendingDispatch] = \Daanra\LaravelLetsEncrypt\Facades\LetsEncrypt::create('mydomain.com');

// You could, for example, chain some jobs to enable a new virtual host
// in Apache and send a notification once the website is available
[$certificate, $pendingDispatch] = \Daanra\LaravelLetsEncrypt\Facades\LetsEncrypt::create('mydomain.com', [
    new CreateNewApacheVirtualHost('mydomain.com'), 
    new ReloadApache(),
    new NotifyUserOfNewCertificate(request()->user()),
]);

// You can also do it synchronously:
\Daanra\LaravelLetsEncrypt\Facades\LetsEncrypt::createNow('mydomain.com');

Alternative syntax available from v0.3.0:

LetsEncrypt::certificate('mydomain.com')
            ->chain([
                new SomeJob()
            ])
            ->delay(5)
            ->retryAfter(4)
            ->setTries(4)
            ->setRetryList([1, 5, 10])
            ->create(); // or ->renew()

Where you can specify values for all jobs:

tries (The number of times the job may be attempted)
retryAfter (The number of seconds to wait before retrying the job)
retryList (The list of seconds to wait before retrying the job)
chain (Chain some jobs after the certificate has successfully been obtained)
delay (Set the desired delay for the job)

You could also achieve the same by using an artisan command:

php artisan lets-encrypt:create -d mydomain.com

Certificates are stored in the database. You can query them like so:

// All certificates
\Daanra\LaravelLetsEncrypt\Models\LetsEncryptCertificate::all();
// All expired certificates
\Daanra\LaravelLetsEncrypt\Models\LetsEncryptCertificate::query()->expired()->get();
// All currently valid certificates
\Daanra\LaravelLetsEncrypt\Models\LetsEncryptCertificate::query()->valid()->get();
// All certificates that should be renewed (because they're more than 60 days old)
\Daanra\LaravelLetsEncrypt\Models\LetsEncryptCertificate::query()->requiresRenewal()->get();

// Find certificate by domain
$certificate = LetsEncryptCertificate::where('domain', 'mydomain.com')->first();
// If you no longer need it, you can soft delete
$certificate->delete();
// Or use a hard delete
$certificate->forceDelete();

Subject Alternative Names

It's also possible to specify Subject Alternative Names as below (requires >= 0.5.0):

LetsEncrypt::certificate('mydomain.com')
        ->setSubjectAlternativeNames(['mydomain2.com'])
        ->create();

Failure events

If one of the jobs fails, one of the following events will be dispatched:

Daanra\LaravelLetsEncrypt\Events\CleanUpChallengeFailed
Daanra\LaravelLetsEncrypt\Events\ChallengeAuthorizationFailed
Daanra\LaravelLetsEncrypt\Events\RegisterAccountFailed
Daanra\LaravelLetsEncrypt\Events\RequestAuthorizationFailed
Daanra\LaravelLetsEncrypt\Events\RequestCertificateFailed
Daanra\LaravelLetsEncrypt\Events\StoreCertificateFailed
Daanra\LaravelLetsEncrypt\Events\RenewExpiringCertificatesFailed

Every event implements the Daanra\LaravelLetsEncrypt\Interfaces\LetsEncryptCertificateFailed interface so you can listen for that as well.

Automatically renewing certificates

Certificates are valid for 90 days. Before those 90 days are over, you will want to renew them. To do so, you could add the following to your App\Console\Kernel:

protected function schedule(Schedule $schedule)
{
    $schedule->job(new \Daanra\LaravelLetsEncrypt\Jobs\RenewExpiringCertificates)->daily();
}

This will automatically renew every certificate that is older than 60 days, ensuring that they never expire.

Configuration

By default this package will use Let's Encrypt's staging server to issue certificates. You should set:

LETS_ENCRYPT_API_URL=https://acme-v02.api.letsencrypt.org/directory

in the .env file of your production server.

By default, this package will attempt to validate a certificate using a HTTP-01 challenge. For this reason, a file will be temporarily stored in your application's storage directory under the path app/public/.well-known/acme-challenge/<CHALLENGE_TOKEN>. You can customise this behavior by setting a custom PathGenerator class in your config under path_generator. Note that Let's Encrypt expects the following path:

/.well-known/acme-challenge/<CHALLENGE_TOKEN>

to return the contents of the file located at $pathGenerator->getPath($token).

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email opensource@daanraatjes.dev instead of using the issue tracker. If you have a question, please open an issue instead of sending an email.

Credits

License

The MIT License (MIT). Please see License File for more information.

daanra / laravel-lets-encrypt

Maintainers

Details