Oh Dear is the all-in-one monitoring tool for your entire website. We monitor uptime, SSL certificates, broken links, scheduled tasks and more. You'll get a notifications for us when something's wrong. All that paired with a developer friendly API and kick-ass documentation. O, and you'll also be able to create a public status page under a minute. Start monitoring using our free trial now.

Selling digital products using Laravel part 5: Using Satis to install private packages

Original – by Freek Van der Herten – 7 minute read

Some of our products, like Mailcoach and Media Library Pro, are PHP packages for which people can buy a time-limited license. Of course, we want customers to be able to install our paid packages using Composer. Our paid packages are not registered on Packagist, because Packagist is meant to be used for free packages, and there's no way to handle licenses. Let's take a look at how we can solve this using Satis.

Satis is an open-source Composer repository generator. You can think of it as a very lightweight, self-hosted version of Packagist that you can configure any way you want. We installed satis at satis.spatie.be

For our paid packages, we instruct users to put this in their composer.json file.

"repositories": [
        "type": "composer",
        "url": "https://satis.spatie.be"

This will make Composer look for packages - that it can't find on packagist.org - on satis.spatie.be. As a human, you can also check what's available on our Satis installation by visiting https://satis.spatie.be.

Satis itself is dead simple to configure. All it needs is a satis.json file that contains the repositories that should be made available through it. Here is the content of satis.json

  "name": "spatie/satis.spatie.be",
  "homepage": "https://satis.spatie.be",
  "output-dir": "public",
  "repositories": [
    { "type": "vcs", "url": "https://github.com/spatie/mailcoach" },
    { "type": "vcs", "url": "https://github.com/spatie/mailcoach-ui" },
    { "type": "vcs", "url": "https://github.com/spatie/laravel-mailcoach" },
    { "type": "vcs", "url": "https://github.com/spatie/laravel-mailcoach-mailgun-feedback" },
    { "type": "vcs", "url": "https://github.com/spatie/laravel-mailcoach-ses-feedback" },
    { "type": "vcs", "url": "https://github.com/spatie/laravel-mailcoach-sendgrid-feedback" },
    { "type": "vcs", "url": "https://github.com/spatie/laravel-mailcoach-postmark-feedback" },
    { "type": "vcs", "url": "https://github.com/spatie/laravel-mailcoach-unlayer" },
    { "type": "vcs", "url": "https://github.com/spatie/laravel-mailcoach-monaco" },
    { "type": "vcs", "url": "https://github.com/spatie/laravel-medialibrary-pro" }
  "archive": {
    "directory": "dist",
    "skip-dev": false
  "require-all": true

Giving Satis access to private repositories

If you'd only want to use public repositories, then this configuration would be enough. But, in our case, those repositories are private. We need to give Satis the credentials to be able to access those private repos. Under the hood, Satis uses Composer to fetch the packages. You can give Composer the right credentials by creating an auth.json file and put that in Composer's home directory.

On GitHub, you should create a personal access token on a user that has access to the private repos. That token should be put in auth.json. On our server, this is the content of ~/.composer/auth.json

    "github-oauth": {
        "github.com": "put-your-github-token-here"

With this in place, Satis can access the private GitHub repositories. In the satis.json above, setting the archive.directory option to dist will make Satis copy all released versions of a repository to the public/dist directory. For all releases of a repo, a zip file will be created.

Authorizing package downloads

If we left it like this, everyone would be able to download the zips in the dist directory. We don't want that. Only people with a valid license for a particular product should be able to download the zips that contain that product.

We use Nginx to serve Satis. In the Nginx config for we've put these lines in the server block.

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name satis.spatie.be;
    server_tokens off;
    root /home/forge/satis.spatie.be/public;
    # Some other stuff
    # ...
    location /dist {
        auth_request /auth; 
        try_files $uri $uri/ /index.php?$query_string;
    location = /auth {
        proxy_method      POST;
        proxy_set_header  Accept "application/json";
        proxy_set_header  X-Original-URI $request_uri;
        proxy_pass        https://spatie.be/api/satis/authenticate;

With this configuration, Satis will not serve up the zip files in the dist directory anymore for anyone. When a request comes in for a file in /dist, Nginx will call the internal /auth endpoint first. This internal endpoint will pass on the original request to https://spatie.be/api/satis/. If that endpoint on spatie.be returns a 2XX response, the request to download the zip is allowed; otherwise, it is denied. If you want to know more about this kind of authentication, head over to the relevant Nginx docs.

Handling license requests in Laravel

Let's take a look at the route that handles the request to /api/satis/.

Route::post('satis/authenticate', SatisAuthenticationController::class)->middleware('auth:license-api');

We're using the license-api guard to authenticate the request. In the auth.php config file, we've set things up so that the license-api guard uses the license-key driver.

'guards' => [
     // ...

    'license-api' => [
        'driver' => 'license-key',

The license-key driver is defined in AuthServiceProvider.

class AuthServiceProvider extends ServiceProvider
    public function boot()
        Auth::viaRequest('license-key', function (Request $request) {
            $license = License::query()
                ->where('key', $request->getPassword())

            if (! $license) {
                abort(401, 'License key invalid');

            if ($license->isExpired()) {
                abort(401, 'This license is expired');


            return $license;

The above license-key driver will try to find a license whose key matches the password used for the request. You might find it strange that we use the password there. Well, when Composer tries to authenticate, it will ask the user for a password. We instruct our users to put their license key there.

When no valid license is found, we abort the request and send an unauthorized response. If a valid license is found, the auth middleware will not stop the request, and eventually, the SatisAuthenticationController is called. Here is the full code of that controller. I've put in some comments to explain what is going on.

namespace App\Http\Api;

use App\Models\License;
use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Http\Request;
use Illuminate\Routing\Controller;

class SatisAuthenticationController extends Controller
    public function __invoke(Authenticatable $license, Request $request)
        /** @var $license \App\Models\License */
        if (! $license instanceof License) {

         * We have a master key that we use for our projects that grants
         * us access to anything available on Satis.
        if ($license->isMasterKey()) {
            return response('valid');

         * Find the package that is being requested.
        $package = $this->getRequestedPackage($request);

         * Composer can only store one authentication method per repository.
         * This means the user is probably going to try to authenticate with a license
         * key for the wrong package. We have to check the user's other licenses
         * as well.
        $hasAccess = License::query()
            ->where('user_id', $license->user_id)
                fn (License $license) => $license->purchasable->includesPackageAccess($package)

        abort_unless($hasAccess, 401);

        return response('valid');

    protected function getRequestedPackage(Request $request): string
        $originalUrl = $request->header('X-Original-URI', '');

        preg_match('#^/dist/(?<package>spatie/[^/]*)/#', $originalUrl, $matches);

        if (! key_exists('package', $matches)) {
            abort(401, 'Missing X-Original-URI header');

        return $matches['package'];

If this controller determines that the user can access the requested package, a response with code 200 is returned. This will signal to Nginx that the requested zip in the dist directory may be downloaded. When a license has expired, SatisAuthenticationController will not return a 200 response anymore, and the user loses access to the package.

And that is how we use Satis to handle private packages that have a time-limited license.

This series is continued in part 6: Building a video section using Vimeo.

Stay up to date with all things Laravel, PHP, and JavaScript.

You can follow me on these platforms:

On all these platforms, regularly share programming tips, and what I myself have learned in ongoing projects.

Every month I send out a newsletter containing lots of interesting stuff for the modern PHP developer.

Expect quick tips & tricks, interesting tutorials, opinions and packages. Because I work with Laravel every day there is an emphasis on that framework.

Rest assured that I will only use your email address to send you the newsletter and will not use it for any other purposes.


Kevin Dees avatar

If you are using SSL on your auth proxy you might need to include proxy_ssl_server_name on; within the auth location.

location = /auth {
        proxy_method      POST;
        proxy_set_header  Accept "application/json";
        proxy_ssl_server_name on; # added
        proxy_set_header  X-Original-URI $request_uri;
        proxy_pass        https://auth-satis.example.com/;
Randall Wilk avatar

After hours of debugging, this is what I needed. Thank you for posting that.

Comments powered by Laravel Comments
Want to join the conversation? Log in or create an account to post a comment.