# How to Integrate SunLicense into an Existing PHP Project

> Easily integrate SunLicense into your PHP project. Generate secure license keys with this dependency-free, single-file PHP class. Learn how to instantiate and use the generate() method for robust license key creation.

- Repository: [Mehmet Selcuk Batal/php-license-key-generator](https://github.com/msbatal/php-license-key-generator)
- Tags: how-to-guide
- Published: 2026-03-07

---

**SunLicense is a dependency-free PHP 5.5+ class that generates cryptographically random product license keys through a single-file integration requiring only instantiation with optional configuration parameters and a call to the `generate()` method.**

SunLicense provides a lightweight solution for adding license key generation capabilities to any PHP codebase without external dependencies. This single-class library from the `msbatal/php-license-key-generator` repository encapsulates all logic needed to create random, unique keys formatted to your specifications. Whether you need one key or thousands, integrating SunLicense into an existing PHP project requires minimal setup and offers extensive customization through its constructor parameters.

## Core Architecture and Class Structure

The SunLicense library centers around a single self-contained file located at [`SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/SunLicense.php) in the repository root. This file defines the **`SunLicense`** class, which acts as the central engine for all key creation operations without requiring external libraries or Composer dependencies. The repository also includes validation scripts at [`test/SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/test/SunLicense.php) and [`test/index.php`](https://github.com/msbatal/php-license-key-generator/blob/main/test/index.php) demonstrating typical integration patterns.

The class architecture includes five primary properties configured at instantiation:

- **`$prefix`** – Optional text prepended to every generated key
- **`$template`** – Pattern string driving character types where `X` represents letters, `9` represents digits, and `-` represents literal symbols (default: `X9XX99-XX99-9X9X-99XX9X`)
- **`$case`** – String value of `"upper"` or `"lower"` determining letter casing
- **`$keyCount`** – Integer specifying how many distinct keys to produce
- **`$keys`** – Internal array storage tracking generated keys to guarantee uniqueness within a session

Four core methods handle the generation logic:

- **`__construct($prefix, $template, $case, $count)`** – Accepts configuration parameters, stores them in corresponding properties, and registers a generic exception handler to surface runtime errors
- **`license()`** (private) – Implements the character replacement loop iterating over the template and prepending the prefix when defined
- **`check()`** (private) – Verifies generated keys against the `$keys` property to prevent duplicates within the generation session
- **`generate()`** (public) – Orchestrates the generation process by repeatedly calling `license()` until a unique key passes `check()`, returning either a string for single keys or an array for multiple keys, and throwing an exception if generation fails

## Step-by-Step Integration Guide

Adding SunLicense to your existing codebase requires four straightforward steps:

1. **Add the class file** – Copy [`SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/SunLicense.php) from the `msbatal/php-license-key-generator` repository into your project's library directory or include path.

2. **Require the file** – Use a standard `require_once` statement to load the class before instantiation.

3. **Instantiate the class** – Create a new `SunLicense` object, passing any combination of the four optional parameters (`$prefix`, `$template`, `$case`, `$count`) to customize output formatting.

4. **Generate keys** – Execute the **`generate()`** method and handle the returned value, which will be a string for single-key generation or an array for batch generation.

## Configuration Options and Templates

The constructor accepts four optional parameters that control key formatting without requiring file modification:

**Template Patterns** define the visual structure using placeholder characters. The default template `X9XX99-XX99-9X9X-99XX9X` produces standard software-key formatting, but you can specify any pattern combining `X` (letters), `9` (digits), and literal characters such as `-` for separators.

**Prefix Handling** allows vendor or product identification through the **`$prefix`** parameter. When provided, this string prepends directly to the generated key before the template content.

**Case Control** via the **`$case`** parameter accepts `"upper"` or `"lower"` to force consistent letter casing throughout the generated key.

**Batch Generation** occurs when **`$keyCount`** exceeds 1, causing `generate()` to return an array of unique strings rather than a single string value.

## Practical Implementation Examples

### Default Single Key Generation

For basic integration using all default values, simply instantiate without parameters:

```php
require_once 'SunLicense.php';

$license = new SunLicense();
echo $license->generate();
// Output: XG7Y2Z-5M8-9Q3K-12RZ8L

```

### Custom Prefix, Template, and Case

To generate lowercase keys with a product-specific prefix and custom segmentation:

```php
require_once 'SunLicense.php';

$license = new SunLicense(
    'SLK',
    'AA99-9A9A-A9A9-99AA',
    'lower'
);
echo $license->generate();
// Output: slk-ab12-3c4d-e5f6-78gh

```

### Generating Multiple Unique Keys

Request batch generation by specifying the count parameter:

```php
require_once 'SunLicense.php';

$license = new SunLicense(null, null, null, 5);
$keys = $license->generate();

foreach ($keys as $key) {
    echo $key . PHP_EOL;
}

```

### Full Configuration with Batch Generation

Combine all parameters for enterprise licensing scenarios:

```php
require_once 'SunLicense.php';

$license = new SunLicense(
    'PROD',
    'X9X9-9X9X',
    'upper',
    10
);
$keys = $license->generate();
print_r($keys);

```

## Summary

- **SunLicense** resides in a single file ([`SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/SunLicense.php)) requiring only PHP 5.5+ and zero external dependencies, making it compatible with legacy and modern PHP environments.
- Integration requires only file inclusion, instantiation with optional **`$prefix`**, **`$template`**, **`$case`**, and **`$keyCount`** parameters, and calling **`generate()`**.
- The **`generate()`** method returns a string for single keys or an array for multiple keys, with internal **`check()`** logic ensuring uniqueness across the generation session.
- Template customization uses `X` for alphabetic characters, `9` for digits, and literal hyphens or other characters for formatting separators.
- The class automatically registers an exception handler to surface runtime errors during the generation process.

## Frequently Asked Questions

### What PHP version does SunLicense require?

SunLicense requires **PHP 5.5 or higher** according to the repository documentation. The class uses only core PHP functions available in standard installations since version 5.5, making it compatible with both legacy and modern PHP environments without additional extensions.

### How does SunLicense ensure generated keys are unique?

The class maintains an internal **`$keys`** array property that tracks all generated strings within the current instance. The private **`check()`** method verifies each newly generated key against this array before returning it, and the **`generate()`** method continues looping until a unique candidate passes verification or throws an exception if generation fails.

### Can I customize the license key format beyond the default pattern?

Yes. Pass a custom **`$template`** string to the constructor using `X` placeholders for random letters, `9` for random digits, and any other characters for fixed separators. For example, the template `'XX99-XXXX'` produces four letters, two digits, a hyphen, then four more letters, allowing complete control over key structure and length.

### Does SunLicense support generating multiple keys in one operation?

Yes. Set the **`$keyCount`** parameter (fourth constructor argument) to any integer greater than 1. The **`generate()`** method will then return an indexed array containing the specified number of unique keys, with the internal **`check()`** method verifying uniqueness against each other within that single generation call.