🚀 Full support for the new alphanumeric CNPJ format.

🌎 Acessar documentação em português

A PHP utility to generate valid CNPJ (Brazilian Business Tax ID).

PHP Support

Passing ✔	Passing ✔	Passing ✔	Passing ✔

Features

• ✅ Alphanumeric CNPJ generation: Supports base characters from 0-9 and A-Z with numeric check digits
• ✅ Flexible options API: Use named arguments or a CnpjGeneratorOptions instance
• ✅ Configurable base prefix: Provide up to 12 base characters and generate only missing positions
• ✅ Format output toggle: Return compact (14 chars) or formatted (18 chars) output
• ✅ Per-call override model: Instance defaults can be overridden for one generate() call only
• ✅ Typed option validation: Dedicated TypeError/Exception subclasses for invalid option usage
• ✅ Dual API style: Object-oriented (CnpjGenerator) and functional (cnpj_gen())

Installation

# using Composer
$ composer require lacus/cnpj-gen

Import

<?php

use Lacus\BrUtils\Cnpj\CnpjGenerator;
use Lacus\BrUtils\Cnpj\CnpjGeneratorOptions;
use Lacus\BrUtils\Cnpj\Enums\CnpjType;

use function Lacus\BrUtils\Cnpj\cnpj_gen;

Quick start

<?php

use Lacus\BrUtils\Cnpj\CnpjGenerator;

$generator = new CnpjGenerator();

$generator->generate();                // e.g. "AB123CDE000196"
$generator->generate(format: true);    // e.g. "AB.123.CDE/0001-96"

Usage

The main entry points are the class CnpjGenerator, the options object CnpjGeneratorOptions, the enum CnpjType, and the helper cnpj_gen().

CnpjGenerator

• __construct: new CnpjGenerator(?CnpjGeneratorOptions $options = null, $format = null, $prefix = null, $type = null)

  If $options is a CnpjGeneratorOptions instance, that same instance is stored internally (mutations later affect future generate() calls with no per-call override). Otherwise, a new options object is built from named values.

• getOptions(): Returns the internal CnpjGeneratorOptions instance.

• generate: generate(?CnpjGeneratorOptions $options = null, $format = null, $prefix = null, $type = null): string

  Per-call options are merged over instance defaults only for that call. Returned value is:

  • 14 characters when format = false (default)
  • 18 characters with separators when format = true (XX.XXX.XXX/XXXX-XX)

<?php

use Lacus\BrUtils\Cnpj\CnpjGenerator;
use Lacus\BrUtils\Cnpj\Enums\CnpjType;

$generator = new CnpjGenerator(type: CnpjType::Numeric);

$generator->generate();                                 // e.g. "12345678000195"
$generator->generate(format: true);                     // e.g. "12.345.678/0001-95"
$generator->generate(prefix: 'AB123CDE');               // e.g. "AB123CDE000196"
$generator->generate(prefix: 'AB123CDE', format: true); // e.g. "AB.123.CDE/0001-96"

Default options on the instance; per-call overrides:

$generator = new CnpjGenerator(format: true, type: CnpjType::Numeric);

$generator->generate();                // formatted numeric CNPJ
$generator->generate(format: false);   // this call only: unformatted
$generator->generate();                // formatted again (instance defaults preserved)

CnpjGeneratorOptions

CnpjGeneratorOptions encapsulates generator configuration (format, prefix, type), supports magic property access (__get/__set), and can merge layered values through overrides.

• Constructor: new CnpjGeneratorOptions($format = null, $prefix = null, $type = null, ?array $overrides = [])
  • overrides accepts a list of arrays and/or other CnpjGeneratorOptions instances
  • merge order is left to right (last override wins)
• set(...): Updates one or more option values and returns $this
• getAll(): Returns a shallow snapshot array (format, prefix, type)

Generation options

Parameter	Type	Default	Description
format	?bool	false	When true, returns formatted CNPJ (XX.XXX.XXX/XXXX-XX); otherwise returns compact 14-character output
prefix	?string	''	Base seed for generation. Non-alphanumeric chars are stripped, letters are uppercased, and only first 12 chars (indexes 0-11) are used; characters at index 12+ are ignored
type	CnpjType|'alphanumeric'|'alphabetic'|'numeric'|null	CnpjType::Alphanumeric	Character family used for generated base positions (0-9, A-Z, or both)

prefix validation rules:

• base ID 00000000 is rejected (when first 8 chars are present)
• branch ID 0000 is rejected (when chars 9-12 are present)
• 12 repeated numeric digits are rejected (e.g. 111111111111)

CnpjType

Available enum cases:

• CnpjType::Alphanumeric
• CnpjType::Alphabetic
• CnpjType::Numeric

Helper methods:

• CnpjType::values(): list<string>
• CnpjType::toSequenceType(): SequenceType

Functional helper

cnpj_gen() is a convenience wrapper:

• Builds a new CnpjGenerator with the same constructor arguments
• Calls generate() once

$cnpj = cnpj_gen();               // e.g. "AB123CDE000196"
$cnpj = cnpj_gen(format: true);   // e.g. "AB.123.CDE/0001-96"
$cnpj = cnpj_gen(prefix: '12345678', type: CnpjType::Numeric);

Errors & exceptions

This package uses TypeError vs Exception semantics:

• Type errors indicate wrong API/option types
• Exceptions indicate invalid option values or business-rule violations

Relevant classes:

• CnpjGeneratorTypeError (abstract, extends PHP TypeError)
• CnpjGeneratorOptionsTypeError
• CnpjGeneratorException (abstract, extends Exception)
• CnpjGeneratorOptionPrefixInvalidException
• CnpjGeneratorOptionTypeInvalidException

<?php

use Lacus\BrUtils\Cnpj\CnpjGenerator;
use Lacus\BrUtils\Cnpj\Exceptions\CnpjGeneratorOptionPrefixInvalidException;
use Lacus\BrUtils\Cnpj\Exceptions\CnpjGeneratorOptionTypeInvalidException;
use Lacus\BrUtils\Cnpj\Exceptions\CnpjGeneratorOptionsTypeError;

try {
    $generator = new CnpjGenerator(prefix: '00000000');
    $generator->generate();
} catch (CnpjGeneratorOptionPrefixInvalidException $e) {
    echo $e->getMessage();
}

try {
    new CnpjGenerator(type: 'invalid');
} catch (CnpjGeneratorOptionTypeInvalidException $e) {
    echo $e->getMessage();
}

try {
    new CnpjGenerator(prefix: 123);
} catch (CnpjGeneratorOptionsTypeError $e) {
    echo $e->getMessage();
}

Other available resources

• CnpjGeneratorOptions::CNPJ_LENGTH (14)
• CnpjGeneratorOptions::CNPJ_PREFIX_MAX_LENGTH (12)

Contribution & Support

We welcome contributions! Please see our Contributing Guidelines for details. If you find this project helpful, please consider:

• ⭐ Starring the repository
• 🤝 Contributing to the codebase
• 💡 Suggesting new features
• 🐛 Reporting bugs

License

This project is licensed under the MIT License — see the LICENSE file for details.

Changelog

See CHANGELOG for a list of changes and version history.

---

Made with ❤️ by Lacus Solutions