Carregar imagens em uma API Laravel exige mais do que um simples campo de texto: precisa de tratamento de ficheiros, armazenamento organizado e validação de formato. Vais aprender como permitir upload de imagens no controlador de receitas, guardá las numa pasta pública e bloquear ficheiros que não cumpram o formato esperado.

Este fluxo é útil para qualquer programador que esteja a construir um CRUD com Laravel e queira adicionar uma camada extra de segurança ao processo administrativo.

Como permitir o upload de uma imagem no controlador?

O ponto de partida está no método de criação do recurso. Em vez de tratar a imagem como texto, tens de a tratar como ficheiro através da classe Request, que gere todo o pedido enviado pelo cliente.

No controlador, dentro do método que cria a receita, usas o método file para apanhar o campo de imagem e o método store para guardar o ficheiro numa pasta organizada. A estrutura básica fica assim:

php $receita->imagem = $request->file('imagem')->store('receitas', 'public'); $receita->update();

A pasta receitas será criada automaticamente dentro de app/public, que é onde o Laravel armazena ficheiros acessíveis publicamente. O método update garante que a alteração no registo é persistida.

Onde o Laravel guarda imagens com store? Por defeito, o método store coloca o ficheiro em storage/app/public dentro da subpasta que indicas. No exemplo, fica em storage/app/public/receitas.

Como testar o upload no Postman?

Para validar o endpoint, usas o Postman com uma requisição POST já autenticada. O detalhe importante está no campo da imagem: por defeito, o Postman aceita texto, mas precisas de mudar o tipo do campo.

• Posiciona te sobre o campo imagem no body do tipo form data.
• Clica no ícone que aparece e troca text por file.
• Seleciona o ficheiro do teu computador e clica em open.
• Envia a requisição e confirma que a rota da imagem é devolvida no resultado.

Depois de enviar, vais ver no projeto que a pasta foi criada e a imagem foi armazenada com um nome único gerado pelo Laravel [03:15].

Como validar que o ficheiro é uma imagem?

Aqui entra a camada de segurança. Sem validação, qualquer utilizador pode tentar carregar ficheiros que não são imagens, o que abre brechas no teu sistema. A solução está nas regras de validação dentro da classe Request.

No ficheiro de Request associado ao recurso, adicionas as regras ao campo imagem. A regra required obriga o envio e a regra image garante que o ficheiro é uma imagem válida. Podes ainda restringir formatos específicos:

php 'imagem' => 'required|image|mimes:png,jpg'

Se tentares enviar um PNG quando a regra exige apenas JPG, o Laravel devolve imediatamente um erro a indicar que o formato não é aceite. Ao corrigir para PNG ou ajustar a regra, o registo é criado com sucesso.

O que faz a regra image no Laravel? Verifica se o ficheiro carregado tem uma extensão válida de imagem como jpg, png, bmp, gif, svg ou webp. É a forma mais rápida de filtrar uploads inválidos.

Na documentação oficial do Laravel, na secção de Validation, encontras a lista completa de regras disponíveis. Vale a pena explorar a regra max para limitar o peso do ficheiro e a regra size para controlar dimensões, ambas muito úteis quando trabalhas diretamente com ficheiros [05:20].

Como atualizar uma receita com imagem opcional?

A atualização tem uma lógica diferente da criação. Ao atualizar, não queres obrigar o utilizador a enviar sempre uma imagem nova; ele pode querer alterar apenas o título ou outro campo.

A solução passa por uma verificação condicional dentro do método update do controlador. Perguntas se o pedido inclui um ficheiro e, só nesse caso, executas o upload:

php if ($request->file('imagem')) { $receita->imagem = $request->file('imagem')->store('receitas', 'public'); } $receita->update();

Desta forma, a imagem só é substituída quando o utilizador realmente envia uma nova. Os restantes campos são atualizados normalmente, sem forçar uploads desnecessários.

Como testar a atualização no Postman?

Para testar este endpoint precisas de estar autenticado com um token válido. O truque está em manter o método POST mas adicionar um campo extra que indique ao Laravel que se trata de uma atualização.

• Mantém a requisição como POST com o ID do recurso na URL, por exemplo /receitas/107.
• Adiciona um campo chamado _method com o valor put.
• Envia os campos que queres atualizar, como o título.
• Confirma na resposta que o registo foi modificado.

Este padrão é necessário porque o form data com ficheiros não suporta nativamente o método PUT. O Laravel reconhece o campo _method e processa a requisição como atualização [07:45].

Faz este exercício no teu projeto, testa com diferentes formatos de imagem e partilha nos comentários que regras de validação adicionais aplicaste ao teu sistema.