Clavem

Check for updates and install a release from a self-hosted PHP app

Send GET /v1/releases/:productId/latest with the X-License-Key header and platform=php, compare the version with version_compare(), and request the download only when the owner clicks Update, because the signed link lasts one hour. Unpack next to the app and swap folders so a bad update can be rolled back.

What the endpoint returns

The endpoint is public, so an admin screen can call it. A license key adds the download links. Send the key in the X-License-Key header, not the legacy query parameter, to keep it out of server logs.

Request Response
Valid license for this product version, notes, published_at and files, each file with a signed url that lasts one hour
No key, or a key that is unknown, expired, disabled or for another product version and published_at only. Not an error
Nothing published yet 404 with "code": "not_found"

The demo product has no published release, so the live API answers its latest-release request like this, captured with the demo key:

{ "error": { "code": "not_found", "message": "This product has no published release yet." } }

Give the ZIP a platform label in the dashboard. A label is 1 to 40 characters of lowercase letters, digits, dots, dashes and underscores, and Clavem does not fix the list, so use php. A file with no label is offered to every platform, and a platform=php request returns the php files plus those.

Check for a newer version

This is ClavemUpdater for PHP 7.4 or later with the cURL and zip extensions.

<?php
final class ClavemUpdater
{
    private const BASE = 'https://clavem.io';

    private $productId;
    private $installed;

    public function __construct(int $productId, string $installedVersion)
    {
        $this->productId = $productId;
        $this->installed = $installedVersion;
    }

    /**
     * The newest release when it is newer than the installed one, otherwise null.
     * @return array{version:string,notes:?string,downloadable:bool}|null
     */
    public function newer(string $licenseKey): ?array
    {
        $ch = curl_init(self::BASE . '/v1/releases/' . $this->productId . '/latest?platform=php');
        curl_setopt_array($ch, [
            CURLOPT_HTTPHEADER => ['X-License-Key: ' . $licenseKey, 'User-Agent: Inkwell/3.2'],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => 3,
            CURLOPT_TIMEOUT => 8,
        ]);
        $raw = curl_exec($ch);
        if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 200 || !is_string($raw)) {
            return null; // nothing published yet (404), rate limited (429), or no answer
        }
        $latest = json_decode($raw, true);
        if (!is_array($latest) || !isset($latest['version']) || version_compare($latest['version'], $this->installed, '<=')) {
            return null;
        }
        $downloadable = false;
        foreach ($latest['files'] ?? [] as $file) {
            $downloadable = $downloadable || isset($file['url']);
        }
        return ['version' => $latest['version'], 'notes' => $latest['notes'] ?? null, 'downloadable' => $downloadable];
    }
}

When downloadable is false, show the version and a renewal link and no button.

Download, unpack, swap

Call install() when the owner clicks Update, not when the check ran. An update screen can sit open for longer than the one hour the link lasts. It asks for a fresh link, streams the ZIP to disk, unpacks it beside the app, then renames the folders.

public function install(string $licenseKey, string $appDir): string
{
    $ch = curl_init(self::BASE . '/v1/releases/' . $this->productId . '/latest?platform=php');
    curl_setopt_array($ch, [CURLOPT_HTTPHEADER => ['X-License-Key: ' . $licenseKey], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 8]);
    $latest = json_decode((string) curl_exec($ch), true);
    $url = $latest['files'][0]['url'] ?? null;
    if ($url === null) {
        throw new RuntimeException('This license cannot download updates.');
    }

    $zipFile = tempnam(sys_get_temp_dir(), 'inkwell');
    $out = fopen($zipFile, 'wb');
    $dl = curl_init($url);
    curl_setopt_array($dl, [CURLOPT_FILE => $out, CURLOPT_FOLLOWLOCATION => true, CURLOPT_TIMEOUT => 300, CURLOPT_FAILONERROR => true]);
    $ok = curl_exec($dl);
    fclose($out);
    if (!$ok) {
        @unlink($zipFile);
        throw new RuntimeException('Download failed: ' . curl_error($dl));
    }

    $staging = $appDir . '.new'; // same filesystem as $appDir, so rename() is atomic
    self::unzipSafely($zipFile, $staging);
    unlink($zipFile);

    $previous = $appDir . '.previous';
    rename($appDir, $previous);
    rename($staging, $appDir);
    if (function_exists('opcache_reset')) {
        opcache_reset(); // otherwise PHP can keep serving the old files from memory
    }
    return $previous;
}

private static function unzipSafely(string $zipFile, string $target): void
{
    $zip = new ZipArchive();
    if ($zip->open($zipFile) !== true) {
        throw new RuntimeException('The download is not a ZIP file.');
    }
    for ($i = 0; $i < $zip->numFiles; $i++) {
        $name = (string) $zip->getNameIndex($i);
        if (substr($name, 0, 1) === '/' || strpos($name, '..') !== false || strpos($name, "\0") !== false) {
            $zip->close();
            throw new RuntimeException('Refusing to unpack ' . $name);
        }
    }
    mkdir($target, 0755, true);
    $zip->extractTo($target);
    $zip->close();
}

I ran both methods against a local mock of the endpoint on PHP 8.3. newer() returned the version with downloadable: false for a missing key and true for a good one, and install() swapped a 3.2.0 folder for 3.2.1 and kept 3.2.0 as .previous. A ZIP with an entry named ../evil.php was refused before anything was written. That run did not use the live API or a real web server.

Version comparison

version_compare() compares dotted numbers segment by segment, which a string comparison does not. Results from PHP 8.3:

Call Result Meaning
version_compare('3.10.0', '3.9.0') 1 3.10.0 is newer, although '3.10.0' < '3.9.0' as strings
version_compare('3.2.0-beta.1', '3.2.0') -1 a beta is older than the release
version_compare('4.0.0-rc.1', '3.9.9') 1 a release candidate is newer than the last 3.x
version_compare('3.2.0', '3.2.0-rc.1') 1 the release is newer than its candidate

Latest means the most recently published release, not the highest version. If you publish a 3.9.5 backport after 4.0.0, the endpoint returns 3.9.5. An install on 4.0.0 gets no offer, which is right, and an install on 3.9.0 is offered 3.9.5 and never sees 4.0.0.

PHP traps

  • Permissions. rename() of the app folder needs write access to its parent. On many shared hosts the web user cannot write there, so offer a manual download link instead.
  • OPcache. With timestamp validation off, PHP serves the old code until opcache_reset() runs, as the PHP manual describes.
  • Keep data out. Put uploads, configuration and the license file outside the folder you swap.
  • Short window. Put the site in maintenance mode for the two renames, and run migrations after the swap.
  • Integrity. Clavem documents no checksum field for files. If you want one, put a SHA-256 in the release notes yourself and compare it before unpacking.
  • Check cost. The releases endpoint allows 120 requests per minute per IP address, counted apart from validation. Cache the answer of newer() for a few hours so each admin page view does not call it.

Doing this with Clavem

Upload the ZIP once on the product page and publish the release. The buyer’s order page and your update check both serve it, and downloads are not metered. Releases and downloads describes the limits.

Questions

Does Clavem install the update on the buyer's server?

No. Clavem stores your release files and returns a version, release notes and a signed download link. Your PHP code downloads the ZIP and installs it.

Why does the check show a new version but no Update button?

Without a license that is valid for the product, the endpoint returns only the version and the publish date. No files, notes or links come back, so the code reports downloadable as false.

Sources

  1. PHP manual, version_compare (checked November 2026)
  2. PHP manual, opcache_reset (checked November 2026)