Download the PHP package lacus/cpf-dv without Composer

🌎 Acessar documentação em português

A PHP utility to calculate check digits on CPF (Brazilian Individual's Taxpayer ID).

PHP Support

Passing ✔	Passing ✔	Passing ✔	Passing ✔

Features

• ✅ Flexible input: Accepts string or array of strings
• ✅ Format agnostic: Automatically strips non-numeric characters from string input
• ✅ Auto-expansion: Multi-character strings in arrays are expanded to individual digits
• ✅ Lazy evaluation: Check digits are calculated only when accessed (via properties)
• ✅ Caching: Calculated values are cached for subsequent access
• ✅ Property-style API: first, second, both, cpf (via magic __get)
• ✅ Minimal dependencies: Only lacus/utils
• ✅ Error handling: Specific types for type, length, and invalid CPF scenarios (TypeError vs Exception semantics)

Installation

Quick Start

Usage

The main resource of this package is the class CpfCheckDigits. Through an instance, you access CPF check-digit information:

• __construct: new CpfCheckDigits(string|array $cpfInput) — 9–11 digits (formatting stripped from strings).
• first: First check digit (10th digit of the CPF). Lazy, cached.
• second: Second check digit (11th digit of the CPF). Lazy, cached.
• both: Both check digits concatenated as a string.
• cpf: The complete CPF as a string of 11 digits (9 base digits + 2 check digits).

Input formats

The CpfCheckDigits class accepts multiple input formats:

String input: plain digits or formatted CPF (e.g. 054.496.519-10). Non-numeric characters are automatically stripped. Use 9 digits (base only) or 11 digits (only the first 9 are used).

Array of strings: single-character strings or multi-character strings (expanded to individual digits), e.g. ['0','5','4','4','9','6','5','1','9'], ['054496519'], ['054','496','519'].

Errors & exceptions handling

This package uses TypeError vs Exception semantics: type errors indicate incorrect API use (e.g. wrong type); exceptions indicate invalid or ineligible data (e.g. invalid CPF). You can catch specific classes or use the abstract bases.

• CpfCheckDigitsTypeError (abstract) — base for type errors; extends PHP’s TypeError
• CpfCheckDigitsInputTypeError — input is not string or string[]
• CpfCheckDigitsException (abstract) — base for data/flow exceptions; extends Exception
• CpfCheckDigitsInputLengthException — sanitized length is not 9–11
• CpfCheckDigitsInputInvalidException — input ineligible (e.g. repeated digits like 111111111)

Other available resources

• CPF_MIN_LENGTH: 9 — class constant CpfCheckDigits::CPF_MIN_LENGTH, and global Lacus\BrUtils\Cpf\CPF_MIN_LENGTH when the autoloaded cpf-dv.php file is loaded.
• CPF_MAX_LENGTH: 11 — class constant CpfCheckDigits::CPF_MAX_LENGTH, and global Lacus\BrUtils\Cpf\CPF_MAX_LENGTH when cpf-dv.php is loaded.

Calculation algorithm

The package calculates CPF check digits using the official Brazilian algorithm:

1. First check digit (10th position): digits 1–9 of the CPF base; weights 10, 9, 8, 7, 6, 5, 4, 3, 2 (from left to right); remainder = 11 - (sum(digit × weight) % 11); result is 0 if remainder > 9, otherwise remainder.
2. Second check digit (11th position): digits 1–9 + first check digit; weights 11, 10, 9, 8, 7, 6, 5, 4, 3, 2 (from left to right); same formula.

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