Aplicando Máscaras em Dados no PHP

Bruno Oliveira — Fri, 07 Mar 2025 19:07:29 +0000

Durante o desenvolvimento de sistemas, é comum a necessidade de formatar dados para exibição, como CPF, CNPJ e CEP. A boa prática recomenda armazenar esses dados no banco em seu formato “puro”, sem caracteres de formatação, garantindo maior flexibilidade e integridade.

Entretanto, na apresentação de relatórios, notas fiscais ou telas de exibição, a formatação adequada desses dados melhora a legibilidade e a experiência do usuário. Para isso, podemos criar uma solução genérica e reutilizável no PHP.

Criando um Helper para Máscaras

Vamos implementar uma classe MaskHelper que permitirá aplicar máscaras de forma dinâmica aos dados.

<?php

namespace App\Helpers;

final class MaskHelper
{
    private const MASK_CHAR = '#';

    public static function mask(string $value, string $format): string
    {
        $cleanValue = self::clean($value);
        if ($cleanValue === '' || $format === '') {
            return $value;
        }

        $masked = '';
        $index = 0;

        foreach (str_split($format) as $char) {
            $masked .= ($char === self::MASK_CHAR && isset($cleanValue[$index]))
                ? $cleanValue[$index++]
                : $char;
        }

        return $masked;
    }

    public static function cpf(string $value): string
    {
        return self::mask($value, '###.###.###-##');
    }

    public static function cnpj(string $value): string
    {
        return self::mask($value, '##.###.###/####-##');
    }

    public static function cpfCnpj(string $value): string
    {
        return match (strlen(self::clean($value))) {
            11 => self::cpf($value),
            14 => self::cnpj($value),
            default => $value,
        };
    }

    private static function clean(string $value): string
    {
        return preg_replace('/\D/', '', $value) ?? '';
    }
}

Como Utilizar a Classe

A implementação acima permite aplicar máscaras facilmente aos dados, tornando a formatação mais flexível e reutilizável em toda a aplicação. Veja alguns exemplos de uso:

<php

use App\Helpers\MaskHelper;

$cpf = '12345678900';
echo MaskHelper::cpf($cpf); // Saída: 123.456.789-00

$cnpj = '12345678098700';
echo MaskHelper::cnpj($cnpj); // Saída: 12.345.678/0987-00

$documento = '12345678900';
echo MaskHelper::cpfCnpj($documento); // Detecta e aplica a máscara correta

$cep = '1234567';
echo MaskHelper::mask($cep, '##.###-##'); // Saída: 12.345-67

Conclusão

A classe MaskHelper permite padronizar e reutilizar a formatação de dados em um sistema PHP, melhorando a manutenção do código e a experiência do usuário. Esse tipo de abordagem é útil para exibição de dados em relatórios, telas de administração e formulários.

Caso precise de outras máscaras, basta chamar o método mask() com o formato desejado, tornando a solução altamente flexível!

DEV Community: Bruno Oliveira

Aplicando Máscaras em Dados no PHP

Criando um Helper para Máscaras

Como Utilizar a Classe

Conclusão