Skip to content

Capítulo 2.1: Preparando o Ambiente Laravel

Tempo de Estudo: 1-2 horas

1. Por que um Ambiente Local é Necessário?

Imagine que você está construindo uma sonda espacial. Antes de lançá-la no espaço, você testa todos os sistemas na Terra. Um ambiente local é o seu "laboratório de controle" para o código:

  • Experimentos seguros sem impacto no servidor de produção
  • Implantação rápida de dependências
  • Fácil alternância entre versões de software

💡 Analogia Espacial: Herd = Complexo de Lançamento Móvel Docker = Simulador de Estação Espacial XAMPP = Banco de Testes Estacionário

2. Instalação do Herd

Herd — uma ferramenta moderna para gerenciar o ambiente PHP (análogo ao Laravel Valet).

Passos de Instalação:

  1. Baixe o instalador: herd.laravel.com
  2. Execute Herd Installer.exe → Next → Install
  3. Após a instalação:
    • Abra o Herd no menu Iniciar. O ícone do aplicativo aparecerá na bandeja do sistema (perto do relógio).
    • Clique no ícone do Herd: certifique-se de que o Nginx e a versão de PHP desejada (por exemplo, 8.3) estejam em execução (marcados com um ponto verde).
    • Vá para Herd Paths e adicione a pasta onde seus projetos serão armazenados (por exemplo, C:\Users\YourUser\Code). O Herd criará automaticamente um domínio bonito do tipo nome-da-pasta.test para cada subdiretório nesta pasta.

⚠️ Importante! Durante a instalação: - Permita o acesso à rede (se o firewall solicitar) - Verifique o caminho no PATH: C:\Program Files\Herd\bin

Verificação de Operação:

  1. Clique no ícone do Herd na bandeja do sistema.
  2. Certifique-se de que os serviços Nginx e PHP estejam ativos (indicadores verdes).
  3. Na sua pasta de projetos (por exemplo, C:\Users\YourUser\Code), crie uma pasta test e dentro dela um arquivo index.php com o conteúdo <?php phpinfo(); ?>.
  4. No Herd, através da aba "sites", especifique o caminho para a pasta test e clique em "Add site".
  5. Abra o endereço http://test.test no navegador. Você deverá ver a página com informações sobre o PHP.

3. Métodos Alternativos (brevemente)

Ferramenta Para quem Prós Contras
Laravel Sail (Docker) Para todos os níveis Isolamento completo, repetibilidade do ambiente, suporte oficial do Laravel Requer instalação do Docker, consome mais recursos
XAMPP Iniciantes Tudo em um instalador (All-in-One) Volumoso, mais difícil de gerenciar versões de software, polui o sistema
Laragon Desenvolvedores Windows Rápido, fácil de alternar versões, configuração automática de hosts Requer reinício manual do servidor web ao adicionar um novo projeto

Exemplo com Docker (Laravel Sail): 

# Após a instalação do Docker
./vendor/bin/sail up

4. Instalação do PHP e Composer

Se não estiver usando o Herd:

  1. PHP:
    • Baixe o PHP 8.3 para Windows
    • Descompacte em C:\PHP
    • Adicione ao PATH: 
      # Recomenda-se executar no PowerShell como administrador
[Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\PHP", "User")
  2. Composer:

5. Instalação do PostgreSQL

Para trabalhar com bancos de dados:

  1. Baixe o PostgreSQL 15
  2. Execute o instalador:
  3. Senha para o superusuário: admin (ou sua própria)
  4. Porta: 5432 (padrão)
  5. Após a instalação:
  6. Abra o pgAdmin 4 (cliente gráfico)

    Você pode usar qualquer outro cliente para trabalhar com o banco de dados, por exemplo, DBeaver, DataGrip ou até mesmo a linha de comando. Eu prefiro DBeaver - mas é uma questão de gosto

  7. Crie um banco de dados para o projeto: space_api

6. Instalação do Laravel

  1. Via Composer: 

    composer create-project laravel/laravel space-api
cd space-api

  2. Inicialização do Git (opcional): 

    git init
git add .
git commit -m "Início do projeto espacial"

  3. Iniciando e Verificando o Servidor:

    Se você estiver usando Herd: Certifique-se de que seu projeto space-api esteja na pasta que você adicionou ao Herd. Abra no navegador o endereço: http://space-api.test Você deverá ver a página inicial do Laravel. O servidor já está funcionando graças ao Herd!

Se você NÃO estiver usando Herd (instalação manual): 

php artisan serve
Abra no navegador: http://localhost:8000 → A página inicial do Laravel deverá aparecer!

Ao criar um projeto no Herd:

Basta seguir as instruções na tela. Para facilitar, o nome do projeto será space-api. Starter kit - qualquer um, mas eu prefiro React.

Certifique-se de incluir o phpunit - ele nos será útil mais adiante

7. Configuração do Projeto

Arquivos Importantes:

  • .env — configurações de ambiente (chaves, bancos de dados)
  • config/database.php — configuração do SGBD
  • composer.json — dependências PHP

Conexão do BD ao Projeto:

Adicione em .env:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=space_api
DB_USERNAME=postgres # Login para postgres
DB_PASSWORD=admin # Senha para postgres

Primeiros comandos Artisan: 

php artisan key:generate  # Geração da chave da aplicação
php artisan migrate:fresh # Migração do banco de dados (Ao mudar para postgres)

Quiz para Fixação

1. Herd é...

2. Qual ferramenta o Laravel usa para gerenciar as dependências do PHP?

3. Porta padrão para PostgreSQL:

4. Comando para criar um projeto Laravel via Composer:

5. Arquivo com as configurações de ambiente?

🚀 Resumo do Capítulo

Você implantou o "ponto de partida" para a API espacial! Agora você tem:

  • 🛠️ Ambiente local (Herd ou instalação manual) com PHP e Nginx
  • 🐘 Servidor de banco de dados PostgreSQL instalado
  • 🚀 Projeto Laravel space-api
  • 🔌 Conexão configurada ao banco de dados

📌 Verificação:

  • Se você está com Herd: Certifique-se de que o site abre no endereço http://space-api.test.
  • Se sem Herd: Certifique-se de que o comando php artisan serve funciona e o site abre no endereço http://localhost:8000.
  • De qualquer forma, verifique se o banco de dados space_api criado está visível no pgAdmin 4.