cancio-labs / cpf-doctrine-type

2.0.0 2026-09-22 03:05 UTC

Requires

• php: >=8.5
• doctrine/dbal: ^4.4

Requires (Dev)

• phpunit/phpunit: ^13.3

GPL-3.0-or-later

• Nilo Soares
• Cancio Labs
• NSCPS Solutions

• doctrine
• type
• brazil
• cpf
• mapping type

Published on Packagist.org on 2026-09-22 03:08 UTC

README

A Doctrine DBAL custom mapping type for storing Brazilian CPF values as fixed-length strings.

The type stores values as 11 digits in a CHAR(11) column and exposes them as formatted PHP strings, such as 999.999.999-99. It does not depend on, create, or return a CPF value object.

Requirements

• PHP 8.5 or later
• Doctrine DBAL 4.4 or later

Installation

Install the package with Composer:

composer require cancio-labs/cpf-doctrine-type

Registering the type

Register the type during application bootstrap, before Doctrine creates metadata or connections that use it:

use CancioLabs\Doctrine\Type\Cpf\CpfType;
use Doctrine\DBAL\Types\Type;

Type::addType(CpfType::NAME, CpfType::class);

For Symfony applications, configure the type in config/packages/doctrine.yaml:

doctrine:
    dbal:
        types:
            cpf: CancioLabs\Doctrine\Type\Cpf\CpfType

Usage

Map CPF properties as nullable strings:

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Person
{
    #[ORM\Column(type: 'cpf', nullable: true)]
    private ?string $cpf = null;
}

The database representation is a fixed-length CHAR(11) string containing 11 digits. When writing a value, the type accepts null, a string, or a Stringable object. It removes periods and hyphens from formatted CPF input, then requires exactly 11 digits; all other values cause a Doctrine conversion exception. When reading a value, it returns the formatted 999.999.999-99 representation.

This package does not verify the CPF checksum. Validate that business rule in your application before persistence.

Testing

Install development dependencies, then run the test suite:

composer install
composer tests

Generate an HTML coverage report with Xdebug enabled:

composer coverage

The report is written to coverage/.

License

This project is licensed under the GNU General Public License v3.0 or later.

Contributing

Please use GitHub Issues to report bugs or propose enhancements, and submit changes through pull requests.