What counts as a device in a PHP product
Clavem counts activations. It does not know whether one is a laptop or a web site, so you decide what to send as fingerprint. Activating again with a fingerprint that is already active on the license returns the same seat, with its name updated, instead of using another. That makes the choice of fingerprint the whole policy.
| Fingerprint source | Staging copy | Domain change | New server, site copied over | Container redeploy |
|---|---|---|---|---|
| Host name | new seat | new seat | same seat if the host name stays | same seat |
| Random id in a file | same seat if the file comes along | same seat | same seat if the file comes along | new seat every deploy unless the folder is a volume |
| Random id in the database | same seat if the dump is copied | same seat | same seat if the database comes along | same seat |
Id the owner sets in .env |
same seat if the same value is used | same seat | same seat if the same value is used | same seat |
The code below uses the file because it works on every host. Use the database or an environment value if your product ships in containers or on a platform with a read-only or disposable filesystem. A file that disappears on each deploy gets a new random id, so every deploy activates again and burns a seat until the limit is reached.
Activate and deactivate
Add these methods to the ClavemLicense class from the validation guide. They use its post() and save().
/** Once per install, when the owner enters the key. Returns null on success, or a message to show. */
public function activate(string $licenseKey, string $siteUrl): ?string
{
$key = trim($licenseKey);
[, $reply] = $this->post('activate', [
'license_key' => $key,
'instance_name' => strtolower((string) parse_url($siteUrl, PHP_URL_HOST)),
'fingerprint' => hash('sha256', 'inkwell:' . $this->installId()),
]);
if (empty($reply['activated'])) {
$l = $reply['license_key'] ?? [];
$full = ($l['status'] ?? '') === 'active' && isset($l['activation_limit'])
&& ($l['activation_usage'] ?? 0) >= $l['activation_limit'];
if ($full) {
return sprintf(
'This key is already active on %d of %d sites. Remove one at https://clavem.io/licenses/manage and try again.',
$l['activation_usage'],
$l['activation_limit']
);
}
return $reply['error'] ?? 'Could not reach the license server. Try again in a minute.';
}
$this->save([
'key' => $key,
'instance_id' => $reply['instance']['id'],
'token' => $reply['token'],
'next_check' => time() + self::CHECK_EVERY,
]);
return null;
}
/** True when the seat is free on the server. On false the key is still removed here. */
public function deactivate(): bool
{
$saved = $this->load();
if ($saved === null) {
return true;
}
[$status] = $this->post('deactivate', ['license_key' => $saved['key'], 'instance_id' => $saved['instance_id']]);
@unlink($this->file);
return $status === 200 || $status === 404; // 404: the seat was already gone
}
/** A random id made once and kept next to the license file. It survives a domain change. */
private function installId(): string
{
$file = $this->file . '.id';
$id = @file_get_contents($file);
if ($id === false || strlen($id) !== 32) {
$id = bin2hex(random_bytes(16));
file_put_contents($file, $id, LOCK_EX);
chmod($file, 0600);
}
return $id;
}
Pass the site URL from your own configuration, such as APP_URL. $_SERVER['HTTP_HOST'] is copied from the request header, which a proxy or a visitor can change, and it does not exist when the code runs from cron or a console command. instance_name may be up to 120 characters and fingerprint up to 200. A SHA-256 hex digest is 64.
The activation limit
The default limit for a product is 3 devices, and a product can be set to unlimited. When every seat is taken and the fingerprint matches none, the API answers 400 with "activated": false, the error This license key has reached the activation limit., and the license object. The code reads status, activation_limit and activation_usage from that object instead of matching the error text, because the API reference says to branch on status and fields, not messages. A disabled or expired license also answers 400, so the limit test needs status to be active.
The buyer frees a seat at https://clavem.io/licenses/manage: they enter the key, see which installs use it, and remove one. No account or email round trip is needed, so a dead server does not need your help.
Development and staging hosts
isDevHost() is a small helper for deciding which hosts are not a customer’s live site:
public static function isDevHost(string $host): bool
{
return $host === 'localhost'
|| preg_match('/\.(test|localhost|local|invalid|example)$/', $host) === 1
|| (filter_var($host, FILTER_VALIDATE_IP) !== false
&& filter_var($host, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) === false);
}
It returns true for localhost, shop.test, 192.168.1.20 and 10.0.0.5, and false for shop.example.com and staging.shop.com. The last one shows the limit of any such list: a staging subdomain on a real domain looks like production. Whether development hosts use a seat, run unlicensed, or run free is your decision. Write it in your terms so a buyer is not surprised.
Moving a site
- Old server still reachable: call
deactivate(), then activate on the new one. It returnsfalsewhen the server did not confirm, for example with no network. The key is removed locally anyway, so tell the owner to free the seat on the device page. - Old server gone: the owner removes it on the device page and activates the new install.
- Same host name, new server, files copied: nothing to do. The fingerprint is unchanged, so the same seat is returned.
Doing this with Clavem
Activation, validation and deactivation are three POSTs to /v1/licenses/, documented in the API reference. The device page is part of every Clavem account, so a buyer can free a seat without writing to you.
Questions
Does a staging site use up a seat?
Only if it activates. With a host-name fingerprint, yes, because the staging domain is a new fingerprint. With an install id kept in a file that was copied along with the site, it shares the seat of the site it was copied from. Or skip activation on development hosts.
What happens when the buyer removes an install on the device page?
The next validate from that install answers 404 with instance_id not found. The validation code deletes the stored license and asks for the key again, and activating again takes a seat if one is free.