Como usar variáveis de ambiente do PHP no Laravel

Este artigo foi atualizado em julho de 2025

As variáveis de ambiente são essenciais no Laravel para gerenciar as configurações em diferentes ambientes (local, de teste e de produção). O Laravel armazena essas configurações em um .env arquivo, mantendo os dados confidenciais fora do controle de versão. Isso garante flexibilidade e segurança na implantação de Applications.

Neste guia, vamos mostrar como configurar e usar variáveis de ambiente em um ambiente de desenvolvimento — neste caso, porque os ambientes de produção e de teste têm .env arquivos que devem ser gerenciados por meio de uma plataforma de hospedagem gerenciada, como a Platform.sh, Laravel Forgeou Laravel Cloud.

Configurando variáveis de ambiente

Criação e uso do .env Arquivo

O Laravel inclui um .env.example arquivo por padrão. Para começar a usar variáveis de ambiente, crie um novo .env arquivo copiando o arquivo de exemplo:

Em seguida, abra o .env arquivo e defina as configurações do seu aplicativo:

APP_NAME=VonageVerifyApp
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

VONAGE_API_KEY=your_api_key
VONAGE_API_SECRET=your_api_secret

Após modificar o .env arquivo, limpe o cache de configuração para aplicar as alterações:

Acesso às variáveis de ambiente no Laravel

Usando o env() Ajudante

O Laravel oferece um env() função auxiliar para recuperar variáveis de ambiente:

$apiKey = env('VONAGE_API_KEY');

Importante: Use env() apenas em arquivos de configuração. Para manter a lógica da aplicação limpa e fácil de manter, recupere as configurações por meio do config() . Isso é especialmente importante, pois o Laravel armazena em cache o arquivo de variáveis de ambiente e não invalida automaticamente o cache quando uma variável é alterada no arquivo.

Como usar os arquivos de configuração do Laravel

Os arquivos de configuração do Laravel (localizados no config/ diretório) são a melhor maneira de gerenciar as configurações do ambiente. O contêiner de serviços de configuração do Laravel lê automaticamente cada arquivo dentro do diretório config. Portanto, para adicionar sua chave e seu segredo de API da Vonage, crie um novo arquivo no diretório config e nomeie-o vonage.php. Isso deve retornar um array com sua chave e seu segredo de API.

Por exemplo, em config/services.php, é possível fazer referência a variáveis de ambiente para a Verify API do Vonage Verify:

'vonage' => [
    'api_key' => env('VONAGE_API_KEY'),
    'api_secret' => env('VONAGE_API_SECRET'),
],

Para recuperar esses valores em seu aplicativo, use:

$apiKey = config('vonage.api_key');
$apiSecret = config('vonage.api_secret');

Uso de variáveis de ambiente na Verify API

Com as variáveis de ambiente devidamente configuradas, agora você pode integrar a Verify API à sua aplicação Laravel. Mostraremos como fazer isso manualmente, mas, ao desenvolver sua aplicação, provavelmente você vai querer criar um serviço que inicie automaticamente sua aplicação no contêiner de serviços. Você pode saber mais sobre como fazer isso na documentação do Laravel.

Exemplo: Envio de uma solicitação de verificação

use Vonage\Client;
use Vonage\Client\Credentials\Basic;

use Vonage\Verify2\Request\SMSRequest;
$apiKey = config('vonage.api_key');
$apiSecret = config('vonage.api_secret');

$credentials = new Basic($apiKey, $apiSecret);
$client = new Client($credentials);

$verification = new SmsRequest('+14155550123', 'acme-company');

$response = $client->verify()->start($verification);

echo "Request ID: " . $response->getRequestId();

Exemplo: Verificação de um código de verificação

$requestId = 'VERIFY_REQUEST_ID';
$code = 'VONAGE_VERIFY_CODE; // Code entered by the user

try {
$response = $client->verify2()->check($requestId, $code);
echo $response;} catch ($exception) {
echo $exception->getMessage();
}

Configuração de parâmetros específicos do ambiente

O Laravel permite que você personalize as configurações para diferentes ambientes. Por exemplo, em config/logging.php, você pode definir diferentes níveis de log com base no ambiente. O segundo argumento da função auxiliar env() é o padrão; portanto, certifique-se de saber onde está definindo isso:

'log_level' => env('LOG_LEVEL', 'debug'),

Defina o nível de log nos seus .env arquivos:

LOG_LEVEL=debug  # Local Development
LOG_LEVEL=error  # Production

Essa abordagem permite modificar o comportamento do aplicativo sem alterar o código.

Melhorando o desempenho com o armazenamento em cache de configurações

Em ambientes de produção, armazene em cache suas configurações para melhorar o desempenho:

php artisan config:cache

Após executar esse comando, o Laravel deixa de ler o .env arquivo e passa a usar a configuração armazenada em cache. Se você fizer alterações .env, limpe o cache antes de aplicá-las:

php artisan config:clear

Melhores práticas de segurança

Para manter os dados confidenciais protegidos, siga estas práticas recomendadas:

• Nunca faça o commit do seu .env arquivo — adicione-o ao .gitignore.

• Utilize arquivos de ambiente distintos para os ambientes local, de teste e de produção.

• Nunca insira chaves de API ou segredos diretamente no código do seu aplicativo.

• Use config() em vez de env() na lógica do aplicativo para evitar problemas com o cache de configuração.

• Considere o uso de ferramentas de gerenciamento de segredos, como o AWS Secrets Manager, o HashiCorp Vault ou o gerenciamento de ambientes Docker/Kubernetes, para garantir a segurança da produção.

Solução de problemas com variáveis de ambiente

Se suas variáveis de ambiente não estiverem sendo carregadas corretamente, tente limpá-las e atualizar o cache:

php artisan config:clear  
php artisan config:cache  

Conclusão

E é isso! O uso de variáveis de ambiente no Laravel ajuda a gerenciar as configurações de forma eficiente, ao mesmo tempo em que mantém os dados confidenciais protegidos.