O que é o Carbon?

O Carbon é uma classe que herda diretamente da classe DateTime do PHP, mas o que isso quer dizer?

Quer dizer que numa instância (objeto) do Carbon você tem todos os métodos do DateTime e pode utilizar uma instância Carbon em qualquer local que seria necessário uma instância da classe DateTime.

Como utilizar o Carbon?

Laravel

Isso é bem simples caso você já esteja usando Laravel, basta adicionar o namespace do Carbon no arquivo PHP em que for utiliza-lo:

    use Carbon\Carbon;

Agora você já pode criar objetos Carbon:

    $now = new Carbon();

Sem Laravel

Bom, para evitar que esteja olhando esse post muito no futuro e o passo a passo para instalar o Carbon tenha mudado muito e você acabe se frustando achando que é uma coisa do outro mundo por estar seguindo passos desatualizados (isso já aconteceu com você também?), deixo aqui o link do “Getting Started” do Carbon para que o siga-o. Basta voltar aqui quando terminar 😉


Uma pausa no controle temporal

Você já deve estar ansioso para começar a controlar o tempo na sua aplicação, mas antes de começarmos a investir como fazer isso, primeiro preciso dizer que nada do que você vai ver aqui é diferente da documentação do Carbon. Se já vem acompanhando os meus posts de aprendizado já deve ter percebido que eu apenas gosto de deixar a documentação um pouco mais lúdica, mas que sempre deixo convites para que você se aprofunde na leitura da mesma. Para não fugir da regra aqui vai o link para a documentação. Divirta-se.


Invocando o controle temporal

Para começar a controlar o tempo, você precisa aprender as diversas formas de se instanciar um objeto Carbon, isso pode agilizar seu trabalho e tornar as coisas muito mais simples. Vamos analisar e explicar alguns truques que o Carbon reserva para essa finalidade:

Construtor e seus segredos

Como você deve ter percebido no exemplo a cima, ao construir um novo objeto sem nada sendo passado como parametro o Carbon por padrão te retorna a data e horário atual de acordo com a timezone de sua aplicação. Muito bom não é mesmo? Mas isso é apenas a ponta do iceberg. O construtor do Carbon pode, na verdade, ser usado de formas mais interessantes.

Imagine que na sua aplicação você precise pegar exatamente o último dia de Março de 2010. Como você faria isso? Se estiver usando o Carbon basta apenas construir o objeto da seguinte forma:

    new Carbon('last day of March 2010');

Você ainda pode usar algumas strings para fazer a mágica do construtor acontecer, o código a baixo resultará na data e hora atuais, assim como o construtor vazio retornaria:

    new Carbon('now');

Além disso podemos combinar strings como:

    new Carbon('last friday');

ou:

    new Carbon('next monday');

Segue uma pequena lista das palavras relevantes para serem usadas na construção com strings:

  • this
  • next
  • last
  • tomorrow
  • yesterday
  • +
  • first
  • last
  • ago

Você pode estar precisando criar uma instância com o tempo atual em outra timezone, que não a sua padrão do app. Para isso basta utilizar o método estático now():

    Carbon::now('America/Toronto');

Essa é nossa deixa para começarmos a falar dos métodos estáticos, que também retornam instâncias Carbon.

Métodos estáticos

Você está familiarizado com o now do exemplo a cima, mas o Carbon nos fornece mais do que apenas o método estático now() como instrumento para controle temporal. Além do método now() temos o método tomorrow()yesterday() e today(), os nomes são auto-explicativos.

Além disso o Carbon nos fornece o poderoso método estático createFromFormat(), este recebe como primeiro paramêtro a string que representa o formato que será utilizado pelo Carbon, o segundo a string do momento a ser utilizado (data e/ou horário) e por último a timezone desejada, essa opcional, segue:

    Carbon::createFromFormat('d/m/Y', '01/03/2010');

Para utilizarmos o createFromFormat() em toda sua glória nós precisamos traduzir o que cada caracter representa nos padrões do primeiro parâmetro do Carbon. Para isso criei essa pequena tabela para te ajudar, ela lista os caracteres mais utilizados e o que eles significam:

Caracter Significado
d representa o dia do mês, vai de 01 até 31
D representa o texto do dia em inglês: Mon, Thu, Wed
z representa o dia do ano, vai de 0 até 365
m representa o mês em forma de número, vai de 01 até 12
F representa o mês de forma textual em inglês, ex: January, April, December
y representa o ano em apenas dois números: 16, 02, 91.
Y representa o ano em quatro números: 2016, 2002, 1991.
h representa horas em forma de número, vai de 01 até 12
H representa horas em forma de números no modelo brasileiro, vai de 00 até 23
i representa minutos, vai de 00 até 59
s representa segundos, vai de 00 até 59

Além disso temos os métodos createFromDate() e o createFromTime() basicamente funcionam da seguinte forma:

    Carbon::createFromDate($ano, $mes, $dia, $timezone);
    Carbon::createFromTime($hora, $minuto, $segundo, $timezone);

Recuperando informações temporais

Muito bem! Você já aprendeu diversas formas de iniciar um objeto Carbon em sua aplicação, agora caso você já tenha um, como você pode trabalhar para retornar informações do mesmo? É o que vamos dar uma olhada agora.

Imagine que você queira saber o ano especifico do objeto Carbon que você está lidando, você iria fazer algo desse tipo:

    $now = new Carbon();
    $now->year;

Além do ano, você pode pegar propriedades como: monthdayhourminutesecond. Além desses, existem em todos os objetos Carbon propriedades mais inteligentes como:

  • dayOfWeek: retorna o dia da semana em forma de número 0 para domingo e 6 sábado
  • dayOfYear: retorna o dia do ano, a partir de 0.
  • weekOfMonth: retorna a semana do mês, a partir de 1.
  • daysInMonth: retorna a quantidade de dias no mês.
  • age: É útil para saber a idade de pessoas através da data fornecida.

O tempo para os olhos humanos

Para transformar seus objetos Carbon em strings a lógica é igual ao DateTime, contúdo agora que você já conhece nossa tabela apresentada la em cima de representações de caracteres e seus significados fica tudo mais fácil, correto?

Então podemos fazer algo como:

    $now = new Carbon();
    $now->format('l jS \\d\\e F Y h:i:s A');

Isso retornaria algo do tipo: "Sunday 8th de January 2017 02:27:57 PM" Veja que está tudo em inglês, com excessão do ‘de’ que escapamos do pattern. Agora como podemos deixar essa string em português?

É bem simples: setlocale (LC_TIME, 'pt_BR');

Contudo para utilizar as strings localizadas precisamos utilizar outro método o formatLocalized(). Agora para que possamos tirar proveito desse método é entender que ele utiliza o método strftime() do PHP por baixo dos panos. Logo você deve seguir o padrão para esse método ao formatar a string, deixo o link para que você estude um pouco a tabela de caracteres e seus significados.

Mas de qualquer sorte deixo aqui um exemplo de como funciona o método:

    $now = Carbon();
    $now->formatLocalized('%A %d de %B de %Y');

O retorno dele seria: "domingo 08 de janeiro de 2017"

Concluindo a primeira parte

Você já sabe o básico sobre o Carbon, agora você precisa aprender é como acrescentar, subtrair e comparar datas com ele. Como já aprendemos bastante nesse tópico nós iremos separar o conteúdo e falar sobre isso em um novo tópico. Em breve ele estará disponível aqui no blog.

Se tiver dúvidas ou correções você pode utilizar os comentários.

DEIXE UMA RESPOSTA

Please enter your comment!
Please enter your name here