Como pesquisar por mês ou ano no Laravel?

Eu já ensinei aqui no blog como criar filtros de pesquisa no Laravel através de um intervalo de datas. Porém há outro caso muito comum, que é quando precisamos pesquisar através apenas do mês e ano de uma coluna.

Pesquisando dados por mês ou ano

No Laravel, você pode fazer uma filtro de pesquisa em um campo do tipo DATETIME ou TIMESTAMP facilmente. Você precisa apenas chamar o método whereYear para filtrar pelo ano ou whereMonth para filtrar pelo mês das datas registradas no seu banco de dados.

Veja como é simples:

class ProdutosController extends Controller
{
    function index(Request $request) 
    {
        $query = Produto::query();

        if ($request->has('ano')) {
            $query->whereYear('created_at', '=', $request->ano);
        }

        if ($request->has('mes')) {
            $query->whereMonth('created_at', '=', $request->mes);
        }

        return $query->paginate(); // ou $query->get() se quiser retornar tudo
    }
}

Para pesquisar por mês e ano, bastaria acessar o endpoint de produtos da seguinte forma:

/produtos?mes=2&ano=2021

Explicando o funcionamento de whereYear e WhereMonth no Laravel

O método whereYear modifica a SQL query, adicionando YEAR(created_at). Já whereMonth adiciona MONTH(created_at). O próprio SGBD cuidará de executar a pesquisa baseada no ano e mês passados.

Para testar como uma SQL é criada ao chamar o Query Builder do Laravel, eu costumo utilizar o toSql.

Veja:

echo Produto::whereYear('created_at', '=', 2021)->whereMonth('created_at', '=', 2)->toSql();

Isso irá gerar a saída:

select * from `produto` where year(`created_at`) = ? and month(`created_at`) = ?