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

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, 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). 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

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

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

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:

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), 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, 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 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}