README

Utility function/class to validate CPF (Brazilian personal ID).

PHP Support


Passing ✔	Passing ✔	Passing ✔

Installation

# using Composer
$ composer require lacus/cpf-val

Import

<?php
// Using class-based resource
use Lacus\CpfVal\CpfValidator;

// Or using function-based one
use function Lacus\CpfVal\cpf_val;

Usage

Object-Oriented Usage

$validator = new CpfValidator();
$cpf = '11144477735';

echo $validator->isValid($cpf) ? 'Valid' : 'Invalid';  // returns 'Valid'

$cpf = '111.444.777-35';
echo $validator->isValid($cpf) ? 'Valid' : 'Invalid';  // returns 'Valid'

$cpf = '11144477736';
echo $validator->isValid($cpf) ? 'Valid' : 'Invalid';  // returns 'Invalid'

Imperative programming

The helper function cpf_val() is just a functional abstraction. Internally it creates an instance of CpfValidator and calls the isValid() method right away.

$cpf = '11144477735';

echo cpf_val($cpf) ? 'Valid' : 'Invalid';      // returns 'Valid'

echo cpf_val('111.444.777-35') ? 'Valid' : 'Invalid';  // returns 'Valid'

echo cpf_val('11144477736') ? 'Valid' : 'Invalid';     // returns 'Invalid'

Validation Examples

// Valid CPF numbers
cpf_val('11144477735')      // returns true
cpf_val('111.444.777-35')   // returns true
cpf_val('12345678909')      // returns true

// Invalid CPF numbers
cpf_val('11144477736')      // returns false
cpf_val('12345678901')      // returns false
cpf_val('00000000000')      // returns false
cpf_val('11111111111')      // returns false
cpf_val('123')              // returns false (too short)
cpf_val('')                 // returns false (empty)

Features

✅ Format Agnostic: Accepts CPF with or without formatting (dots, dashes)
✅ Strict Validation: Validates both check digits according to Brazilian CPF algorithm
✅ Type Safety: Built with PHP 8.1+ strict types
✅ Lightweight: Minimal dependencies, only requires lacus/cpf-gen for check digit calculation
✅ Dual API: Both object-oriented and functional programming styles supported

API Reference

CpfValidator Class

`isValid(string $cpfString): bool`

Validates a CPF string and returns true if valid, false otherwise.

Parameters:

$cpfString (string): The CPF to validate (with or without formatting)

Returns:

bool: true if the CPF is valid, false otherwise

cpf_val() Function

`cpf_val(string $cpfString): bool`

Functional wrapper around CpfValidator::isValid().

Parameters:

$cpfString (string): The CPF to validate (with or without formatting)

Returns:

bool: true if the CPF is valid, false otherwise

Validation Algorithm

The package validates CPF using the official Brazilian algorithm:

Length Check: Ensures the CPF has exactly 11 digits
First Check Digit: Calculates and validates the 10th digit
Second Check Digit: Calculates and validates the 11th digit
Format Tolerance: Automatically strips non-numeric characters before validation

Error Handling

The validator is designed to be forgiving with input format but strict with validation:

Invalid formats (too short, too long) return false
Invalid check digits return false
Empty strings return false
Non-numeric strings (after stripping formatting) return false

Dependencies

PHP: >= 8.1
lacus/cpf-gen: ^1.0 (for check digit calculation)

Contribution & Support

We welcome contributions! Please see our Contributing Guidelines for details. But 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

lacus / cpf-val

Maintainers

Details