#Instalação

#Requisitos

Antes de instalar o Laravel Lusophone, certifique-se de que o seu ambiente atende aos seguintes requisitos:

#Requisitos Mínimos

PHP: 8.1 ou superior
Laravel: 10.x, 11.x ou 12.x
Extensões PHP:
- ext-bcmath - Para cálculos de validação precisos
- ext-json - Para processamento de dados de localização

#Ambientes Testados

Desenvolvimento: Linux, macOS, Windows
Produção: Ubuntu 20.04+, CentOS 8+, Amazon Linux 2
Containers: Docker, Laravel Sail
Cloud: AWS, Google Cloud, Azure, DigitalOcean

#Instalação Via Composer

#1. Instalação Básica

Copied!

composer require arnaldotomo/laravel-lusophone

composer require arnaldotomo/laravel-lusophone

#2. Verificação da Instalação

Copied!

php artisan vendor:publish --tag=lusophone-config

php artisan vendor:publish --tag=lusophone-config

Será criado o arquivo config/lusophone.php com as configurações padrão.

#3. Teste Rápido

Copied!

php artisan lusophone:detect

php artisan lusophone:detect

Saída esperada:

Copied!

🌍 Laravel Lusophone - Detecção de Região
 
✅ Região detectada: MZ (Moçambique)
📍 Ambiente: Local (desenvolvimento)
💰 Moeda: MZN (Metical)
📞 Formato telefone: +258 XX XXX XXXX
🆔 Validação fiscal: NUIT (9 dígitos)
 
🎯 Teste de validação:
✅ NUIT válido: 123456789
✅ Telefone válido: +258 823456789
✅ Formatação moeda: 1.500,50 MT

🌍 Laravel Lusophone - Detecção de Região

✅ Região detectada: MZ (Moçambique)
📍 Ambiente: Local (desenvolvimento)
💰 Moeda: MZN (Metical)
📞 Formato telefone: +258 XX XXX XXXX
🆔 Validação fiscal: NUIT (9 dígitos)

🎯 Teste de validação:
✅ NUIT válido: 123456789
✅ Telefone válido: +258 823456789
✅ Formatação moeda: 1.500,50 MT

#Configuração Automática vs Manual

#⚡ Configuração Automática (Recomendada)

Copied!

php artisan lusophone:setup

php artisan lusophone:setup

Este comando irá:

Publicar ficheiros de configuração
Publicar traduções (opcional)
Detectar o seu ambiente
Configurar região padrão apropriada
Testar a integração

Saída interativa:

Copied!

🚀 Configuração do Laravel Lusophone
 
? Qual é o seu ambiente principal de desenvolvimento?
  1. Moçambique (MZ) - Recomendado para desenvolvimento africano
  2. Portugal (PT) - Para desenvolvimento europeu
  3. Brasil (BR) - Para desenvolvimento brasileiro
  4. Detectar automaticamente
 
? Publicar ficheiros de idioma personalizáveis? (Y/n) n
? Integrar automaticamente com Laravel Breeze/Jetstream? (Y/n) y
 
✅ Configuração concluída com sucesso!

🚀 Configuração do Laravel Lusophone

? Qual é o seu ambiente principal de desenvolvimento?
  1. Moçambique (MZ) - Recomendado para desenvolvimento africano
  2. Portugal (PT) - Para desenvolvimento europeu
  3. Brasil (BR) - Para desenvolvimento brasileiro
  4. Detectar automaticamente

? Publicar ficheiros de idioma personalizáveis? (Y/n) n
? Integrar automaticamente com Laravel Breeze/Jetstream? (Y/n) y

✅ Configuração concluída com sucesso!

#🔧 Configuração Manual

Se preferir configurar manualmente:

Publicar Configurações

Copied!

php artisan vendor:publish --tag=lusophone-config

php artisan vendor:publish --tag=lusophone-config

Publicar Traduções (Opcional)

Copied!

php artisan vendor:publish --tag=lusophone-lang

php artisan vendor:publish --tag=lusophone-lang

Configurar .env

Copied!

# Detecção automática (recomendado)
LUSOPHONE_AUTO_DETECT=true
 
# Região padrão para desenvolvimento local
LUSOPHONE_DEFAULT_REGION=MZ
 
# Definir locale automaticamente
LUSOPHONE_AUTO_SET_LOCALE=true
 
# Forçar região específica (opcional - para testes)
# LUSOPHONE_FORCE_REGION=PT

# Detecção automática (recomendado)
LUSOPHONE_AUTO_DETECT=true

# Região padrão para desenvolvimento local
LUSOPHONE_DEFAULT_REGION=MZ

# Definir locale automaticamente
LUSOPHONE_AUTO_SET_LOCALE=true

# Forçar região específica (opcional - para testes)
# LUSOPHONE_FORCE_REGION=PT

#Integração com Laravel Breeze

#Instalação Simultânea (Novo Projeto)

Copied!

# 1. Criar projeto Laravel
composer create-project laravel/laravel meu-projeto
cd meu-projeto
 
# 2. Instalar Breeze
composer require laravel/breeze --dev
php artisan breeze:install blade
 
# 3. Instalar Laravel Lusophone
composer require arnaldotomo/laravel-lusophone
 
# 4. Configurar
php artisan lusophone:setup --breeze
 
# 5. Compilar assets
npm install && npm run build
 
# 6. Testar
php artisan serve

# 1. Criar projeto Laravel
composer create-project laravel/laravel meu-projeto
cd meu-projeto

# 2. Instalar Breeze
composer require laravel/breeze --dev
php artisan breeze:install blade

# 3. Instalar Laravel Lusophone
composer require arnaldotomo/laravel-lusophone

# 4. Configurar
php artisan lusophone:setup --breeze

# 5. Compilar assets
npm install && npm run build

# 6. Testar
php artisan serve

#Projeto Existente com Breeze

Copied!

# Instalar Laravel Lusophone
composer require arnaldotomo/laravel-lusophone
 
# Configurar com integração Breeze
php artisan lusophone:setup --breeze
 
# As views de autenticação serão automaticamente traduzidas!

# Instalar Laravel Lusophone
composer require arnaldotomo/laravel-lusophone

# Configurar com integração Breeze
php artisan lusophone:setup --breeze

# As views de autenticação serão automaticamente traduzidas!

Resultado da Integração:

✅ Login/registo traduzido automaticamente
✅ Mensagens de validação em português
✅ Formulários adaptados culturalmente
✅ Emails de recuperação de palavra-passe localizados

#Integração com Laravel Jetstream

#Com Livewire

Copied!

# Instalar Jetstream primeiro
composer require laravel/jetstream
php artisan jetstream:install livewire
 
# Instalar Laravel Lusophone
composer require arnaldotomo/laravel-lusophone
php artisan lusophone:setup --jetstream
 
# Compilar
npm install && npm run build

# Instalar Jetstream primeiro
composer require laravel/jetstream
php artisan jetstream:install livewire

# Instalar Laravel Lusophone
composer require arnaldotomo/laravel-lusophone
php artisan lusophone:setup --jetstream

# Compilar
npm install && npm run build

#Com Inertia.js

Copied!

# Instalar Jetstream com Inertia
composer require laravel/jetstream
php artisan jetstream:install inertia
 
# Instalar Laravel Lusophone
composer require arnaldotomo/laravel-lusophone
php artisan lusophone:setup --jetstream --inertia
 
# Compilar
npm install && npm run build

# Instalar Jetstream com Inertia
composer require laravel/jetstream
php artisan jetstream:install inertia

# Instalar Laravel Lusophone
composer require arnaldotomo/laravel-lusophone
php artisan lusophone:setup --jetstream --inertia

# Compilar
npm install && npm run build

Funcionalidades Jetstream Localizadas:

✅ Dashboard traduzido
✅ Gestão de perfil localizada
✅ Gestão de equipas adaptada culturalmente
✅ API tokens com terminologia regional
✅ Configurações de conta em português

#Verificação da Instalação

#1. Teste de Detecção

Copied!

php artisan lusophone:detect --verbose

php artisan lusophone:detect --verbose

#2. Teste de Validação

Copied!

php artisan lusophone:detect --test-validation

php artisan lusophone:detect --test-validation

#3. Teste de Formatação

Copied!

php artisan lusophone:detect --test-currency

php artisan lusophone:detect --test-currency

#4. Teste Completo

Copied!

php artisan lusophone:detect --full-test

php artisan lusophone:detect --full-test

#Resolução de Problemas

#Erro: "Class 'ArnaldoTomo\LaravelLusophone...' not found"

Copied!

# Limpar cache do Composer
composer dump-autoload
 
# Limpar cache do Laravel
php artisan config:clear
php artisan cache:clear

# Limpar cache do Composer
composer dump-autoload

# Limpar cache do Laravel
php artisan config:clear
php artisan cache:clear

#Erro: Extensões PHP em falta

Ubuntu/Debian

Copied!

sudo apt-get install php8.1-bcmath php8.1-json

sudo apt-get install php8.1-bcmath php8.1-json

CentOS/RHEL

Copied!

sudo yum install php81-bcmath php81-json

sudo yum install php81-bcmath php81-json

macOS (Homebrew)

Copied!

brew install [email protected]
pecl install bcmath

brew install [email protected]
pecl install bcmath

Windows (XAMPP/WAMP)

Editar php.ini e descomentar:

Copied!

extension=bcmath
extension=json

extension=bcmath
extension=json

#Problema: Detecção de região incorreta

Em desenvolvimento local:

Copied!

# Force uma região específica
LUSOPHONE_FORCE_REGION=MZ

# Force uma região específica
LUSOPHONE_FORCE_REGION=MZ

Em produção:

Copied!

# Verificar headers HTTP
php artisan lusophone:detect --debug

# Verificar headers HTTP
php artisan lusophone:detect --debug

#Problema: Traduções não aparecem

Copied!

# Publicar e reconfigurar
php artisan vendor:publish --tag=lusophone-lang --force
php artisan config:clear
php artisan view:clear

# Publicar e reconfigurar
php artisan vendor:publish --tag=lusophone-lang --force
php artisan config:clear
php artisan view:clear

#Configuração Avançada

#Ambiente Docker

Dockerfile:

Copied!

FROM php:8.1-fpm
 
# Instalar extensões necessárias
RUN docker-php-ext-install bcmath
 
# Instalar Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
 
# Copiar aplicação
WORKDIR /var/www
COPY . .
 
# Instalar dependências
RUN composer install --no-dev --optimize-autoloader

FROM php:8.1-fpm

# Instalar extensões necessárias
RUN docker-php-ext-install bcmath

# Instalar Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Copiar aplicação
WORKDIR /var/www
COPY . .

# Instalar dependências
RUN composer install --no-dev --optimize-autoloader

#Laravel Sail

Adicionar ao docker-compose.yml:

Copied!

services:
    laravel.test:
        environment:
            - LUSOPHONE_DEFAULT_REGION=MZ
            - LUSOPHONE_AUTO_DETECT=true

services:
    laravel.test:
        environment:
            - LUSOPHONE_DEFAULT_REGION=MZ
            - LUSOPHONE_AUTO_DETECT=true

#Configuração de Produção

Otimizações recomendadas:

Copied!

# Produção
APP_ENV=production
LUSOPHONE_AUTO_DETECT=true
LUSOPHONE_AUTO_SET_LOCALE=true
 
# Cache de configuração

# Produção
APP_ENV=production
LUSOPHONE_AUTO_DETECT=true
LUSOPHONE_AUTO_SET_LOCALE=true

# Cache de configuração

Copied!

# Deploy de produção
php artisan config:cache
php artisan route:cache
php artisan view:cache
composer install --no-dev --optimize-autoloader

# Deploy de produção
php artisan config:cache
php artisan route:cache
php artisan view:cache
composer install --no-dev --optimize-autoloader

#Próximos Passos

Agora que tem o Laravel Lusophone instalado:

Instalação concluída! 🎉 A sua aplicação Laravel agora suporta todos os países lusófonos automaticamente.

Instalação

É oficial! #LARAVELLUSOPHONE v1.0 chegou com tudo!

On this page

#Instalação

#Requisitos

#Requisitos Mínimos

#Ambientes Testados

#Instalação Via Composer

#1. Instalação Básica

#2. Verificação da Instalação

#3. Teste Rápido

#Configuração Automática vs Manual

#⚡ Configuração Automática (Recomendada)

#🔧 Configuração Manual

Publicar Configurações

Publicar Traduções (Opcional)

Configurar .env

#Integração com Laravel Breeze

#Instalação Simultânea (Novo Projeto)

#Projeto Existente com Breeze

#Integração com Laravel Jetstream

#Com Livewire

#Com Inertia.js

#Verificação da Instalação

#1. Teste de Detecção

#2. Teste de Validação

#3. Teste de Formatação

#4. Teste Completo

#Resolução de Problemas

#Erro: "Class 'ArnaldoTomo\LaravelLusophone...' not found"

#Erro: Extensões PHP em falta

Ubuntu/Debian

CentOS/RHEL

macOS (Homebrew)

Windows (XAMPP/WAMP)

#Problema: Detecção de região incorreta

Em desenvolvimento local:

Em produção:

#Problema: Traduções não aparecem

#Configuração Avançada

#Ambiente Docker

#Laravel Sail

#Configuração de Produção

#Próximos Passos