Filament Core Suite

Appearance

Instalação ​

Guia completo para criar um novo projeto usando o Filament Core Starter Kit.

Pré-requisitos ​

Software Necessário ​

  • PHP 8.3 ou superior com extensões:
    • OpenSSL, PDO, Mbstring, Tokenizer, XML, Ctype, JSON, BCMath, Fileinfo
  • Composer 2.6+
  • Node.js 20+ e npm
  • Laravel Installer (será instalado no processo)

Banco de Dados (escolha um) ​

  • MySQL 8.0+
  • PostgreSQL 13+
  • SQLite 3.35+

Recomendado para Produção ​

  • Redis 6.0+ (cache e queues)

Instalação ​

1. Instalar Laravel Installer ​

bash
composer global require laravel/installer

Verificar instalação:

bash
laravel --version

Saída esperada:

text
Laravel Installer 5.x

2. Criar Novo Projeto ​

Use o Laravel Installer com o template do Filament Core:

bash
laravel new my-new-project --git --pest --using=aronpc/filament-core-starter-kit

Flags utilizadas:

  • --git - Inicializa repositório Git
  • --pest - Usa Pest PHP para testes (recomendado)
  • --using=aronpc/filament-core-starter-kit - Usa o template do Starter Kit

Saída esperada:

text
Creating a "laravel/laravel" project at "./my-new-project"
Installing laravel/laravel...
Cloning template from aronpc/filament-core-starter-kit...
Application ready! Build something amazing.

Alternativamente, use PHPUnit:

bash
laravel new my-new-project --git --phpunit --using=aronpc/filament-core-starter-kit

Sem flags adicionais:

bash
laravel new my-new-project --using=aronpc/filament-core-starter-kit

3. Entrar no Projeto ​

bash
cd my-new-project

4. Configurar Ambiente ​

Copiar Arquivo de Ambiente ​

bash
cp .env.example .env

Gerar Chave da Aplicação ​

bash
php artisan key:generate

Saída esperada:

text
Application key set successfully.

Configurar Banco de Dados ​

Edite o arquivo .env:

Para MySQL:

bash
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=my_new_project
DB_USERNAME=root
DB_PASSWORD=sua_senha

Para PostgreSQL:

bash
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=my_new_project
DB_USERNAME=postgres
DB_PASSWORD=sua_senha

Para SQLite (desenvolvimento):

bash
DB_CONNECTION=sqlite
# DB_DATABASE será: database/database.sqlite

Se usar SQLite, crie o arquivo:

bash
touch database/database.sqlite

5. Criar Banco de Dados ​

MySQL:

bash
mysql -u root -p
sql
CREATE DATABASE my_new_project CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;

PostgreSQL:

bash
createdb my_new_project

6. Executar Migrações ​

bash
php artisan migrate

Saída esperada:

text
Migration table created successfully.
Migrating: 2024_01_01_000000_create_users_table
Migrated:  2024_01_01_000000_create_users_table (15ms)
Migrating: 2024_01_02_000000_create_people_table
Migrated:  2024_01_02_000000_create_people_table (18ms)
Migrating: 2024_01_03_000000_create_invoices_table
Migrated:  2024_01_03_000000_create_invoices_table (22ms)
...

7. Instalar Dependências Frontend ​

bash
npm install

Compilar assets:

bash
npm run dev

8. Criar Link de Storage ​

bash
php artisan storage:link

Resultado:

text
The [public/storage] link has been connected to [storage/app/public].

9. Criar Usuário Admin ​

Opção 1: Comando Filament (Recomendado) ​

bash
php artisan make:filament-user

Interativo - preencha os dados:

text
Name:
> Admin

Email address:
> admin@exemplo.com

Password:
> ********

Success!

Opção 2: Via Tinker ​

bash
php artisan tinker
php
User::create([
    'name' => 'Admin',
    'email' => 'admin@exemplo.com',
    'password' => bcrypt('senha123'),
]);

10. Iniciar Servidor ​

bash
php artisan serve

Saída esperada:

text
INFO  Server running on [http://127.0.0.1:8000].

Press Ctrl+C to stop the server

11. Acessar o Painel Admin ​

Abra seu navegador em:

text
http://localhost:8000/admin

Tela de login deve aparecer! ✅

Faça login com as credenciais criadas no passo 9.

Configuração dos Módulos ​

Habilitar/Desabilitar Módulos ​

O Starter Kit vem com todos os módulos habilitados por padrão. Para desabilitar algum, edite o .env:

bash
# Habilitar/Desabilitar módulos
FILAMENT_MODULE_INVOICES=true
FILAMENT_MODULE_PEOPLE=true
FILAMENT_MODULE_COMMUNICATIONS=true

Para desabilitar o módulo de Communications, por exemplo:

bash
FILAMENT_MODULE_COMMUNICATIONS=false

Configurações Avançadas ​

Veja config/filament-core.php para todas as opções:

php
return [
    'modules' => [
        'invoices' => env('FILAMENT_MODULE_INVOICES', true),
        'people' => env('FILAMENT_MODULE_PEOPLE', true),
        'communications' => env('FILAMENT_MODULE_COMMUNICATIONS', true),
    ],

    'features' => [
        'multi_tenant' => env('FILAMENT_MULTI_TENANT', false),
        'api_access' => env('FILAMENT_API_ACCESS', true),
    ],
];

Executar Seeders (Opcional) ​

Para popular o banco com dados de exemplo:

bash
# Todos os seeders
php artisan db:seed

# Seeder específico
php artisan db:seed --class=PeopleSeeder

Ambientes de Desenvolvimento ​

Configuração Local (Padrão) ​

O .env.example já vem configurado para desenvolvimento local:

bash
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync
MAIL_MAILER=log

Usando Laravel Sail (Docker) ​

O Starter Kit vem com Sail pré-configurado:

bash
# Iniciar containers
./vendor/bin/sail up -d

# Rodar migrações no container
./vendor/bin/sail artisan migrate

# Criar usuário admin
./vendor/bin/sail artisan make:filament-user

# Acessar em http://localhost

Usando Herd (macOS) ​

bash
# Entrar no diretório do projeto
cd ~/Herd/my-new-project

# Acessar em http://my-new-project.test

Troubleshooting ​

Erro: "Laravel Installer not found" ​

Causa: Laravel Installer não está no PATH

Solução:

bash
# Verificar se está instalado
composer global show laravel/installer

# Adicionar ao PATH (Linux/macOS)
echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Adicionar ao PATH (macOS com Zsh)
echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Erro: "SQLSTATE[HY000] [2002] Connection refused" ​

Causa: Banco de dados não está rodando ou credenciais incorretas

Solução:

bash
# Verificar se MySQL está rodando (Linux)
sudo systemctl status mysql

# Iniciar MySQL (Linux)
sudo systemctl start mysql

# Verificar se PostgreSQL está rodando (Linux)
sudo systemctl status postgresql

# macOS com Homebrew
brew services list
brew services start mysql

Verificar credenciais no .env:

bash
DB_HOST=127.0.0.1  # Use 127.0.0.1, não "localhost"
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=  # Senha correta

Erro: "Specified key was too long" ​

Causa: MySQL versão antiga

Solução: Edite app/Providers/AppServiceProvider.php:

php
use Illuminate\Support\Facades\Schema;

public function boot(): void
{
    Schema::defaultStringLength(191);
}

Depois rode novamente:

bash
php artisan migrate:fresh

Erro: "npm: command not found" ​

Causa: Node.js não está instalado

Solução:

bash
# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# macOS com Homebrew
brew install node

# Verificar instalação
node --version
npm --version

Assets não aparecem no navegador ​

Solução:

bash
# Recompilar assets
npm run dev

# Ou para produção
npm run build

# Limpar cache do navegador (Ctrl+Shift+R)

Erro: "Class 'Filament\Panel' not found" ​

Causa: Dependências não instaladas corretamente

Solução:

bash
# Reinstalar dependências
rm -rf vendor composer.lock
composer install

# Limpar cache
php artisan optimize:clear

Verificação de Saúde ​

Execute para verificar se tudo está OK:

bash
# Informações do ambiente
php artisan about

# Verificar conexão com banco
php artisan db:show

# Listar rotas do Filament
php artisan route:list --name=filament

# Rodar testes
php artisan test

Saída esperada dos testes:

text
PASS  Tests\Feature\ExampleTest
✓ the application returns a successful response

PASS  Tests\Unit\ExampleTest
✓ that true is true

Tests:    2 passed (2 assertions)
Duration: 0.15s

Próximos Passos ​

Agora que você instalou com sucesso:

  1. 🚀 Primeiros Passos - Aprenda a usar o painel admin
  2. 🏗️ Estrutura do Projeto - Entenda a organização do código
  3. ⚙️ Configuração - Configure variáveis e módulos
  4. 📚 Funcionalidades - Explore todos os recursos disponíveis

Recursos Úteis ​

Documentação privada do ecossistema Filament Core.

© 2025 Aron Cardoso