# How to Use a Custom Template with the PHP License Key Generator

> Learn to use custom templates with the PHP License Key Generator by passing your pattern to the constructor. Generate keys matching your exact specification effortlessly.

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

---

**Pass your custom pattern as the second argument to the `SunLicense` constructor, using `A` for alphabetic characters and `9` for digits, then call `generate()` to produce keys matching your exact specification.**

The **PHP License Key Generator** (`msbatal/php-license-key-generator`) enables precise control over license key formatting through configurable templates. When you use a custom template with the PHP License Key Generator, you define the specific arrangement of letters, numbers, and separators that appear in every generated key. The core implementation resides in [`SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/SunLicense.php), where the `license()` method processes template characters according to strict mapping rules.

## Understanding Template Syntax and Character Mapping

The template system interprets each character in your pattern string through logic defined in the private `license()` method (lines 84-95 of [`SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/SunLicense.php)). The method evaluates characters using regular expressions to determine output:

- **`A`** — Generates a random alphabetic character. The `license()` method checks against `/[a-zA-Z]/` and produces a letter based on the `$case` property (uppercase by default, lowercase when specified).
- **`9`** — Generates a random digit 0-9. The method matches against `/\d/` to trigger numeric generation.
- **Any other character** — Inserted literally as a separator. Hyphens are most common, but dots, underscores, or spaces pass through unchanged.

The constructor stores your custom template in the private `$template` property (lines 63-65) and references it during the generation loop.

## Configuring Custom Templates in the Constructor

The `SunLicense` class accepts four constructor arguments, with the template specified as the second parameter:

1. `$prefix` — Optional string prepended to the key with a trailing hyphen
2. `$template` — Your custom pattern string defining the key structure
3. `$case` — `'upper'` or `'lower'` controlling alphabetic character casing
4. `$count` — Integer specifying how many unique keys to generate

### Basic Custom Template Implementation

```php
require_once 'SunLicense.php';

// Template: Two letters, two digits, separator, four letters
$license = new SunLicense(null, 'AA99-AAAA');
echo $license->generate();  // e.g., "XK47-MQTP"

```

### Lowercase Letters with Custom Patterns

```php
require_once 'SunLicense.php';

// Same template forced to lowercase via third parameter
$license = new SunLicense(null, 'AA99-AAAA', 'lower');
echo $license->generate();  // e.g., "xk47-mqtp"

```

### Multiple Keys with Prefix and Template

```php
require_once 'SunLicense.php';

// Prefix "PRO", custom template, uppercase, generate 5 keys
$license = new SunLicense('PRO', 'AA99-9A9A-A9A9-99AA', 'upper', 5);
$keys = $license->generate();

print_r($keys);
/*
Array
(
    [0] => PRO-EB34-7J2K-M4Q8-12XZ
    [1] => PRO-RT67-1M5N-P9L2-34GH
    [2] => PRO-QW12-8Z3V-B6Y5-78JK
    [3] => PRO-OP90-5X1C-D4R7-56MN
    [4] => PRO-LK23-9U8W-A1S3-90DE
)
*/

```

## Advanced Template Usage and Batch Generation

For applications requiring multiple template patterns, instantiate separate `SunLicense` objects or iterate through templates as demonstrated in [`test/index.php`](https://github.com/msbatal/php-license-key-generator/blob/main/test/index.php):

```php
require_once 'SunLicense.php';

$templates = [
    'AA99-9A9A',      // Short product keys
    'X9XX99',         // Compact format
    'AA-99-AA'        // Simple pattern
];

foreach ($templates as $template) {
    $generator = new SunLicense('PRD', $template, 'upper', 2);
    $keys = $generator->generate();
    
    echo "Template {$template} generates:\n";
    foreach ($keys as $key) {
        echo "  {$key}\n";
    }
}

```

The `generate()` method ensures uniqueness through the private `check()` method (lines 106-111 in [`SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/SunLicense.php)), which compares each new key against previously generated entries stored in the `$keys` array. If a duplicate is detected, the generator discards it and creates a replacement until the requested `$count` of unique keys is reached.

## Summary

- **Custom templates** control license key structure through the `SunLicense` constructor's second parameter.
- **Character mapping** uses `A` for letters and `9` for digits; all other characters render as literal separators.
- **Case control** via the third constructor argument affects all alphabetic positions in the template.
- **Uniqueness guarantee** is handled internally by the `check()` method when generating multiple keys.
- **Source implementation** resides in [`SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/SunLicense.php), specifically in the `license()` method (lines 84-95) and constructor (lines 63-65).

## Frequently Asked Questions

### What characters can I use in a custom template?

Use `A` to generate random alphabetic characters and `9` to generate random digits. Any other character—including hyphens, dots, underscores, or spaces—appears literally in the output as a separator. The `license()` method in [`SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/SunLicense.php) uses regular expressions to distinguish between these character types during generation.

### How do I make the generated keys lowercase?

Pass `'lower'` as the third argument to the `SunLicense` constructor. This sets the private `$case` property, which the `license()` method references when generating characters for every `A` position in your template. The default value is `'upper'`, which produces capital letters.

### Can I use special characters other than hyphens?

Yes. The template parser treats any non-alphanumeric character as a literal separator. You can use dots, underscores, slashes, or spaces, and they will appear exactly where placed in your template string. For example, a template of `AA.99_AA` produces keys like `XK.47_MQ`.

### How does the library ensure unique keys?

The `generate()` method calls the private `check()` method (lines 106-111 in [`SunLicense.php`](https://github.com/msbatal/php-license-key-generator/blob/main/SunLicense.php)) after creating each key. This method compares the new key against all previously generated entries stored in the `$keys` array. If a duplicate is detected, the generator discards it and creates a new one until the requested number of unique keys is reached.