README

Official PHP SDK for integrating TweekersNut License Management System into your applications.

Features

🔐 License Activation - Activate licenses with hardware binding
✅ License Validation - Online and offline validation with caching
🎯 Feature Gating - Control features based on license type
💻 Hardware Fingerprinting - Bind licenses to specific machines (excludes USB/removable storage)
⚡ Smart Caching - Automatic caching to reduce server load
🛡️ Exception Handling - Proper error handling with custom exceptions
🌐 Cross-Platform - Works on Windows, Linux, and macOS

Installation

Install via Composer:

composer require tweekersnut/license-sdk

Quick Start

1. Initialize the Client

<?php
require 'vendor/autoload.php';

use TweekersNut\LicenseSDK\LicenseClient;

$license = new LicenseClient(
    'https://license.yourdomain.com',  // Your license server URL
    file_get_contents('public.pem'),    // Public key for verification
    'license.tnlic'                     // License file path (optional)
);

2. Activate a License

try {
    $result = $license->activate('TNPRO-XXXXX-XXXXX-XXXXX-XXXXX');
    echo "License activated successfully!\n";
} catch (\TweekersNut\LicenseSDK\Exceptions\LicenseException $e) {
    echo "Activation failed: " . $e->getMessage() . "\n";
}

3. Validate License

try {
    $result = $license->validate(true); // true = online validation
    
    if ($result['valid']) {
        echo "License is valid!\n";
        // Your application code here
    } else {
        echo "License invalid: " . $result['reason'] . "\n";
    }
} catch (\TweekersNut\LicenseSDK\Exceptions\ValidationException $e) {
    echo "Validation error: " . $e->getMessage() . "\n";
}

4. Check Features

if ($license->hasFeature('premium')) {
    // Show premium features
    echo "Premium features enabled!\n";
} else {
    // Show basic features only
    echo "Upgrade to unlock premium features\n";
}

// Get all enabled features
$features = $license->getFeatures();
print_r($features);

Complete Example

<?php
require 'vendor/autoload.php';

use TweekersNut\LicenseSDK\LicenseClient;
use TweekersNut\LicenseSDK\Exceptions\LicenseException;

// Initialize
$license = new LicenseClient(
    'https://license.yourdomain.com',
    file_get_contents('public.pem'),
    'license.tnlic'
);

// Check if already activated
if (!$license->isActivated()) {
    // Show activation form
    echo "Please enter your license key: ";
    $licenseKey = trim(fgets(STDIN));
    
    try {
        $license->activate($licenseKey);
        echo "✓ License activated successfully!\n";
    } catch (LicenseException $e) {
        die("✗ Activation failed: " . $e->getMessage() . "\n");
    }
}

// Validate license
try {
    $result = $license->validate(true);
    
    if ($result['valid']) {
        echo "✓ License is valid\n";
        
        // Check features
        if ($license->hasFeature('api_access')) {
            echo "✓ API access enabled\n";
        }
        
        if ($license->hasFeature('premium')) {
            echo "✓ Premium features enabled\n";
        }
        
        // Your application logic here
        runApplication();
        
    } else {
        die("✗ License invalid: " . $result['reason'] . "\n");
    }
} catch (LicenseException $e) {
    die("✗ Validation error: " . $e->getMessage() . "\n");
}

function runApplication() {
    echo "\n🚀 Application is running...\n";
    // Your application code here
}

API Reference

LicenseClient

Constructor

public function __construct(
    string $serverUrl,
    string $publicKey,
    ?string $licenseFile = null
)

$serverUrl - License server URL (e.g., https://license.yourdomain.com)
$publicKey - Public key in PEM format for signature verification
$licenseFile - Optional path to store license file

Methods

activate(string $licenseKey): array

Activate a license with the provided license key.

Returns: ['success' => true, 'message' => '...']

Throws: LicenseException on failure

validate(bool $online = true): array

Validate the current license.

Parameters:

$online - true for online validation, false for offline

Returns: ['valid' => true, 'license_key' => '...', 'features' => [...]]

Throws: ValidationException if no license is activated

hasFeature(string $featureName): bool

Check if a specific feature is enabled.

Returns: true if feature is enabled, false otherwise

getFeatures(): array

Get all enabled features.

Returns: Array of feature names

deactivate(): array

Deactivate the current license.

Returns: ['success' => true, 'message' => '...']

Throws: LicenseException on failure

isActivated(): bool

Check if a license is currently activated.

Returns: true if activated, false otherwise

getLicenseInfo(): ?array

Get current license information.

Returns: License data array or null if not activated

Integration Examples

WordPress Plugin

class MyPremiumPlugin {
    private $license;
    
    public function __construct() {
        $this->license = new LicenseClient(
            'https://license.yourdomain.com',
            file_get_contents(plugin_dir_path(__FILE__) . 'public.pem'),
            plugin_dir_path(__FILE__) . 'license.tnlic'
        );
        
        add_action('admin_init', [$this, 'check_license']);
    }
    
    public function check_license() {
        if (!$this->license->isActivated()) {
            add_action('admin_notices', function() {
                echo '<div class="error"><p>Please activate your license</p></div>';
            });
            return;
        }
        
        try {
            $result = $this->license->validate();
            if (!$result['valid']) {
                add_action('admin_notices', function() use ($result) {
                    echo '<div class="error"><p>License error: ' . $result['reason'] . '</p></div>';
                });
            }
        } catch (Exception $e) {
            // Handle error
        }
    }
}

Laravel Application

// In a Service Provider
public function boot() {
    $license = new LicenseClient(
        config('license.server_url'),
        file_get_contents(storage_path('app/public.pem')),
        storage_path('app/license.tnlic')
    );
    
    $this->app->instance('license', $license);
}

// In a Middleware
public function handle($request, Closure $next) {
    $license = app('license');
    
    if (!$license->isActivated()) {
        return redirect()->route('license.activate');
    }
    
    try {
        $result = $license->validate();
        if (!$result['valid']) {
            return response()->json(['error' => 'Invalid license'], 403);
        }
    } catch (Exception $e) {
        return response()->json(['error' => 'License error'], 500);
    }
    
    return $next($request);
}

Standalone Application

// bootstrap.php
require 'vendor/autoload.php';

$license = new LicenseClient(
    getenv('LICENSE_SERVER_URL'),
    file_get_contents(__DIR__ . '/public.pem'),
    __DIR__ . '/license.tnlic'
);

// Validate on startup
if (!$license->isActivated() || !$license->validate()['valid']) {
    die("License required. Please activate your license.\n");
}

// Continue with application

Hardware Fingerprinting

The SDK automatically collects hardware information for license binding:

✅ CPU ID - Processor serial number
✅ System Disk Serial - Primary disk only (excludes USB/external drives)
✅ MAC Address - Primary network adapter
✅ Motherboard Serial - Motherboard identifier
✅ OS Information - Operating system type and version

Important: The SDK only fingerprints permanent hardware. USB drives, external storage, and removable media are excluded to prevent false hardware change detections.

Caching

The SDK automatically caches validation results for 15 minutes to reduce server load and improve performance. Cache is stored in the system temp directory by default.

Error Handling

The SDK provides specific exceptions for different error types:

use TweekersNut\LicenseSDK\Exceptions\LicenseException;
use TweekersNut\LicenseSDK\Exceptions\ValidationException;
use TweekersNut\LicenseSDK\Exceptions\NetworkException;

try {
    $license->activate($key);
} catch (NetworkException $e) {
    // Network/connectivity issues
    echo "Network error: " . $e->getMessage();
} catch (ValidationException $e) {
    // Validation-specific errors
    echo "Validation error: " . $e->getMessage();
} catch (LicenseException $e) {
    // General license errors
    echo "License error: " . $e->getMessage();
}

Requirements

PHP 8.0 or higher
cURL extension
JSON extension
OpenSSL extension

Support

Documentation: https://docs.tweekersnut.com/license-sdk
Issues: https://github.com/tweekersnut/license-sdk/issues
Email: support@tweekersnut.com

License

MIT License. See LICENSE file for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Made with ❤️ by TweekersNut Network

tweekersnut / license-sdk

Maintainers

Package info

Statistics

Security