PHPackages                             validbr/validbr - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. validbr/validbr

ActiveLibrary

validbr/validbr
===============

A comprehensive Brazilian validation library for PHP

10[12 PRs](https://github.com/julioamorimdev/ValidBR/pulls)TypeScriptCI passing

Since Aug 6Pushed 4mo ago1 watchersCompare

[ Source](https://github.com/julioamorimdev/ValidBR)[ Packagist](https://packagist.org/packages/validbr/validbr)[ RSS](/packages/validbr-validbr/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)DependenciesVersions (13)Used By (0)

ValidBR 🇧🇷
==========

[](#validbr-)

[![npm version](https://camo.githubusercontent.com/734995dd5866738533415d2957b77ae1b9146a04c73b21f6fcfc9a6f16d36563/68747470733a2f2f62616467652e667572792e696f2f6a732f76616c696462722e737667)](https://www.npmjs.com/package/validbr)[![PyPI version](https://camo.githubusercontent.com/0b0249a3e04310d98004b00d100b682c9c29cbc1404da71a48accf981eef631b/68747470733a2f2f62616467652e667572792e696f2f70792f76616c696462722e737667)](https://pypi.org/project/validbr/)[![Packagist version](https://camo.githubusercontent.com/6d2f18c0c808f1b3df6f5828ce5b5579247f54edd9465050830c90391c17fdc7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f76616c696462722f76616c696462722e737667)](https://packagist.org/packages/validbr/validbr)[![Build Status](https://github.com/validbr/validbr/workflows/CI/badge.svg)](https://github.com/validbr/validbr/actions)[![Test Coverage](https://camo.githubusercontent.com/b188bcbaa4890c9654033710c09fc9d2acada17e1a821dd16007ffb11808019d/68747470733a2f2f636f6465636f762e696f2f67682f76616c696462722f76616c696462722f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/validbr/validbr)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![GitHub stars](https://camo.githubusercontent.com/db56031067022702dc3f6f7de455064179b50fe67ea5745fd487b7d4b44bd68a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f76616c696462722f76616c69646272)](https://github.com/validbr/validbr/stargazers)[![GitHub forks](https://camo.githubusercontent.com/594385917811e8ec68e1ae7d6c45b77113bb84e76e5bf4ff7d56a40e3b3da3a4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f76616c696462722f76616c69646272)](https://github.com/validbr/validbr/network)[![GitHub issues](https://camo.githubusercontent.com/0d73dfce18b67b58199c5bfb1111400f963f75c68d79fccbfcebd84f83f182f2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f76616c696462722f76616c69646272)](https://github.com/validbr/validbr/issues)[![GitHub pull requests](https://camo.githubusercontent.com/6be4c6432c9422a0fe5e4105867863181557f029aeea97248cdcae2d0d5d8170/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732d70722f76616c696462722f76616c69646272)](https://github.com/validbr/validbr/pulls)

 [![Node.js Support](https://camo.githubusercontent.com/883975d46f7c17665c7f7cd452484d9e9ce39ce33826baaa37320f81c8ff10cb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4e6f64652e6a732de29c932d677265656e3f7374796c653d666f722d7468652d6261646765266c6f676f3d6e6f64652e6a73)](https://camo.githubusercontent.com/883975d46f7c17665c7f7cd452484d9e9ce39ce33826baaa37320f81c8ff10cb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4e6f64652e6a732de29c932d677265656e3f7374796c653d666f722d7468652d6261646765266c6f676f3d6e6f64652e6a73) [![Python Support](https://camo.githubusercontent.com/926726f87d57f8b369ed35a739a7e5156dd13bd10722dec5872a70a96b4f0f48/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f507974686f6e2de29c932d677265656e3f7374796c653d666f722d7468652d6261646765266c6f676f3d707974686f6e)](https://camo.githubusercontent.com/926726f87d57f8b369ed35a739a7e5156dd13bd10722dec5872a70a96b4f0f48/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f507974686f6e2de29c932d677265656e3f7374796c653d666f722d7468652d6261646765266c6f676f3d707974686f6e) [![PHP Support](https://camo.githubusercontent.com/d72b357a763123ed16b64da0383a7f5a2ad2c98a5e8a4d4129b005e7ef02337c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502de29c932d677265656e3f7374796c653d666f722d7468652d6261646765266c6f676f3d706870)](https://camo.githubusercontent.com/d72b357a763123ed16b64da0383a7f5a2ad2c98a5e8a4d4129b005e7ef02337c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502de29c932d677265656e3f7374796c653d666f722d7468652d6261646765266c6f676f3d706870)

---

### 📦 Available on Package Managers

[](#-available-on-package-managers)

 [ ![npm](https://camo.githubusercontent.com/57c765bc71362e45528372f1283ac5750f753367db02886dcf48d155392e9f8b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6e706d2d76616c696462722d626c75653f7374796c653d666f722d7468652d6261646765266c6f676f3d6e706d) ](https://www.npmjs.com/package/validbr) [ ![PyPI](https://camo.githubusercontent.com/19958b1a55e1e123fa89440fd581a167940f135f631ddfd923e55a4edae1be68/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f507950492d76616c696462722d626c75653f7374796c653d666f722d7468652d6261646765266c6f676f3d70797069) ](https://pypi.org/project/validbr/) [ ![Packagist](https://camo.githubusercontent.com/5811aeb06685abdeb5c0d7d3d38169be80258924617111528c22223fa46f030c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5061636b61676973742d76616c696462722d626c75653f7374796c653d666f722d7468652d6261646765266c6f676f3d636f6d706f736572) ](https://packagist.org/packages/validbr/validbr)

---

🌟 Live Demo
-----------

[](#-live-demo)

Test all ValidBR features directly in your browser: **[🚀 Open Interactive Demo](demo.html)**

> **💡 Tip**: Open the `demo.html` file in your browser to test all ValidBR features interactively!

---

📋 Table of Contents
-------------------

[](#-table-of-contents)

- [Overview](#overview)
- [Features](#-features)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Documentation](#-documentation)
- [Testing](#-testing)
- [Contributing](#-contributing)
- [Support](#-support)
- [License](#-license)

---

📖 Overview
----------

[](#-overview)

**ValidBR** is a comprehensive Brazilian validation library available for **Node.js**, **Python**, and **PHP**. It provides robust validation for Brazilian documents, phone numbers, addresses, and personal information with advanced features like mask application, state identification, and data sanitization.

### 🎯 What ValidBR Validates

[](#-what-validbr-validates)

- **📄 Documents**: CPF, CNPJ, RG, IE (State Registration), CNH, Voter ID (Título de Eleitor), PIS/NIS/NIT/PASEP
- **📞 Communication**: Phone numbers, Email addresses
- **📍 Location**: CEP (ZIP codes), DDD codes, State identification
- **👤 Personal**: Full names, Birth dates
- **🛠️ Utilities**: Mask application/removal, Data sanitization

---

✨ Features
----------

[](#-features)

### 🔐 Document Validation

[](#-document-validation)

- ✅ **CPF/CNPJ Validation** - Complete validation with check digits and state identification
- ✅ **RG Validation** - Including check digits for supported states
- ✅ **State Registration (IE) Validation** - By UF with state-specific algorithms
- ✅ **CNH Validation** - Brazilian Driver's License (CNH) validation
- ✅ **Voter ID (Título de Eleitor) Validation**
- ✅ **PIS/NIS/NIT/PASEP Validation**

### 📞 Communication Validation

[](#-communication-validation)

- ✅ **Phone Number Validation** - DDD identification, phone format validation, and state lookup
- ✅ **Email Validation** - Brazilian email format validation with provider detection

### 📍 Location & Address

[](#-location--address)

- ✅ **CEP Validation** - With or without external API consultation (ViaCEP)
- ✅ **DDD Information** - State and city lookup from DDD codes
- ✅ **State Identification** - From CPF/CNPJ first two digits

### 👤 Personal Information

[](#-personal-information)

- ✅ **Full Name Validation** - No numbers or invalid characters, Brazilian name detection
- ✅ **Birth Date Validation** - No future dates or people over 130 years old, age calculation

### 🛠️ Utility Functions

[](#️-utility-functions)

- ✅ **Mask Application** - Apply and remove masks (e.g., 000.000.000-00, (11) 99999-9999)
- ✅ **Input Sanitization** - Remove spaces and invalid special characters
- ✅ **Reverse Formatting** - Transform "(11) 91234-5678" to "11912345678"

---

📦 Installation
--------------

[](#-installation)

### Node.js (npm)

[](#nodejs-npm)

```
npm install validbr
```

📦 **[View on npm](https://www.npmjs.com/package/validbr)**

### Python (pip)

[](#python-pip)

```
pip install validbr
```

📦 **[View on PyPI](https://pypi.org/project/validbr/)**

### PHP (Composer)

[](#php-composer)

```
composer require validbr/validbr
```

📦 **[View on Packagist](https://packagist.org/packages/validbr/validbr)**

---

🚀 Quick Start
-------------

[](#-quick-start)

### Node.js

[](#nodejs)

```
const ValidBR = require('validbr');

// CPF validation
console.log(ValidBR.cpf.isValid('123.456.789-09')); // true
console.log(ValidBR.cpf.generate()); // Generate valid CPF
console.log(ValidBR.cpf.getState('12345678909')); // 'São Paulo'

// CNH validation
console.log(ValidBR.cnh.isValid('02650306461')); // true
console.log(ValidBR.cnh.generate()); // Generate valid CNH

// Voter ID validation
console.log(ValidBR.tituloEleitor.isValid('123456789012')); // true
console.log(ValidBR.tituloEleitor.generate()); // Generate valid Voter ID

// PIS validation
console.log(ValidBR.pis.isValid('123.45678.90-1')); // true
console.log(ValidBR.pis.generate()); // Generate valid PIS

// Phone validation
console.log(ValidBR.phone.isValid('(11) 91234-5678')); // true
console.log(ValidBR.phone.getState('11')); // 'São Paulo'

// Apply mask
console.log(ValidBR.cpf.applyMask('12345678909')); // '123.456.789-09'
console.log(ValidBR.phone.applyMask('11912345678')); // '(11) 91234-5678'
```

### Python

[](#python)

```
from validbr import validbr

# CPF validation
print(validbr.cpf.is_valid('123.456.789-09'))  # True
print(validbr.cpf.generate())  # Generate valid CPF
print(validbr.cpf.get_state('12345678909')); // 'São Paulo'

# CNH validation
print(validbr.cnh.is_valid('02650306461')) # True
print(validbr.cnh.generate()) # Generate valid CNH

# Voter ID validation
print(validbr.titulo_eleitor.is_valid('123456789012')) # True
print(validbr.titulo_eleitor.generate()) # Generate valid Voter ID

# PIS validation
print(validbr.pis.is_valid('123.45678.90-1')) # True
print(validbr.pis.generate()) # Generate valid PIS

# Phone validation
print(validbr.phone.is_valid('(11) 91234-5678'));  # True
print(validbr.phone.get_state('11'));  # 'São Paulo'

# Apply mask
print(validbr.cpf.apply_mask('12345678909'));  # '123.456.789-09'
print(validbr.phone.apply_mask('11912345678'));  # '(11) 91234-5678'
```

### PHP

[](#php)

```
use ValidBR\ValidBR;

// CPF validation
echo ValidBR::cpf()->isValid('123.456.789-09') ? 'true' : 'false'; // true
echo ValidBR::cpf()->generate(); // Generate valid CPF
echo ValidBR::cpf()->getState('12345678909'); // 'São Paulo'

// CNH validation
echo ValidBR::cnh()->isValid('02650306461') ? 'true' : 'false'; // true
echo ValidBR::cnh()->generate(); // Generate valid CNH

// Voter ID validation
echo ValidBR::tituloEleitor()->isValid('123456789012') ? 'true' : 'false'; // true
echo ValidBR::tituloEleitor()->generate(); // Generate valid Voter ID

// PIS validation
echo ValidBR::pis()->isValid('123.45678.90-1') ? 'true' : 'false'; // true
echo ValidBR::pis()->generate(); // Generate valid PIS

// Phone validation
echo ValidBR::phone()->isValid('(11) 91234-5678') ? 'true' : 'false'; // true
echo ValidBR::phone()->getState('11'); // 'São Paulo'

// Apply mask
echo ValidBR::cpf()->applyMask('12345678909'); // '123.456.789-09'
echo ValidBR::phone()->applyMask('11912345678'); // '(11) 91234-5678'
```

---

📚 Documentation
---------------

[](#-documentation)

### CPF Validation

[](#cpf-validation)

```
// Node.js
ValidBR.cpf.isValid('123.456.789-09');        // true/false
ValidBR.cpf.generate();                        // Generate valid CPF
ValidBR.cpf.applyMask('12345678909');         // '123.456.789-09'
ValidBR.cpf.removeMask('123.456.789-09');     // '12345678909'
ValidBR.cpf.getState('12345678909');          // 'São Paulo'
```

### CNPJ Validation

[](#cnpj-validation)

```
// Node.js
ValidBR.cnpj.isValid('12.345.678/0001-95');   // true/false
ValidBR.cnpj.generate();                       // Generate valid CNPJ
ValidBR.cnpj.applyMask('12345678000195');     // '12.345.678/0001-95'
ValidBR.cnpj.removeMask('12.345.678/0001-95'); // '12345678000195'
ValidBR.cnpj.getState('12345678000195');      // 'São Paulo'
```

### Phone Validation

[](#phone-validation)

```
// Node.js
ValidBR.phone.isValid('(11) 91234-5678');     // true/false
ValidBR.phone.getDDD('(11) 91234-5678');      // '11'
ValidBR.phone.getState('11');                 // 'São Paulo'
ValidBR.phone.applyMask('11912345678');       // '(11) 91234-5678'
ValidBR.phone.removeMask('(11) 91234-5678');  // '11912345678'
ValidBR.phone.getValidDDDs();                 // Array of valid DDDs
```

### Email Validation

[](#email-validation)

```
// Node.js
ValidBR.email.isValid('user@example.com');    // true/false
ValidBR.email.sanitize(' user@example.com '); // 'user@example.com'
ValidBR.email.getDomain('user@example.com');  // 'example.com'
ValidBR.email.getUsername('user@example.com'); // 'user'
ValidBR.email.isBrazilianProvider('user@uol.com.br'); // true
```

### Name Validation

[](#name-validation)

```
// Node.js
ValidBR.fullName.isValid('João Silva Santos');    // true/false
ValidBR.fullName.sanitize('João Silva Santos  '); // 'João Silva Santos'
ValidBR.fullName.getFirstName('João Silva Santos'); // 'João'
ValidBR.fullName.getLastName('João Silva Santos');  // 'Santos'
ValidBR.fullName.getInitials('João Silva Santos');  // 'JSS'
ValidBR.fullName.hasCommonBrazilianName('João');   // true
```

### Birth Date Validation

[](#birth-date-validation)

```
// Node.js
ValidBR.birthDate.isValid('1990-05-15');      // true/false
ValidBR.birthDate.getAge('1990-05-15');       // Current age
ValidBR.birthDate.isAdult('1990-05-15');      // true/false
ValidBR.birthDate.isElderly('1940-05-15');    // true/false
ValidBR.birthDate.isMinor('2010-05-15');      // true/false
ValidBR.birthDate.format('1990-05-15', 'DD/MM/YYYY'); // '15/05/1990'
ValidBR.birthDate.getZodiacSign('1990-05-15'); // 'Touro'
```

### CEP Validation

[](#cep-validation)

```
// Node.js
ValidBR.cep.isValid('01234-567');             // true/false
ValidBR.cep.getInfo('01234-567');             // Get address info (async)
ValidBR.cep.applyMask('01234567');            // '01234-567'
ValidBR.cep.removeMask('01234-567');          // '01234567'
ValidBR.cep.getState('01234567');             // 'São Paulo'
ValidBR.cep.isFromSaoPaulo('01234567');       // true/false
ValidBR.cep.getRegion('01234567');            // 'Sudeste'
```

### RG Validation

[](#rg-validation)

```
// Node.js
ValidBR.rg.isValid('12.345.678-9', 'SP');     // true/false (state required)
ValidBR.rg.applyMask('123456789');            // '12.345.678-9'
ValidBR.rg.removeMask('12.345.678-9');        // '123456789'
ValidBR.rg.generate('SP');                    // Generate valid RG for SP
ValidBR.rg.getValidStates();                  // Array of supported states
```

### State Registration (IE) Validation

[](#state-registration-ie-validation)

```
// Node.js
ValidBR.ie.isValid('123.456.789', 'SP');      // true/false
ValidBR.ie.applyMask('123.456.789', 'SP');      // '123.456.789'
ValidBR.ie.removeMask('123.456.789');         // '123456789'
ValidBR.ie.generate('SP');                    // Generate valid IE for SP
ValidBR.ie.getValidStates();                  // Array of supported states
```

### CNH Validation

[](#cnh-validation)

```
// Node.js
ValidBR.cnh.isValid('02650306461'); // true/false
ValidBR.cnh.generate(); // Generate valid CNH
ValidBR.cnh.applyMask('02650306461'); // '02650306461'
ValidBR.cnh.removeMask('02650306461'); // '02650306461'
```

### Voter ID (Título de Eleitor) Validation

[](#voter-id-título-de-eleitor-validation)

```
// Node.js
ValidBR.tituloEleitor.isValid('123456789012'); // true/false
ValidBR.tituloEleitor.generate(); // Generate valid Voter ID
ValidBR.tituloEleitor.applyMask('123456789012'); // '1234 5678 9012'
ValidBR.tituloEleitor.removeMask('1234 5678 9012'); // '123456789012'
```

### PIS/NIS/NIT/PASEP Validation

[](#pisnisnitpasep-validation)

```
// Node.js
ValidBR.pis.isValid('123.45678.90-1'); // true/false
ValidBR.pis.generate(); // Generate valid PIS
ValidBR.pis.applyMask('12345678901'); // '123.45678.90-1'
ValidBR.pis.removeMask('123.45678.90-1'); // '12345678901'
```

### Utility Functions

[](#utility-functions)

```
// Node.js
ValidBR.sanitize('  test@example.com  ');     // 'test@example.com'
ValidBR.removeNonNumeric('abc123def456');     // '123456'
ValidBR.removeNonAlphabetic('João123Silva');  // 'JoãoSilva'
```

---

🧪 Testing
---------

[](#-testing)

### Run All Tests with Docker

[](#run-all-tests-with-docker)

```
# Navigate to docker directory
cd docker

# Run all tests
docker-compose up --build

# Run tests for specific language
docker-compose run nodejs npm test
docker-compose run python python -m pytest
docker-compose run php composer test
```

### Run Tests Individually

[](#run-tests-individually)

```
# Node.js
cd nodejs
npm install
npm test

# Python
cd python
pip install -e .
python -m pytest

# PHP
cd php
composer install
composer test
```

### Test Coverage

[](#test-coverage)

```
# Node.js
npm run test:coverage

# Python
python -m pytest --cov=validbr

# PHP
composer test:coverage
```

---

🎯 Browser Testing
-----------------

[](#-browser-testing)

Open `demo.html` in your browser to test all ValidBR features interactively. The demo includes:

- Real-time validation for all document types
- Mask application and removal
- State and region identification
- Age calculation and zodiac signs
- CEP information lookup
- Input sanitization examples

---

🤝 Contributing
--------------

[](#-contributing)

We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:

- Code of Conduct
- How to report bugs
- How to suggest features
- How to submit pull requests
- Development setup

### Development Setup

[](#development-setup)

1. Fork the repository
2. Clone your fork
3. Create a feature branch
4. Make your changes
5. Add tests for new functionality
6. Run all tests: `docker-compose up --build`
7. Submit a pull request

### Quick Links

[](#quick-links)

- 📋 **[Contributing Guide](CONTRIBUTING.md)**
- 🐛 **[Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md)**
- 💡 **[Feature Request Template](.github/ISSUE_TEMPLATE/feature_request.md)**
- 🔄 **[Pull Request Template](.github/pull_request_template.md)**

---

📄 License
---------

[](#-license)

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

🆘 Support
---------

[](#-support)

- 📧 **Email**:
- 🐛 **Issues**: [GitHub Issues](https://github.com/validbr/validbr/issues)
- 📖 **Documentation**:
- 💬 **Discussions**: [GitHub Discussions](https://github.com/validbr/validbr/discussions)
- 📱 **Discord**: [Join our community](https://discord.gg/validbr)

---

📈 Changelog
-----------

[](#-changelog)

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

---

🌟 Star History
--------------

[](#-star-history)

[![Star History Chart](https://camo.githubusercontent.com/dc87c0d2e3947c9d10f141a9b14e9c09d31468f0d0e85978fecda83ff5deb461/68747470733a2f2f6170692e737461722d686973746f72792e636f6d2f7376673f7265706f733d76616c696462722f76616c6964627226747970653d44617465)](https://star-history.com/#validbr/validbr&Date)

---

📊 Statistics
------------

[](#-statistics)

[![GitHub stars](https://camo.githubusercontent.com/db56031067022702dc3f6f7de455064179b50fe67ea5745fd487b7d4b44bd68a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f76616c696462722f76616c69646272)](https://camo.githubusercontent.com/db56031067022702dc3f6f7de455064179b50fe67ea5745fd487b7d4b44bd68a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f76616c696462722f76616c69646272)[![GitHub forks](https://camo.githubusercontent.com/594385917811e8ec68e1ae7d6c45b77113bb84e76e5bf4ff7d56a40e3b3da3a4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f76616c696462722f76616c69646272)](https://camo.githubusercontent.com/594385917811e8ec68e1ae7d6c45b77113bb84e76e5bf4ff7d56a40e3b3da3a4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f76616c696462722f76616c69646272)[![GitHub issues](https://camo.githubusercontent.com/0d73dfce18b67b58199c5bfb1111400f963f75c68d79fccbfcebd84f83f182f2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f76616c696462722f76616c69646272)](https://camo.githubusercontent.com/0d73dfce18b67b58199c5bfb1111400f963f75c68d79fccbfcebd84f83f182f2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f76616c696462722f76616c69646272)[![GitHub pull requests](https://camo.githubusercontent.com/6be4c6432c9422a0fe5e4105867863181557f029aeea97248cdcae2d0d5d8170/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732d70722f76616c696462722f76616c69646272)](https://camo.githubusercontent.com/6be4c6432c9422a0fe5e4105867863181557f029aeea97248cdcae2d0d5d8170/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732d70722f76616c696462722f76616c69646272)

---

🚀 Publishing
------------

[](#-publishing)

For information on how to publish ValidBR to package repositories, see the [Publishing Guide](PUBLISH_GUIDE.md).

### Publication Status

[](#publication-status)

- **NPM**: Ready for publication
- **PyPI**: Ready for publication
- **Packagist**: Ready for publication

### Publishing Commands

[](#publishing-commands)

#### Using Automation Script (Recommended)

[](#using-automation-script-recommended)

```
# Run all tests
./publish.sh test

# Publish to NPM
./publish.sh npm

# Publish to PyPI
./publish.sh pypi

# Check Packagist configuration
./publish.sh packagist

# Complete process (tests + publishing)
./publish.sh all
```

#### Manual Commands

[](#manual-commands)

```
# NPM
cd nodejs && npm publish

# PyPI
cd python && python setup.py sdist bdist_wheel && twine upload dist/*

# Packagist
# Connect Git repository to Packagist.org
```

---

### 🇧🇷 Versão em Português

[](#-versão-em-português)

---

📖 Visão Geral
-------------

[](#-visão-geral)

**ValidBR** é uma biblioteca abrangente de validação brasileira disponível para **Node.js**, **Python** e **PHP**. Ela fornece validação robusta para documentos brasileiros, números de telefone, endereços e informações pessoais com recursos avançados como aplicação de máscaras, identificação de estado e sanitização de dados.

### 🎯 O que o ValidBR Valida

[](#-o-que-o-validbr-valida)

- **📄 Documentos**: CPF, CNPJ, RG, IE (Inscrição Estadual), CNH, Título de Eleitor, PIS/NIS/NIT/PASEP
- **📞 Comunicação**: Números de telefone, Endereços de email
- **📍 Localização**: CEP, Códigos DDD, Identificação de estado
- **👤 Pessoal**: Nomes completos, Datas de nascimento
- **🛠️ Utilitários**: Aplicação/remoção de máscaras, Sanitização de dados

---

✨ Funcionalidades
-----------------

[](#-funcionalidades)

### 🔐 Validação de Documentos

[](#-validação-de-documentos)

- ✅ **Validação CPF/CNPJ** - Validação completa com dígitos verificadores e identificação de estado
- ✅ **Validação RG** - Incluindo dígitos verificadores para estados suportados
- ✅ **Validação IE (Inscrição Estadual)** - Por UF com algoritmos específicos de cada estado
- ✅ **Validação CNH** - Carteira Nacional de Habilitação
- ✅ **Validação Título de Eleitor**
- ✅ **Validação PIS/NIS/NIT/PASEP**

### 📞 Validação de Comunicação

[](#-validação-de-comunicação)

- ✅ **Validação de Telefone** - Identificação de DDD, validação de formato e busca de estado
- ✅ **Validação de Email** - Validação de formato brasileiro com detecção de provedor

### 📍 Localização e Endereço

[](#-localização-e-endereço)

- ✅ **Validação de CEP** - Com ou sem consulta à API externa (ViaCEP)
- ✅ **Informações de DDD** - Busca de estado e cidade a partir de códigos DDD
- ✅ **Identificação de Estado** - A partir dos dois primeiros dígitos do CPF/CNPJ

### 👤 Informações Pessoais

[](#-informações-pessoais)

- ✅ **Validação de Nome Completo** - Sem números ou caracteres inválidos, detecção de nomes brasileiros
- ✅ **Validação de Data de Nascimento** - Sem datas futuras ou pessoas com mais de 130 anos, cálculo de idade

### 🛠️ Funções Utilitárias

[](#️-funções-utilitárias)

- ✅ **Aplicação de Máscaras** - Aplicar e remover máscaras (ex: 000.000.000-00, (11) 99999-9999)
- ✅ **Sanitização de Entrada** - Remover espaços e caracteres especiais inválidos
- ✅ **Formatação Reversa** - Transformar "(11) 91234-5678" em "11912345678"

---

📦 Instalação
------------

[](#-instalação)

### Node.js (npm)

[](#nodejs-npm-1)

```
npm install validbr
```

📦 **[Ver no npm](https://www.npmjs.com/package/validbr)**

### Python (pip)

[](#python-pip-1)

```
pip install validbr
```

📦 **[Ver no PyPI](https://pypi.org/project/validbr/)**

### PHP (Composer)

[](#php-composer-1)

```
composer require validbr/validbr
```

📦 **[Ver no Packagist](https://packagist.org/packages/validbr/validbr)**

---

🚀 Início Rápido
---------------

[](#-início-rápido)

### Node.js

[](#nodejs-1)

```
const ValidBR = require('validbr');

// Validação de CPF
console.log(ValidBR.cpf.isValid('123.456.789-09')); // true
console.log(ValidBR.cpf.generate()); // Gerar CPF válido
console.log(ValidBR.cpf.getState('12345678909')); // 'São Paulo'

// Validação de telefone
console.log(ValidBR.phone.isValid('(11) 91234-5678')); // true
console.log(ValidBR.phone.getState('11')); // 'São Paulo'

// Aplicar máscara
console.log(ValidBR.cpf.applyMask('12345678909')); // '123.456.789-09'
console.log(ValidBR.phone.applyMask('11912345678')); // '(11) 91234-5678'
```

### Python

[](#python-1)

```
from validbr import ValidBR

# Validação de CPF
print(ValidBR.cpf.is_valid('123.456.789-09'))  # True
print(ValidBR.cpf.generate())  # Gerar CPF válido
print(ValidBR.cpf.get_state('12345678909')); // 'São Paulo'

# Validação de telefone
print(ValidBR.phone.is_valid('(11) 91234-5678')); // true
print(ValidBR.phone.get_state('11')); // 'São Paulo'

# Aplicar máscara
print(ValidBR.cpf.apply_mask('12345678909')); // '123.456.789-09'
print(ValidBR.phone.apply_mask('11912345678')); // '(11) 91234-5678'
```

### PHP

[](#php-1)

```
use ValidBR\ValidBR;

// Validação de CPF
echo ValidBR::cpf()->isValid('123.456.789-09') ? 'true' : 'false'; // true
echo ValidBR::cpf()->generate(); // Gerar CPF válido
echo ValidBR::cpf()->getState('12345678909'); // 'São Paulo'

// Validação de telefone
echo ValidBR::phone()->isValid('(11) 91234-5678') ? 'true' : 'false'; // true
echo ValidBR::phone()->getState('11'); // 'São Paulo'

# Aplicar máscara
echo ValidBR::cpf()->applyMask('12345678909'); // '123.456.789-09'
echo ValidBR::phone()->applyMask('11912345678'); // '(11) 91234-5678'
```

---

🤝 Como Contribuir
-----------------

[](#-como-contribuir)

Aceitamos contribuições! Por favor, leia nosso [Guia de Contribuição](CONTRIBUTING.md) para detalhes sobre:

- Código de Conduta
- Como reportar bugs
- Como sugerir funcionalidades
- Como enviar pull requests
- Configuração de desenvolvimento

### Configuração de Desenvolvimento

[](#configuração-de-desenvolvimento)

1. Faça um fork do repositório
2. Clone seu fork
3. Crie uma branch para sua funcionalidade
4. Faça suas alterações
5. Adicione testes para nova funcionalidade
6. Execute todos os testes: `docker-compose up --build`
7. Envie um pull request

### Links Rápidos

[](#links-rápidos)

- 📋 **[Guia de Contribuição](CONTRIBUTING.md)**
- 🐛 **[Template de Bug Report](.github/ISSUE_TEMPLATE/bug_report.md)**
- 💡 **[Template de Feature Request](.github/ISSUE_TEMPLATE/feature_request.md)**
- 🔄 **[Template de Pull Request](.github/pull_request_template.md)**

---

🆘 Suporte
---------

[](#-suporte)

- 📧 **Email**:
- 🐛 **Issues**: [GitHub Issues](https://github.com/validbr/validbr/issues)
- 📖 **Documentação**:
- 💬 **Discussões**: [GitHub Discussions](https://github.com/validbr/validbr/discussions)
- 📱 **Discord**: [Entre em nossa comunidade](https://discord.gg/validbr)

---

### ⭐ Se este projeto te ajudou, considere dar uma estrela!

[](#-se-este-projeto-te-ajudou-considere-dar-uma-estrela)

 [ ![GitHub stars](https://camo.githubusercontent.com/361b417421776ed5b4fcb466d8c0ceae3d54c6ef0f3e078a293bfa3d62e44da6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f76616c696462722f76616c696462723f7374796c653d736f6369616c) ](https://github.com/validbr/validbr/stargazers) [ ![GitHub forks](https://camo.githubusercontent.com/b549ddc686fa45ec0f2a417de1ead00b931e47d53160726c8fd43a025bb93710/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f76616c696462722f76616c696462723f7374796c653d736f6369616c) ](https://github.com/validbr/validbr/network)

###  Health Score

21

—

LowBetter than 18% of packages

Maintenance50

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity23

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/c9f8ea6e0acea76a84c6f831eec9565c0e7a53ad03d6ea33c9c8549ad3794f17?d=identicon)[julioamorimdev](/maintainers/julioamorimdev)

---

Top Contributors

[![julioamorimdev](https://avatars.githubusercontent.com/u/98892057?v=4)](https://github.com/julioamorimdev "julioamorimdev (14 commits)")

### Embed Badge

![Health badge](/badges/validbr-validbr/health.svg)

```
[![Health](https://phpackages.com/badges/validbr-validbr/health.svg)](https://phpackages.com/packages/validbr-validbr)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)