Estrutura de Pastas Laravel: Guia para Desenvolvedores

Descubra como organizar seu projeto Laravel como um profissional! Neste guia completo, vamos desmistificar a estrutura de pastas do Laravel, mostrando como cada componente se encaixa e contribui para um desenvolvimento mais eficiente e escalável. Desde os conceitos básicos até as funcionalidades avançadas, você aprenderá a aproveitar ao máximo as ferramentas que o Laravel oferece para criar aplicações web robustas e modernas.

O Laravel é um dos frameworks PHP mais utilizados, conhecido por sua simplicidade e elegância no desenvolvimento de aplicações web. Para quem está começando ou até para desenvolvedores experientes, entender a estrutura de pastas de um projeto Laravel é essencial para criar uma aplicação organizada, escalável e fácil de manter.

Nesta matéria, vamos explorar a estrutura padrão do Laravel, focando em pastas e arquivos como Controllers, Actions, Traits, Scopes, Services, Models e Observers. Também citaremos outras funcionalidades que tornam o Laravel tão poderoso e flexível.

A Estrutura de Diretórios do Laravel

Ao iniciar um novo projeto Laravel, você verá a seguinte estrutura de pastas:

app/
bootstrap/
config/
database/
public/
resources/
routes/
storage/
tests/
vendor/

Cada pasta tem um papel fundamental na organização da aplicação, mas nosso foco estará na pasta app/, onde grande parte da lógica de negócio reside.

Estrutura Completa da Pasta app no Laravel: Explicação Avançada e Profissional

A pasta app/ centraliza toda a lógica da aplicação no Laravel. Conhecer cada subpasta e sua função é essencial para desenvolver de forma limpa, organizada e escalável.

Aqui está a estrutura completa, incluindo subpastas comuns em projetos modernos:

app/
├── Actions/
├── Console/
├── Enums/
├── Events/
├── Exceptions/
├── Exports/
├── Http/
│   ├── Controllers/
│   │   ├── API/
│   │   ├── Admin/
│   │   └── Site/
│   ├── Middleware/
│   ├── Requests/
│   ├── Resources/
├── Imports/
├── Jobs/
├── Listeners/
├── Livewire/
├── Mail/
├── Models/
├── Observers/
├── Policies/
├── Providers/
├── Repositories/
├── Services/
└── Traits/

Agora, vamos explicar cada pasta detalhadamente:

1. Actions/

As Actions são uma maneira de organizar métodos específicos e isolados para determinadas tarefas. Enquanto muitos utilizam métodos diretamente dentro dos controllers, em projetos maiores é comum delegar a lógica de ações para classes separadas dentro de app/Actions. Isso facilita a reutilização e testabilidade.

Exemplo de uma Action:

namespace App\Actions;

use App\Models\User;

class CreateUserAction
{
    public function execute(array $data)
    {
        return User::create($data);
    }
}

Essa estrutura promove o princípio de responsabilidade única, tornando o código mais modular.

2. Console/

Contém comandos Artisan personalizados. O Kernel.php define comandos e agendamentos (Scheduler).

3. Enums/

Laravel Enum é uma funcionalidade poderosa que permite representar conjuntos fixos de valores de forma organizada e segura, substituindo o uso de strings soltas no código. Com a introdução dos Enums no PHP 8.1, o Laravel passou a oferecer suporte nativo para utilizar enums em models, validações, formulários e muito mais — tornando o desenvolvimento mais limpo, legível e livre de erros. Neste guia, você vai entender como aplicar Enums de forma prática no seu projeto Laravel e aproveitar todo o seu potencial.

Criando um Enum no Laravel

Use o comando Artisan se desejar gerar manualmente:

php artisan make:enum OrderStatus

Em seguida, crie o Enum em app/Enums/OrderStatus.php:

namespace App\Enums;

enum OrderStatus: string
{
    case PENDING = 'pending';
    case PAID = 'paid';
    case SHIPPED = 'shipped';
    case CANCELED = 'canceled';
}

4. Events/

Laravel Events permitem implementar uma arquitetura desacoplada, onde diferentes partes do sistema podem reagir a ações específicas, como o cadastro de um usuário ou a conclusão de um pedido. Com suporte nativo a listeners, filas assíncronas e até broadcast em tempo real, os eventos tornam o código mais organizado, escalável e fácil de manter.

Como Criar um Evento no Laravel

Use o comando Artisan:

php artisan make:event UserRegistered

Isso criará a classe em app/Events/UserRegistered.php:

namespace App\Events;

use App\Models\User;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;

class UserRegistered
{
    use Dispatchable, SerializesModels;

    public function __construct(public User $user) {}
}

✅ A propriedade User $user será usada pelos listeners.

5. Exceptions/

Erros acontecem — seja por uma falha de conexão com o banco de dados, um formulário mal preenchido ou uma regra de negócio que não foi satisfeita. O importante é como você os trata. No Laravel, o tratamento de exceções é uma parte essencial para garantir aplicações robustas, seguras e com uma boa experiência para o usuário.

O que são exceções em PHP e Laravel

Exceções são eventos inesperados que interrompem o fluxo normal de execução de um programa. Em PHP, as exceções são tratadas com blocos try, catch e throw. No Laravel, o sistema de exceções é baseado nessa estrutura, mas encapsulado e automatizado por uma classe central: o App\Exceptions\Handler.

Tratamento padrão de exceções no Laravel

Handler padrão (App\Exceptions\Handler.php)

Toda exceção em uma aplicação Laravel passa pelo arquivo Handler.php. É nele que você pode registrar exceções, definir como elas serão reportadas (logadas) e renderizadas (mostradas ao usuário).

Principais métodos do Handler.php:

• report(Exception $exception): responsável por registrar o erro no log.
• render($request, Throwable $exception): define como o erro será apresentado para o usuário.

6. Exports/

Utilizada com Laravel Excel para exportar dados em arquivos .xlsx, .csv, .pdf.

Exemplo: UsersExport, OrdersExport

Usa o pacote maatwebsite/excel.

7. Http/

Responsável pelas requisições HTTP.

a. Controllers/

Os Controllers estão localizados em app/Http/Controllers e são responsáveis por lidar com as requisições HTTP e retornar respostas adequadas, geralmente uma view ou JSON. Eles atuam como intermediários entre as rotas e a lógica de negócio.

Exemplo de um Controller:

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
 public function index()
 {
 $users = User::all();
 return view('users.index', compact('users'));
 }

 public function store(Request $request)
 {
 // Lógica de validação e criação de um novo usuário
 }
}

b. Middleware/

Como Funciona o Middleware no Laravel?

Quando uma requisição HTTP é recebida, o Laravel a encaminha por uma pilha de middlewares definidos na aplicação. Cada middleware tem a oportunidade de processar a requisição e decidir se ela deve continuar seu caminho ou ser interrompida.

Os middlewares são definidos como classes que implementam um método handle, responsável por processar a requisição. Esse método recebe dois parâmetros: a requisição ($request) e uma função de continuação ($next). O middleware pode executar ações antes ou depois de chamar $next($request), permitindo manipular tanto a requisição quanto a resposta.

Este comando criará uma nova classe VerificarToken no diretório app/Http/Middleware. Dentro dessa classe, você pode implementar a lógica desejada:

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class VerificarToken
{
    public function handle(Request $request, Closure $next)
    {
        if ($request->input('token') !== 'meu-token-secreto') {
            return redirect('/home');
        }

        return $next($request);
    }
}

c. Requests/

Form Requests com validação customizada.

d. Resources/

Transformam os dados para saída JSON limpa (ideal para APIs).

8. Imports/

Também usada com Laravel Excel, para importação de dados a partir de planilhas ou arquivos externos.

Exemplo: ProductsImport, LeadsImport

9. Jobs/

Contém tarefas que podem ser executadas em fila (queue), para tornar o sistema mais performático.

Exemplo: SendEmailJob, GeneratePDFJob

Use php artisan queue:work para processar jobs.

10. Listeners/

Escutam e reagem a eventos definidos em Events/.

Exemplo: SendWelcomeEmailListener, NotifyAdminOfNewUser

Podem ser síncronos ou assíncronos (colocados em fila).

11. Livewire/

Contém os componentes Livewire, que permitem criar interfaces dinâmicas sem sair do Laravel.

Exemplo: UserTable, FormContato, CheckoutComponent

Geralmente organizados por funcionalidades ou domínios.

12. Mail/

Contém classes de e-mail que definem estrutura e conteúdo das mensagens enviadas.

Exemplo: WelcomeMail, InvoiceMail, ResetPasswordMail

Usadas com Mail::to($user)->send(new WelcomeMail());

13. Models/

Os Models representam as tabelas do banco de dados e são responsáveis por interagir diretamente com os dados da aplicação. Eles estão localizados na pasta app/Models e utilizam o Eloquent ORM para simplificar as consultas.

Exemplo de um Model:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $fillable = ['name', 'email', 'password'];
}

Além disso, você pode definir relações entre modelos, como belongsTo, hasMany, e outras.

14. Observers/

Os Observers são utilizados para observar eventos no ciclo de vida de um model, como a criação, atualização ou exclusão de registros. Eles permitem que você execute ações automaticamente quando esses eventos ocorrem.

Os Observers são localizados em app/Observers.

Exemplo de um Observer:

namespace App\Observers;

use App\Models\User;

class UserObserver
{
    public function created(User $user)
    {
        // Enviar email de boas-vindas quando um usuário for criado
    }
}

O Observer deve ser registrado no AppServiceProvider:

use App\Models\User;
use App\Observers\UserObserver;

public function boot()
{
User::observe(UserObserver::class);
}

15. Policies/

As Policies no Laravel são uma forma poderosa de centralizar e organizar a lógica de autorização da sua aplicação. Ao invés de misturar regras de acesso nos controllers ou nas views, você pode isolá-las em classes específicas, tornando o código mais limpo, seguro e reutilizável.

O que são Policies no Laravel?

As Policies funcionam como “gatekeepers” — elas determinam se um usuário pode executar uma determinada ação em um determinado recurso (geralmente um Model, como um Post, Produto, ou Usuário).

✅ Gate vs Policy

• Gate: usado para ações genéricas, que não estão relacionadas diretamente a um Model.
• Policy: usada quando você precisa autorizar ações sobre instâncias de um Model (ex: se o usuário pode editar um Post específico).

16. Providers/

Service providers registram serviços, bindings, eventos, observers, macros etc.

17. Repositories/

Responsáveis por abstrair a lógica de acesso aos dados. Você pode definir interfaces + implementações aqui para melhor desacoplamento.

18. Services/

Centralizam lógicas de negócio reutilizáveis. Exemplo: UserService, PagamentoService, WebhookService.

19. Traits/

As Traits são blocos de código reutilizáveis que você pode incluir em várias classes. No Laravel, é comum ver traits para isolar comportamentos que são compartilhados por diferentes classes, como métodos de logs ou validações.

As Traits são geralmente armazenadas dentro de app/Traits.

Exemplo de uma Trait:

namespace App\Traits;

trait Loggable
{
    public function log($message)
    {
        // Implementação de log
    }
}

Para utilizá-la em uma classe:

use App\Traits\Loggable;

class UserController extends Controller
{
    use Loggable;

    public function store()
    {
        $this->log('Usuário criado.');
    }
}

Scopes

Os Scopes são usados para definir consultas comuns que podem ser reutilizadas em diversos lugares da aplicação. Eles são muito utilizados em Models para filtrar resultados de consultas.

Os Scopes são definidos dentro dos Models:

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    public function scopeActive(Builder $query)
    {
        return $query->where('status', 'active');
    }
}

Agora, você pode utilizar esse scope em qualquer consulta:

$activeUsers = User::active()->get();

Services

Os Services encapsulam a lógica de negócio da aplicação, separando-a dos controllers e models. Services são ideais para gerenciar funcionalidades complexas, que envolvem múltiplas partes da aplicação.

Eles geralmente são armazenados dentro da pasta app/Services.

Exemplo de um Service:

namespace App\Services;

use App\Models\User;

class UserService
{
    public function createUser(array $data)
    {
        return User::create($data);
    }

    public function deleteUser(User $user)
    {
        return $user->delete();
    }
}

Esse service pode ser facilmente chamado em Controllers ou Actions:

$userService = new UserService();
$userService->createUser($request->all());

Estrutura de pastas de um projeto Laravel

Entender a estrutura de pastas de um projeto Laravel é o primeiro passo para desenvolver aplicações bem organizadas e escaláveis. Componentes como Controllers, Actions, Traits, Scopes, Services, Models e Observers ajudam a separar as responsabilidades e facilitam a manutenção e extensão do projeto.

Essa organização não só melhora a legibilidade do código, mas também promove a reutilização de funcionalidades, um aspecto crucial em projetos de grande escala.

Baixe o Template Base de Projeto Laravel Profissional

Quer começar seu projeto Laravel já com toda essa estrutura organizada?

Baixe agora um projeto base com todos os diretórios, padrões e exemplos comentados.

🔥 Construa seus projetos com a melhor infraestrutura e ainda apoie o DevsBrasil!

Na Hostinger, você encontra hospedagem rápida, segura e com suporte top de linha — ideal para desenvolvedores e empreendedores digitais.

💡 Use o nosso link exclusivo do DevsBrasil e garanta:

✅ Descontos especiais nos planos de hospedagem, e-mail profissional, VPS e criador de sites com IA

✅ Ferramentas otimizadas para performance, com ótimo custo-benefício

✅ Apoio direto à nossa comunidade e ao nosso conteúdo gratuito 💚

👉 Acesse agora com nosso link exclusivo e aproveite os benefícios!