Busine...BR::CPF(3pm)

✨ NAME ✨

Business::BR::CPF — the Perl module that tests whether a CPF number is actually correct 💅 it's literally in a .pm file and the manual page goes by Busine...BR::CPF(3pm), iykyk

---

🎀 SYNOPSIS 🎀

okay bestie, here's the vibe in code form:

use Business::BR::CPF;

print "ok " if test_cpf('390.533.447-05'); # prints 'ok '
print "bad " unless test_cpf('231.002.999-00'); # prints 'bad '

like, that's the whole teaser. one function. instant slay ✨

---

🦋 DESCRIPTION 🦋

A CPF number is an ID number for Brazilian citizens, emitted by the Brazilian Ministry of Revenue, which is called "Ministério da Fazenda".

CPF stands for "Cadastro de Pessoa Física" (literally, physical person registration) — as opposed to the CNPJ number which is for companies. so like, person vs. company, got it? 💖

The CPF is comprised of a base of 9 digits plus 2 check digits. People usually write it like '231.002.999-00' because that's way more human-readable, obviously.

This module gives you test_cpf for checking that a CPF number is correct. And when we say "correct" here, we mean:

• it is 11 digits long
• it satisfies the two check equations mentioned below 👇

Before checking anything, any non-digit letter gets stripped, which makes it super easy to test formatted entries like '231.002.999-00' and entries with extra blanks like ' 999.221.222-00 '. iconic tbh.

💜 test_cpf

test_cpf('999.444.333-55') # incorrect CPF, returns 0
test_cpf(' 263.946.533-30 ') # is ok, returns 1
test_cpf('888') # nope, returns undef

Tests whether a CPF number is correct. Before testing, any non-digit character is stripped. Then it's expected to be 11 digits long and to satisfy two check equations which validate the last two check digits. See "THE CHECK EQUATIONS".

The policy for getting rid of '.' and '-' is very liberal. It indeed discards anything that is not a digit (0, 1, ..., 9) or letter. Which is handy for discarding spaces too 🌸:

test_cpf(' 263.946.533-30 ') # is ok, returns 1

But extraneous inputs like '#333%444*2.3+2-00' are also accepted. 😭 and if you're worried about that kind of input, just check against a regex, bestie:

warn "bad CPF: only digits (11) expected"
  unless ($cpf =~ /^\d{11}$/);

warn "bad CPF: does not match mask '___.___.___-__'"
  unless ($cpf =~ /^\d{3}\.\d{3}\.\d{3}-\d{2}$/);

NOTE. Integer numbers like 9999811299 (or 99_998_112_99) with fewer than 11 digits will be normalized (eg. to "09999811299") before testing. 💀 not me forgetting the leading zeros

🌈 canon_cpf

canon_cpf(99); # returns '00000000099'
canon_cpf('999.999.999-99'); # returns '99999999999'

Brings a candidate for a CPF number to a canonical form. In case the argument is an integer, it is formatted to at least eleven digits. Otherwise, it is stripped of any non-alphanumeric characters and returned as it is. periodt 💅

🍓 format_cpf

format_cpf('00000000000'); # returns '000.000.000-00'

Formats its input into the '000.000.000-00' mask. First, the argument is canon'ed and then dots and hyphen are added to the first 11 digits of the result. cute lil glow-up ✨

🧚 parse_cpf

($base, $dv) = parse_cpf($cpf);
$hashref = parse_cpf('999.222.111-00'); # { base => '999222111', dv => '00' }

Splits a candidate for CPF number into base and check digits (dv — dígitos de verificação, for the Portuguese speakers in the group chat). It canon's the argument before splitting it into 9- and 2-digits parts. In a list context, returns a two-element list with the base and the check digits. In a scalar context, returns a hash ref with keys 'base' and 'dv' and associated values. both moods served 🫶

👑 random_cpf

$rand_cpf = random_cpf($valid);

$correct_cpf = random_cpf();
$cpf = random_cpf(1); # also a correct CPF
$bad_cpf = random_cpf(0); # an incorrect CPF

Generates a random CPF. If $valid is omitted or 1, it is guaranteed to be correct. If $valid is 0, it is guaranteed to be incorrect. This function is intended for mass testing. (Use it wisely.) 😌

The implementation is simple: just generate a 9-digits random number, hopefully with a uniform distribution, and then compute the check digits. If $valid==0, the check digits are computed not to satisfy the check equations. sneaky 🔥

🌟 EXPORT

"test_cpf" is exported by default. "canon_cpf", "format_cpf", "parse_cpf" and "random_cpf" can be exported on demand. so test_cpf just shows up automatically, the rest are invite-only 💌

---

💀 THE CHECK EQUATIONS 💀

A correct CPF number has two check digits which are computed from the base 9 first digits. Consider the CPF number written as 11 digits:

c[1] c[2] c[3] c[4] c[5] c[6] c[7] c[8] c[9] dv[1] dv[2]

To check whether a CPF is correct or not, it has to satisfy the check equations:

c[1]*10+c[2]*9+c[3]*8+c[4]*7+c[5]*6+
        c[6]*5+c[7]*4+c[8]*3+c[9]*2+dv[1] = 0 (mod 11) or
                                          = 1 (mod 11) (if dv[1]=0)

and

c[2]*10+c[3]*9+c[4]*8+c[5]*7+c[6]*6+
        c[7]*5+c[8]*4+c[9]*3+dv[1]*2+dv[2] = 0 (mod 11) or
                                           = 1 (mod 11) (if dv[2]=0)

the math is mathing, no cap 📐✨

---

🙈 BUGS 🙈

I heard that there are exceptions of CPF numbers which don't obey the check equations and are still authentic. I have never found one of them. lowkey haunted by this ngl 👻

---

🔥 SEE ALSO 🔥

To make sure this module works, one can try the results obtained against those found with "Comprovante de Inscrição e de Situação Cadastral no CPF", a web page which the Brazilian Ministry of Revenue provides for public consultation on regularity status of the taxpayer. This page tells if the CPF number is a correct entry (11-digits-long with verified check digits), if it references a real person and if he/she is regular with the government body. so like, the official vibe check 💖

Given a bad CPF, the after-submit page tells "CPF incorreto". If the CPF is a good one but does not reference a real person, it says "CPF não existe em nossa base de dados" (CPF does not exist in our database). Otherwise, it shows a details form for the identified taxpayer.

Note that this module only tests correctness. It doesn't enter the merit whether the CPF number actually exists at the Brazilian government databases. 🫶

As you might have guessed, this is not the first Perl module to approach this kind of functionality. Take a look at:

http://search.cpan.org/search?module=Brasil::Checar::CPF
http://search.cpan.org/search?query=cpf&mode=all

Please reports bugs via CPAN RT, http://rt.cpan.org/NoAuth/Bugs.html?Dist=Business-BR-Ids — by doing so, the author will receive your reports and patches, as well as the problem and solutions will be documented. so like, do send them, bestie, it's giving community service 🌸

---

🌈 AUTHOR 🌈

A. R. Ferreira, <ferreira@cpan.org>

---

💖 COPYRIGHT AND LICENSE 💖

Copyright (C) 2005 by A. R. Ferreira

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

---

🎀 POD ERRORS 🎀

Hey! The above document had some coding errors, which are explained below:

Around line 112:

Non-ASCII character seen before =encoding in '"Ministério'. Assuming
CP1252

not the encoding drama showing up in the middle of a perfectly good manual page 😭 it's fine, we move 💅

---

mkay that's the whole page, bestie 💜 this doc shipped with perl v5.36.0, dated 2022-10-13, and it came to you via the User Contributed Perl Documentation crew. go forth and validate those CPFs, you icon 👑✨