Can You Use Special Characters in the SunLicense Template? A Deep Dive into the PHP License Key Generator

No, you cannot use arbitrary special characters in the SunLicense template—any character that is not a letter or digit is automatically converted to a hyphen (-).

The SunLicense class in the msbatal/php-license-key-generator repository processes license key templates through a strict three-category parser. If you need to understand exactly what characters are supported and how the generator handles unexpected symbols, examining the source code in SunLicense.php reveals the precise limitations of the template syntax.

How the SunLicense Template Parser Works

The template parsing logic resides in the core generation loop of SunLicense.php (lines 84–96). The class examines each character of your template string sequentially and categorizes it into one of three distinct behaviors:

Letter Placeholders (A-Z)

When the parser encounters an alphabetic character—whether uppercase or lowercase—it triggers the letter generation branch. According to lines 84–90, the code uses preg_match('/[a-zA-Z]/', $this->template[$i]) to detect letters. By default, this produces a random uppercase letter, though you can configure the case parameter to generate lowercase letters instead.

Digit Placeholders (0-9)

Numeric characters in the template activate the digit generation path. At line 92, the parser checks for digits using preg_match('/\d/', $this->template[$i]) and substitutes a random number from 0 through 9 at that position in the final key.

Symbol Handling: The Default Hyphen Rule

The critical limitation for special characters appears in the else branch at line 94. The parser uses a simple fallthrough logic: if a character is not a letter and not a digit, it executes else { $key .= '-'; // generate symbols }. This means every non-alphanumeric character—whether it is @, #, *, /, or any other symbol—is unconditionally replaced by a literal hyphen character.

What Happens When You Use Special Characters

Attempting to embed arbitrary symbols in your template results in automatic conversion to hyphens. The generator does not preserve your original special character, nor does it map different symbols to different outputs.

Consider this practical demonstration:

require_once 'SunLicense.php';

// Attempting to use various symbols in the template
$tmpl = 'A9@A9#-A*9A';
$license = new SunLicense(null, $tmpl);
echo $license->generate();

Example output:

G5-9H7-6R4G

In this execution, the @, #, and * characters in the template are not recognized as special placeholders. Instead, each triggers the else branch at line 94, producing hyphens in the final output. The explicit hyphen in the template also produces a hyphen, resulting in multiple consecutive hyphens if you mix explicit hyphens with special characters.

Customizing the Symbol Character

If you require a delimiter other than the hyphen, you must modify the source code directly. The current implementation in SunLicense.php hardcodes the hyphen at line 94. To use a different separator—such as an underscore _ or period .—you would need to edit the else branch to append your preferred character instead of '-'.

Alternatively, you could extend the class to add new placeholder types (for example, mapping S to specific symbols), but this requires subclassing or forking the repository rather than using the template string alone.

Summary

• Three template tokens only: The SunLicense class recognizes letters (A), digits (9), and treats everything else as a hyphen placeholder.
• Automatic hyphen conversion: Any special character (@, #, *, etc.) in your template becomes a - in the generated key due to the fallthrough logic at line 94 of SunLicense.php.
• No native symbol support: You cannot preserve arbitrary special characters in the final license key without modifying the source code.
• Custom delimiters require editing: To change the default symbol from hyphen to another character, alter the else branch in the template processing loop.

Frequently Asked Questions

Can I use underscores or periods instead of hyphens in my license key template?

No, not without modifying the source code. As implemented in msbatal/php-license-key-generator, line 94 of SunLicense.php explicitly appends a hyphen - for any non-alphanumeric template character. If you replace '-' with '_' or '.' in that line, the generator will use your preferred delimiter instead.

Why do my special characters turn into hyphens when generating license keys?

This occurs because the template parser uses a regex-based classification system. Lines 84–92 check for letters (/[a-zA-Z]/) and digits (/\d/), while line 94 catches all remaining characters. Since @, #, and similar symbols match neither regex, they fall through to the symbol generation branch that hardcodes hyphens.

Is there a way to add custom placeholder symbols like X for special characters?

The current SunLicense class does not support custom placeholder mappings. The template syntax is limited to the three built-in behaviors. To add a custom placeholder (for example, having X generate random symbols), you would need to extend the class and override the template processing method in SunLicense.php to handle additional regex patterns before the final else branch.

Does the case parameter affect how special characters are handled?

No. The case parameter only influences the output of letter placeholders (A). Setting case to 'lower' affects lines 84–90, converting letter output to lowercase. Special characters bypass this logic entirely and always trigger the hyphen substitution at line 94, regardless of the case setting.

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