Carbon para PHP: guia completo com exemplos

O que é Carbon e para que serve?

Carbon é uma biblioteca poderosa e elegante para PHP que estende a classe nativa DateTime. Se você já trabalhou com datas em PHP nativamente, sabe que o DateTime e DateTimeImmutable padrão fornecem funcionalidades básicas, mas sua API é frequentemente verbosa e pouco intuitiva. Carbon resolve esse problema oferecendo uma sintaxe limpa, legível e expressiva para trabalhar com datas e horas.

Por que usar Carbon? Imagine que você precisa:

\n
• Adicionar 3 dias à data atual: $date->add(new DateInterval('P3D')) (PHP nativo) vs $date->addDays(3) (Carbon).
\n
• Obter a diferença em dias entre duas datas: o verboso DateTime::diff() seguido de formatação vs $date1->diffInDays($date2).
\n
• Verificar se uma data é fim de semana: escrever sua própria lógica vs $date->isWeekend().
\n

Carbon torna o código não apenas mais curto, mas também significativamente mais claro. Ele é amplamente utilizado em frameworks PHP modernos, como Laravel (onde é o padrão), Symfony, Yii e outros. A biblioteca é totalmente compatível com o DateTime nativo, o que significa que você pode usar Carbon em qualquer lugar onde se espera um DateTime.

Principais vantagens do Carbon:

\n
• Sintaxe expressiva: métodos nomeados de forma que sua finalidade seja clara sem comentários (startOfDay(), endOfMonth(), isFuture()).
\n
• Imutabilidade (Immutable): suporte a CarbonImmutable para trabalhar com datas com segurança, sem efeitos colaterais.
\n
• Localização: suporte embutido para formatação de datas em diferentes idiomas.
\n
• API rica: centenas de métodos para manipulação, comparação, formatação e cálculo de datas.
\n
• Comparação intuitiva: métodos como isBefore(), isAfter(), isSameDay().
\n

Instalação do Carbon

O Carbon é instalado via Composer — o gerenciador de pacotes padrão para PHP. Se você ainda não tem o Composer, é necessário instalá-lo (veja getcomposer.org).

Abra o terminal na raiz do seu projeto e execute o comando:

composer require nesbot/carbon

Após a instalação bem-sucedida, uma pasta vendor/ e um arquivo composer.json com a dependência adicionada serão criados no seu projeto. Para usar o Carbon no seu código, é necessário incluir o autoloader do Composer:

<?php\nrequire_once 'vendor/autoload.php';\n\nuse Carbon\\Carbon;\n\n// Agora você pode usar o Carbon\necho Carbon::now(); // 2025-04-03 15:30:00\n?>

Importante: O Carbon requer PHP versão 8.0 ou superior (para as versões mais recentes). Recomenda-se usar PHP 8.1+.

Início rápido com exemplo de código

Vamos direto à prática. Aqui estão alguns exemplos simples que demonstram o poder do Carbon:

<?php\nrequire_once 'vendor/autoload.php';\nuse Carbon\\Carbon;\n\n// Data e hora atuais\n$now = Carbon::now();\necho "Agora: " . $now . "\\n"; // 2025-04-03 15:30:00\n\n// Criar data a partir de uma string\n$birthday = Carbon::createFromDate(1990, 5, 15);\necho "Aniversário: " . $birthday->format('d.m.Y') . "\\n"; // 15.05.1990\n\n// Manipulações com datas\n$tomorrow = Carbon::tomorrow();\necho "Amanhã: " . $tomorrow . "\\n";\n\n$nextWeek = Carbon::now()->addWeek();\necho "Daqui a uma semana: " . $nextWeek . "\\n";\n\n// Diferença entre datas\n$age = $birthday->diffInYears(Carbon::now());\necho "Idade: $age anos\\n"; // 34 ou 35\n\n// Verificação de condições\n$date = Carbon::parse('2025-12-25');\nif ($date->isChristmas()) {\n    echo "É Natal!\\n";\n}\n\n//