RibaSoft

Laravel - 07/01/2026

• • Criar ambiente de desenvolvimento WSL
  • Extenções VSCode
  • Criar Projeto
  • PHP
  • docker-compose.yml
  • Dockerfile
  • .env
  • Fortify
  • Spatie
  • Alterar o Migrate Users
  • Registrar o Middleware
  • Criar Seeders
  • Registrar os Seeders
  • Restrigindo os acessos com Spatie
  • Criar banco de dados
  • Iniciando aplicativo pela primeira vez
  • Comandos php artisan
  • GitHub
  • Passando de DEV para PROD
  • Atualizando o Sistema
  • Tradução pt_BR
  • Personalizando Email

Criar ambiente de desenvolvimento WSL:

• Extensões VS Code:

  
  WSL: by Microsoft GitHub Copilot Chat: by GitHub Laravel Blade Snippets: by Winnie Lin Portuguese (Brazil) Language Pack for VS Code: by Microsoft HTML CSS Support: by ecmel JavaScrip (ES6) code Snippets: by charalampos karypidis

• Criar Projeto:

  
  

  O Docker é um gerenciador de containers, ele tem um plugin chamado compose, mas esse plugin não será usado agora, oque será usado é um container chamado composer que criará a estrutura do Laravel que é um aplicativo em PHP, por isso ao se falar em app está se falando do Laravel.

  Então o Docker baixará e executará um container chamado compose que criará a estrutura do Laravel pelo comando "composer create-project laravel/laravel .".

  docker run --rm -v $(pwd):/app -w /app composer:latest composer create-project laravel/laravel .

  Obs. Quando o Projeto já existir, quando por exemplo baixado em outro lugar pelo git clone, o composer do php precisará ser executado novamente para instalar algumas dependências do projeto que não são enviadas ao GitHub.

• PHP:

  
  

  Depois de criada a estrutura do Laravel pelo composer do PHP, além de instalar os requerimentos contidos no arquivo compose.json, o comando executado acima também espelhará os aquivos de dentro do container do PHP para a pasta atual do projeto, assim é uma das formas de interagir com as configurações internas dos containers, por isso já se pode criar também o diretório para a configurações do php.ini.

  mkdir -p docker/php nano docker/php/php.ini

  Conteúdo:

  upload_max_filesize = 500M post_max_size = 500M memory_limit = 512M max_execution_time = 600 date.timezone = "America/Sao_Paulo"

• docker-compose.yml

  
  

  Configurar o docker-compose.yml para gerenciar a criação e configuração do container do PHP onde será definida o vínculo de pastas e arquivos externos com os internos, redes virtuais para comunicação com servidor e banco de dados, etc.

  Obs. A identação é fundamental definida a cada 2 espaços e não pode ser usado TAB.

  services: #PHP com Laravel app: build: . networks: - rede_global_nginx - rede_global_postgres container_name: laravel_ribasoft_app working_dir: /var/www volumes: - ./:/var/www - ./docker/php/php.ini:/usr/local/etc/php/conf.d/php.ini restart: unless-stopped networks: rede_global_nginx: external: true rede_global_postgres: external: true

• Dockerfile

  
  

  O Dockerfile tem configurações adicionais e comandos que serão executados no UP do container.

  Tambérm instalará os pacotes necessários e definirá privilérios de usuárias para evitar que os arquivos criados posteriormente sejam criados como root.

  FROM php:8.4-fpm #Pacotes Básicos RUN apt-get update && apt-get install -y libpq-dev zip unzip git ffmpeg python3 python3-pip python3-full && rm -rf /var/lib/apt/lists/* RUN python3 -m pip install --break-system-packages -U yt-dlp #Postgres RUN docker-php-ext-install pdo_pgsql pgsql #Composer COPY --from=composer:latest /usr/bin/composer /usr/bin/composer #Usuario RUN groupadd -g 1000 ribasoft && useradd -u 1000 -ms /bin/bash -g ribasoft ribasoft RUN chown -R ribasoft:ribasoft /var/www USER ribasoft #Diretorio de trabalho WORKDIR /var/www

• .env

  
  

  Aqui é definida as configuraçãos de conexão, por padrão ele não vai para o git, por isso deve ser recriado e reconfigurado quando passar do ambiente DEV para o PROD.

  cp .env.example .env

  Conteúdo para alterar:

  DB_CONNECTION=pgsql DB_HOST=postgres DB_PORT=5432 DB_DATABASE=nome_banco DB_USERNAME=usuario_banco DB_PASSWORD=senha_banco

• Fortify:

  
  

  Para login, e autenticações de usuário será usado o Fortify.

  docker run --rm -v $(pwd):/app -w /app composer:latest composer require laravel/fortify docker compose up -d docker compose exec app bash php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"

  Após executar esses comandos é necessário registrar o fortify em bootstrap/providers.php:

  return [ App\Providers\AppServiceProvider::class, App\Providers\FortifyServiceProvider::class, ];

  Se o container do PHP já estiver rodando execute o composer install novamente para se seja instaladas as depêndencias necessárias.

  docker compose exec app composer install

  Ou se não estiver rodando pode usar a imagem temporaria do composer.

  docker run --rm -v $(pwd):/app -w /app composer:latest composer install

• Auto Cadastro de Usuário

  Para auto cadastrar-se ou redefinir a senha os seguintes arquivos precisam ser editados:

  app/Providers/FortifyServiceProvider.php

  Adicionar dentro da função boot().

  Fortify::registerView(function () {return view('auth.cadastro');}); Fortify::resetPasswordView(function ($request) {return view('auth.alterar_senha', ['request' => $request]);}); use Laravel\Fortify\Contracts\SuccessfulPasswordResetLinkRequestResponse; $this->app->singleton(SuccessfulPasswordResetLinkRequestResponse::class, function ($app) { return new class implements SuccessfulPasswordResetLinkRequestResponse { public function toResponse($request) { return redirect()->route('login')->with('status', trans('passwords.sent')); } }; });

  No Header da tela de login adicione:

  @if (session('status')) <div class="alert-success"> {{ session('status') }} </div> @endif

  app/Models\User.php

  namespace App\Models; use Illuminate\Notifications\Notifiable; use Illuminate\Foundation\Auth\User as Authenticatable; use Spatie\Permission\Traits\HasRoles; class User extends Authenticatable { use HasRoles, Notifiable; protected $fillable = [ 'name', 'email', 'password', ]; protected $hidden = [ 'password', 'remember_token', ]; protected function casts(): array { return [ 'email_verified_at' => 'datetime', 'password' => 'hashed', ]; } }

• Spatie:

  
  

  O Spatie é responsável pelas regras de permissões, ele que diz quem pode ver oque.

  O composer install instalará as dependências necessárias.

  O php artisan migrate:refresh apagará o banco de dados e recontruirá todas as tabelas com os usuários iniciais já determinando suas permissões.

  ATENÇÃO!

  Se ouver dados importantes no banco de dados não execute o "migrate:refresh" pois você perderá todos os dados. Nesse caso use o psql do postgres.

  docker compose exec app bash composer require spatie/laravel-permission php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" composer install php artisan migrate:refresh --seed

• Alterar o Migrate Users

  
  

  Em app/Models/Users.php adicionar abaixo do namespace App\Models:

  use Spatie\Permission\Traits\HasRoles;

  Dentro da classe User extends Authenticable substituir use HasFactory, Notifiable; por:

  use HasRoles;

• Registrar o Middleware:

  
  

  Os Middlewares são registados em bootstrap/app.php:

  ->withMiddleware(function (Middleware $middleware): void { $middleware->alias([ 'role' => \Spatie\Permission\Middleware\RoleMiddleware::class, 'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class, 'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class, ]); })

• Criar Seeders:

  
  

  Criar os seeders dos primeiros usuários do app e suas permissões:

  php artisan make:seeder RoleSeeder php artisan make:seeder UserSeeder

  Em database/seeders/RoleSeeder.php:

  use Illuminate\Database\Seeder; use Spatie\Permission\Models\Role; use Spatie\Permission\Models\Permission; class RoleSeeder extends Seeder { public function run(): void { // Limpar o cache de permissões do Spatie (muito importante) app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions(); // Locais de Acesso Permission::firstOrCreate(['name' => 'acesso-total']); Permission::firstOrCreate(['name' => 'area-administrativa']); Permission::firstOrCreate(['name' => 'area-clientes']); // Regras das Permissoes $roleSuporte = Role::firstOrCreate(['name' => 'suporte']); $roleSuporte->givePermissionTo(Permission::all()); $roleAdmin = Role::firstOrCreate(['name' => 'adm']); $roleAdmin->givePermissionTo(['area-administrativa']); $roleClientes = Role::firstOrCreate(['name' => 'cliente']); $roleClientes->givePermissionTo(['area-clientes']); } }

  Em database/seeders/UserSeeder.php:

  use Illuminate\Database\Seeder; use App\Models\User; use Illuminate\Support\Facades\Hash; class UserSeeder extends Seeder { public function run(): void { $users = [ [ 'name' => 'Suporte', 'email' => 'suporte@suporte', 'password' => Hash::make('sfaa545sa4s6'), 'email_verified_at' => now(), 'regras' => ['suporte'], ], [ 'name' => 'Administrador', 'email' => 'adm@adm', 'password' => Hash::make('sfaa545sa4s6'), 'email_verified_at' => now(), 'regras' => ['adm'], ], [ 'name' => 'Cliente e Adm', 'email' => 'cliente.adm@cliente.adm', 'password' => Hash::make('sfaa545sa4s6'), 'email_verified_at' => now(), 'regras' => ['adm', 'cliente'], ], [ 'name' => 'Cliente', 'email' => 'cliente@cliente', 'password' => Hash::make('sfaa545sa4s6'), 'email_verified_at' => now(), 'regras' => ['cliente'], ] ]; foreach ($users as $user) { $userModel = User::updateorCreate( ['email' => $user['email']], [ 'name' => $user['name'], 'password' => $user['password'], 'email_verified_at' => $user['email_verified_at'] ] ); $userModel->syncRoles($user['regras']); } } }

• Registrar os Seeders:

  
  

  Registrar os seeders em database/seeeders/DatabaseSeeder.php, primeiro o seeder das regras RoleSeeder e depois o seeder dos usuários UserSeeder, para que as tabelas sejam preenchidas na ordem correta, pois para cadastrar uma usuário com uma regra, ela já deve existir.

  public function run(): void{ public function run(): void { $this->call([ RoleSeeder::class, UserSeeder::class, ]); } }

• Restrigindo os acessos com Spatie:

  
  

  Para se controlar o acesso de rotas inteitas use:

  // Apenas usuários com a role 'adm' ou 'suporte' entram aqui Route::middleware(['auth', 'role:adm|suporte'])->group(function () { Route::get('/admin', [AdminController::class, 'index']); }); // Apenas admins acessam Route::middleware(['auth', 'role:admin'])->group(function () { Route::get('/admin', [AdminController::class, 'index']); }); // Apenas clientes acessam Route::middleware(['auth', 'role:cliente'])->group(function () { Route::get('/area-do-cliente', [ClienteController::class, 'index']); });

  Para restringir apenas partes de códigos use:

  @can('area-administrativa') <nav> <a href="/admin/dashboard">Painel de Controle</a> </nav> @endcan @can('acesso-total') <button>Configurações do Sistema</button> @endcan

Criar banco de dados:

• No diretório do servidor acesse o container do postgres, crie as redes virtuais para comunicação se ainda não foram criadas e crie o banco de dados, usuário e senha:

  docker network create rede_global_nginx docker network create rede_global_postgres docker compose exec postgres psql -U usuario -d banco CREATE USER usuario WITH PASSWORD 'senha'; CREATE DATABASE banco; GRANT ALL ON SCHEMA public TO usuario; GRANT ALL PRIVILEGES ON DATABASE banco TO usuario; ALTER DATABASE banco OWNER TO usuario;

  Ou caso já tenha um banco de dados basta realizar o restore:

  cat /var/www/site-ribasoft/storage/app/private/api/varejo/backups/backup.sql | docker compose exec -T postgres psql -U usuario -d banco

Iniciando aplicativo pela primeira vez:

• Agora subiremos o container, entraremos dentro dele e executaremos seu bash para configurar a aplicação via php artisan.

  docker compose up -d docker compose exec app bash

  Veja mais comandos Docker AQUI

  .

• Criar chave para criptografia, criar tabelas base do sistema no banco de dados alimentar com dados pré-definidos e prepara o sistema para o uso de APIs.

  php artisan key:generate php artisan migrate --seed php artisan install:api

Comandos php artisan:

• Caso algum arquivo criado e espelhado venha como dono root, execute o comando a seguir:

  sudo chown -R usuario:usuario . sudo chmod -R 775 .

• Criar um Controller:

  php artisan make:controller NomeController

• Criar um Model:

  php artisan make:model Cliente

• Criar um Migration:

  php artisan make:migration create_Clientes_table

• Criar um Seeder:

  php artisan make:seeder UsuariosSeeder

• Criar Tabelas dos Migrations e adicionar os dados dos Seeders:

  php artisan migrate --seed

• Atualizar as alterações das tabelas feitas no Migrate:

  php artisan optimize:clear php artisan migrate --force

• Apenas adicinar os dados dos Seeders quando as tabelas jé existirem:

  php artisan db:seed

• Recriar todas as tabelas e iniciar dados básicos:

  migrate:fresh --seed

• Limpesa quando algo está bugado:

  php artisan optimize:clear

• Gerar Cache para melhor velocidade em produção:

  php artisan optimize

• Criar chave para cripitografias funcionarem corretamente:

  php artisan key:generate

• Criar link simbólico:

  Expor o diretório storage/app/public no diretório public/storage, dessa forma os arquivos podem ser acessados de forma pública pelo browser.

  php artisan storage:link

• Listar rotas válidas:

  php artisan route:list

• Procurar rota específica:

  php artisan route:list | grep nome_rota

• Cria arquivos para envio de email:

  php artisan make:mail ConviteCliente

• Limpa o banco por completo, tabelas, dados, etc:

  php artisan db:wipe

GitHub:

• Adicione as restrições no .gitignore para evitar problemas:

  /public/storage /public/videos /public/arquivos /public/musicas /storage

• Configurar o GitHub:

  git init git branch -M main git config --global user.name "ribasoft" git config --global user.email "ribamarmsantos@gmail.com" git remote add origin git@github.com:RibaSoft/nome_projeto.git git status git add . git commit -m "Primeiro commit" git push -u origin main

Passando de DEV para PROD:

• GitHub

  No servidor Debian de produção após instalar e configurar o git e o docker, crie o diretório de projeto baixe o projeto do GitHub e instale o composer do php através do docker para criar o vendor dentre outras coisas:

  git clone git@github.com:RibaSoft/nome_projeto.git . docker run --rm -v $(pwd):/app -w /app composer:latest composer install

  Crie as redes virtuais, o arquivo .env, e a chave de criptografia.

  docker network create rede_global_nginx docker network create rede_global_postgres cp .env.example .env docker compose exec app bash php artisan key:generate php artisan migrate --seed

Atualizando o Sistema:

• Sempre que houver alterações no projeto no github execute:

  git pull

Tradução pt_BR:

• docker compose exec app bash composer require lucascudo/laravel-pt-br-localization --dev php artisan vendor:publish --tag=laravel-pt-br-localization php artisan config:clear

  No .env

  APP_NAME=Nome_APP APP_LOCALE=pt_BR APP_FALLBACK_LOCALE=pt_BR APP_FAKER_LOCALE=pt_BR DB_CONNECTION=pgsql DB_HOST=postgres DB_PORT=5432 DB_DATABASE=nome_banco DB_USERNAME=usuario DB_PASSWORD=senha MAIL_MAILER=smtp MAIL_SCHEME=null MAIL_HOST=smtp.gmail.com MAIL_PORT=587 MAIL_ENCRYPTION=tls MAIL_USERNAME=email@semaspas MAIL_PASSWORD=senha_app_sem_espaços_e_sem_aspas MAIL_FROM_ADDRESS="no-reply@seudominio.com.br" MAIL_FROM_NAME="${APP_NAME} - No Reply"

  Obs. Sempre que mexer no .env execute:

  docker compose exec app php artisan optimize:clear docker compose exec app php artisan optimize

Personalizando Email:

• php artisan vendor:publish --tag=laravel-mail

  Para aconpanhar o desenvolvimento do visual do email de recuperação de senha use a rota temporatia abaixo:

  use Illuminate\Auth\Notifications\ResetPassword; use App\Models\User; Route::get('/mail-preview', function () { // Cria uma notificação fake para gerar o visual $notification = new ResetPassword('token-de-teste'); // Transforma a notificação em uma mensagem de e-mail e renderiza o HTML return $notification->toMail(User::first() ?? new \App\Models\User); });

  Para exibir o logo apague o if/else do arquivos resources/views/vendor/mail/html/themes/header.blade.php mas deixe a tag da imagem e coloque um url completo de uma imagem online.

  <img src="https://seudominio.com.br/img/logo.png" class="logo" alt="Empresa Logo">