README

A modern, secure and extensible licensing engine for Laravel applications. This package provides the complete domain logic, models, and business rules required to implement a full-featured licensing system inside Laravel applications.

Requirements

PHP 8.4 or higher
Laravel 12.x or higher

Features

Multiple license types: Lifetime, Annual, Subscription, Trial, and Credits-based
License status management: Active, Expired, Suspended, and Revoked
Activation tracking with domain, machine hash, IP, and user agent
Usage monitoring with consumed units and limits
Event logging for complete audit trail
Grace period support for expired licenses
Encrypted metadata storage
Configurable table names and models
Full factory support for testing
100% test coverage (213 tests, 338 assertions)

Installation

You can install the package via composer:

composer require akira/laravel-license

You can publish and run the migrations with:

php artisan vendor:publish --tag="laravel-license-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="laravel-license-config"

This is the contents of the published config file:

return [
    'tables' => [
        'licenses' => 'licenses',
        'activations' => 'license_activations',
        'usages' => 'license_usages',
        'events' => 'license_events',
    ],

    'models' => [
        'license' => License::class,
        'activation' => LicenseActivation::class,
        'usage' => LicenseUsage::class,
        'event' => LicenseEvent::class,
    ],
];

Usage

Creating a License

use Akira\LaravelLicense\Models\License;
use Akira\LaravelLicense\Enums\LicenseType;
use Akira\LaravelLicense\Enums\LicenseStatus;

$license = License::create([
    'key' => 'XXXX-XXXX-XXXX-XXXX',
    'type' => LicenseType::ANNUAL->value,
    'status' => LicenseStatus::ACTIVE->value,
    'max_activations' => 5,
    'max_seats' => 10,
    'expires_at' => now()->addYear(),
]);

Using Factories

// Create a basic license
$license = License::factory()->create();

// Create an active annual license
$license = License::factory()
    ->active()
    ->annual()
    ->create();

// Create a license with grace period
$license = License::factory()
    ->withGracePeriod()
    ->create();

// Create a license with metadata
$license = License::factory()
    ->withMeta(['customer_id' => 123])
    ->create();

License Activation

use Akira\LaravelLicense\Models\LicenseActivation;

$activation = LicenseActivation::create([
    'license_id' => $license->id,
    'domain' => 'example.com',
    'machine_hash' => hash('sha256', 'unique-machine-id'),
    'ip' => request()->ip(),
    'user_agent' => request()->userAgent(),
]);

// Using factory
$activation = LicenseActivation::factory()
    ->forLicense($license)
    ->withDomain('example.com')
    ->create();

Usage Tracking

use Akira\LaravelLicense\Models\LicenseUsage;

$usage = LicenseUsage::create([
    'license_id' => $license->id,
    'consumed_units' => 0,
    'limit' => 1000,
]);

// Check remaining units
$remaining = $usage->remaining(); // 1000

// Consume units
$usage->update(['consumed_units' => 250]);
$remaining = $usage->remaining(); // 750

// Using factory
$usage = LicenseUsage::factory()
    ->forLicense($license)
    ->withLimit(1000)
    ->fresh() // 0 consumed units
    ->create();

Event Logging

use Akira\LaravelLicense\Models\LicenseEvent;
use Akira\LaravelLicense\Enums\LicenseEventType;

$event = LicenseEvent::create([
    'license_id' => $license->id,
    'type' => LicenseEventType::ACTIVATED->value,
    'payload' => [
        'ip' => request()->ip(),
        'user_agent' => request()->userAgent(),
    ],
    'created_at' => now(),
]);

// Using factory
$event = LicenseEvent::factory()
    ->forLicense($license)
    ->activated()
    ->withPayload(['user_id' => 123])
    ->create();

Working with License Status

// Check if license is expired
if ($license->isExpired()) {
    // Handle expired license
}

// Check if license is in grace period
if ($license->inGracePeriod()) {
    // Show warning to user
}

// Get license status as enum
$status = $license->statusEnum(); // LicenseStatus enum

// Get license type as enum
$type = $license->typeEnum(); // LicenseType enum

Relationships

// Get all activations for a license
$activations = $license->activations;

// Get all usage records for a license
$usages = $license->usages;

// Get all events for a license
$events = $license->events;

// Get license from activation
$license = $activation->license;

Custom Table Names

You can customize table names in the config file:

'tables' => [
    'licenses' => 'my_licenses',
    'activations' => 'my_activations',
    'usages' => 'my_usages',
    'events' => 'my_events',
],

Encrypted Metadata

License metadata is automatically encrypted:

$license = License::create([
    'key' => 'XXXX-XXXX-XXXX-XXXX',
    'type' => LicenseType::ANNUAL->value,
    'status' => LicenseStatus::ACTIVE->value,
    'meta' => [
        'customer_email' => 'user@example.com',
        'plan_name' => 'Professional',
        'features' => ['api_access', 'priority_support'],
    ],
]);

// Metadata is automatically encrypted in database
// and decrypted when accessed
$email = $license->meta['customer_email'];

Available License Types

The package includes the following license types through the LicenseType enum:

LIFETIME - Permanent license with no expiration
ANNUAL - Annual subscription that expires after one year
SUBSCRIPTION - Recurring subscription-based license
TRIAL - Trial license with limited time period
CREDITS - Credit-based license for usage tracking

Available License Statuses

License statuses are managed through the LicenseStatus enum:

ACTIVE - License is active and can be used
EXPIRED - License has passed its expiration date
SUSPENDED - License is temporarily suspended
REVOKED - License has been permanently revoked

Available Event Types

Events are tracked using the LicenseEventType enum:

CREATED - License was created
ACTIVATED - License was activated on a device/domain
DEACTIVATED - License was deactivated
ROTATED - License key was rotated
REVOKED - License was revoked
USAGE_CONSUMED - Usage units were consumed
EXPIRED - License expired
ABUSE_DETECTED - Potential abuse was detected

Testing

Run the test suite:

composer test

Run tests with coverage:

composer test:coverage

The package includes 213 tests with 100% code coverage across all components:

Test Coverage

Commands: LaravelLicenseCommand
Enums: LicenseType, LicenseStatus, LicenseEventType
Facades: LaravelLicense
Models: License, LicenseActivation, LicenseEvent, LicenseUsage
Support: ConfigManager
Value Objects: DomainName, LicenseContext, LicenseKey, LicenseMeta, LicenseScopes, MachineFingerprint, UpdateEntitlement, UsageAmount

Additional Test Commands

# Run specific test file
./vendor/bin/pest tests/Models/LicenseTest.php

# Run tests in specific directory
./vendor/bin/pest tests/ValueObjects/

# Run with detailed coverage
./vendor/bin/pest --coverage --min=100

Documentation

Complete documentation is available in the docs directory:

Index - Documentation index and navigation
Introduction - Package overview and features
Installation - Installation and setup guide
Configuration - Configuration options
Models - Model documentation
Usage Guide - Comprehensive usage examples
Enums - Available enumerations
Factories - Testing with factories
Testing - Comprehensive testing guide
Value Objects - Immutable domain objects

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

akira / laravel-license

Maintainers

Details