구성

• 소개
• 환경 구성
  • 환경 변수 타입
  • 환경 구성 검색
  • 현재 환경 결정
  • 환경 파일 암호화
• 구성 값 접근
• 구성 캐싱
• 구성 게시
• 디버그 모드
• 유지보수 모드

소개

Laravel 프레임워크의 모든 구성 파일은 config 디렉토리에 저장됩니다. 각 옵션은 문서화되어 있으므로 파일을 살펴보고 사용 가능한 옵션에 익숙해지십시오.

이러한 구성 파일을 사용하면 데이터베이스 연결 정보, 메일 서버 정보는 물론 애플리케이션 시간대 및 암호화 키와 같은 다양한 다른 핵심 구성 값을 구성할 수 있습니다.

about 명령어

Laravel은 about Artisan 명령어를 통해 애플리케이션의 구성, 드라이버 및 환경에 대한 개요를 표시할 수 있습니다.

php artisan about

애플리케이션 개요 출력의 특정 섹션에만 관심이 있는 경우 --only 옵션을 사용하여 해당 섹션을 필터링할 수 있습니다.

php artisan about --only=environment

또는 특정 구성 파일의 값을 자세히 탐색하려면 config:show Artisan 명령어를 사용할 수 있습니다.

php artisan config:show database

환경 설정

애플리케이션이 실행되는 환경에 따라 다른 구성 값을 사용하는 것이 유용한 경우가 많습니다. 예를 들어, 로컬에서는 프로덕션 서버에서 사용하는 것과 다른 캐시 드라이버를 사용하고 싶을 수 있습니다.

이를 간단하게 처리하기 위해 Laravel은 DotEnv PHP 라이브러리를 활용합니다. 새로 설치된 Laravel에서 애플리케이션의 루트 디렉토리에는 많은 일반적인 환경 변수를 정의하는 .env.example 파일이 있습니다. Laravel 설치 프로세스 중에 이 파일은 자동으로 .env로 복사됩니다.

Laravel의 기본 .env 파일에는 애플리케이션이 로컬에서 실행 중인지 아니면 프로덕션 웹 서버에서 실행 중인지에 따라 다를 수 있는 몇 가지 일반적인 구성 값이 포함되어 있습니다. 이러한 값은 Laravel의 env 함수를 사용하여 config 디렉토리 내의 구성 파일에서 읽습니다.

팀과 함께 개발하는 경우 .env.example 파일을 애플리케이션에 계속 포함하고 업데이트하는 것이 좋습니다. 예제 구성 파일에 자리 표시자 값을 넣으면 팀의 다른 개발자가 애플리케이션을 실행하는 데 필요한 환경 변수를 명확하게 확인할 수 있습니다.

환경 파일 보안

애플리케이션을 사용하는 각 개발자/서버마다 다른 환경 구성이 필요할 수 있으므로 .env 파일은 애플리케이션의 소스 제어에 커밋해서는 안 됩니다. 또한 침입자가 소스 제어 저장소에 액세스하는 경우 중요한 자격 증명이 노출될 수 있으므로 보안 위험이 될 수 있습니다.

그러나 Laravel의 기본 제공 환경 암호화를 사용하여 환경 파일을 암호화할 수 있습니다. 암호화된 환경 파일은 소스 제어에 안전하게 배치할 수 있습니다.

추가 환경 파일

애플리케이션의 환경 변수를 로드하기 전에 Laravel은 APP_ENV 환경 변수가 외부에서 제공되었는지 또는 --env CLI 인수가 지정되었는지 확인합니다. 그렇다면 Laravel은 .env.[APP_ENV] 파일이 있으면 로드하려고 시도합니다. 존재하지 않으면 기본 .env 파일이 로드됩니다.

환경 변수 타입

.env 파일의 모든 변수는 일반적으로 문자열로 구문 분석되므로 env() 함수에서 더 넓은 범위의 타입을 반환할 수 있도록 몇 가지 예약된 값이 생성되었습니다.

공백이 포함된 값을 가진 환경 변수를 정의해야 하는 경우 값을 큰따옴표로 묶으면 됩니다.

APP_NAME="내 애플리케이션"

환경 설정 검색하기

.env 파일에 나열된 모든 변수는 애플리케이션이 요청을 받을 때 $_ENV PHP 슈퍼 전역 변수에 로드됩니다. 그러나 구성 파일에서 이러한 변수로부터 값을 검색하기 위해 env 함수를 사용할 수 있습니다. 실제로 Laravel 구성 파일을 살펴보면 많은 옵션이 이미 이 함수를 사용하고 있음을 알 수 있습니다.

'debug' => env('APP_DEBUG', false),

env 함수에 전달되는 두 번째 값은 "기본값"입니다. 이 값은 지정된 키에 대한 환경 변수가 존재하지 않는 경우 반환됩니다.

현재 환경 결정하기

현재 애플리케이션 환경은 .env 파일의 APP_ENV 변수를 통해 결정됩니다. App facade에서 environment 메서드를 통해 이 값에 액세스할 수 있습니다.

use Illuminate\Support\Facades\App;
 
$environment = App::environment();

또한 environment 메서드에 인수를 전달하여 환경이 주어진 값과 일치하는지 여부를 확인할 수 있습니다. 이 메서드는 환경이 주어진 값 중 하나와 일치하면 true를 반환합니다.

if (App::environment('local')) {
    // 환경이 로컬입니다.
}
 
if (App::environment(['local', 'staging'])) {
    // 환경이 로컬 또는 스테이징입니다...
}

환경 파일 암호화하기

암호화되지 않은 환경 파일은 소스 제어에 저장해서는 안 됩니다. 그러나 Laravel을 사용하면 환경 파일을 암호화하여 애플리케이션의 나머지 부분과 함께 안전하게 소스 제어에 추가할 수 있습니다.

암호화

환경 파일을 암호화하려면 env:encrypt 명령을 사용할 수 있습니다.

php artisan env:encrypt

env:encrypt 명령어를 실행하면 .env 파일이 암호화되고 암호화된 내용은 .env.encrypted 파일에 저장됩니다. 복호화 키는 명령어 출력에 표시되며 안전한 비밀번호 관리자에 저장해야 합니다. 사용자 지정 암호화 키를 제공하려면 명령어를 호출할 때 --key 옵션을 사용하면 됩니다.

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

.env 및 .env.staging과 같이 여러 환경 파일이 있는 경우 --env 옵션을 통해 환경 이름을 제공하여 암호화해야 하는 환경 파일을 지정할 수 있습니다.

php artisan env:encrypt --env=staging

복호화

환경 파일을 복호화하려면 env:decrypt 명령어를 사용할 수 있습니다. 이 명령어에는 복호화 키가 필요하며, Laravel은 LARAVEL_ENV_ENCRYPTION_KEY 환경 변수에서 복호화 키를 가져옵니다.

php artisan env:decrypt

또는 --key 옵션을 통해 키를 명령어에 직접 제공할 수 있습니다.

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

env:decrypt 명령어가 호출되면 Laravel은 .env.encrypted 파일의 내용을 복호화하고 복호화된 내용을 .env 파일에 저장합니다.

사용자 지정 암호화 암호를 사용하기 위해 --cipher 옵션을 env:decrypt 명령어에 제공할 수 있습니다.

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

애플리케이션에 .env 및 .env.staging과 같이 여러 환경 파일이 있는 경우 --env 옵션을 통해 환경 이름을 제공하여 복호화해야 하는 환경 파일을 지정할 수 있습니다.

php artisan env:decrypt --env=staging

기존 환경 파일을 덮어쓰려면 env:decrypt 명령어에 --force 옵션을 제공하면 됩니다.

php artisan env:decrypt --force

설정 값 접근하기

애플리케이션 어디에서든 Config 파사드 또는 전역 config 함수를 사용하여 설정 값에 쉽게 접근할 수 있습니다. 설정 값은 접근하려는 파일 이름과 옵션이 포함된 "점" 구문을 사용하여 접근할 수 있습니다. 설정 옵션이 존재하지 않는 경우 반환될 기본 값을 지정할 수도 있습니다.

use Illuminate\Support\Facades\Config;
 
$value = Config::get('app.timezone');
 
$value = config('app.timezone');
 
// 설정 값이 존재하지 않는 경우 기본 값 검색...
$value = config('app.timezone', 'Asia/Seoul');

런타임에 설정 값을 설정하려면 Config 파사드의 set 메서드를 호출하거나 config 함수에 배열을 전달할 수 있습니다.

Config::set('app.timezone', 'America/Chicago');
 
config(['app.timezone' => 'America/Chicago']);

정적 분석을 지원하기 위해 Config 파사드는 유형화된 설정 검색 메서드도 제공합니다. 검색된 설정 값이 예상 유형과 일치하지 않으면 예외가 발생합니다.

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');

설정 캐싱

애플리케이션 속도를 향상시키려면 config:cache Artisan 명령어를 사용하여 모든 설정 파일을 단일 파일로 캐시해야 합니다. 이렇게 하면 애플리케이션의 모든 설정 옵션이 프레임워크에서 빠르게 로드할 수 있는 단일 파일로 결합됩니다.

일반적으로 프로덕션 배포 프로세스의 일부로 php artisan config:cache 명령을 실행해야 합니다. 애플리케이션 개발 과정에서 설정 옵션을 자주 변경해야 하므로 로컬 개발 중에는 명령을 실행해서는 안 됩니다.

설정이 캐시되면 요청 또는 Artisan 명령 중에 애플리케이션의 .env 파일이 프레임워크에 의해 로드되지 않습니다. 따라서 env 함수는 외부 시스템 수준 환경 변수만 반환합니다.

이러한 이유로 애플리케이션의 설정(config) 파일 내에서만 env 함수를 호출해야 합니다. Laravel의 기본 설정 파일을 살펴보면 이에 대한 많은 예시를 볼 수 있습니다. 설정 값은 위에 설명된 config 함수를 사용하여 애플리케이션 어디에서든 접근할 수 있습니다.

캐시된 설정을 제거하는 데는 config:clear 명령을 사용할 수 있습니다.

php artisan config:clear

설정 게시

대부분의 Laravel 설정 파일은 이미 애플리케이션의 config 디렉토리에 게시되어 있습니다. 하지만 cors.php 및 view.php와 같은 특정 설정 파일은 대부분의 애플리케이션에서 수정할 필요가 없으므로 기본적으로 게시되지 않습니다.

그러나 기본적으로 게시되지 않은 설정 파일을 게시하려면 config:publish Artisan 명령어를 사용할 수 있습니다.

php artisan config:publish
 
php artisan config:publish --all

디버그 모드

config/app.php 설정 파일의 debug 옵션은 사용자에게 실제로 표시되는 오류에 대한 정보의 양을 결정합니다. 기본적으로 이 옵션은 .env 파일에 저장된 APP_DEBUG 환경 변수의 값을 따르도록 설정되어 있습니다.

유지 보수 모드

애플리케이션이 유지 보수 모드에 있으면 애플리케이션에 대한 모든 요청에 대해 사용자 정의 보기가 표시됩니다. 이를 통해 업데이트 중이거나 유지 보수를 수행할 때 애플리케이션을 쉽게 "비활성화"할 수 있습니다. 유지 보수 모드 확인은 애플리케이션의 기본 미들웨어 스택에 포함되어 있습니다. 애플리케이션이 유지 보수 모드에 있으면 503 상태 코드로 Symfony\Component\HttpKernel\Exception\HttpException 인스턴스가 throw됩니다.

유지 보수 모드를 활성화하려면 down Artisan 명령을 실행하세요.

php artisan down

모든 유지 보수 모드 응답과 함께 Refresh HTTP 헤더를 보내려면 down 명령을 호출할 때 refresh 옵션을 제공하면 됩니다. Refresh 헤더는 지정된 초 후 페이지를 자동으로 새로 고치도록 브라우저에 지시합니다.

php artisan down --refresh=15

또한 down 명령에 retry 옵션을 제공할 수도 있습니다. 이 옵션은 Retry-After HTTP 헤더 값으로 설정되지만 브라우저에서는 일반적으로 이 헤더를 무시합니다.

php artisan down --retry=60

유지 보수 모드 우회

비밀 토큰을 사용하여 유지 보수 모드를 우회할 수 있도록 하려면 secret 옵션을 사용하여 유지 보수 모드 우회 토큰을 지정할 수 있습니다.

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

애플리케이션을 유지보수 모드로 전환한 후, 이 토큰과 일치하는 애플리케이션 URL로 이동하면 Laravel이 브라우저에 유지보수 모드 우회 쿠키를 발급합니다.

https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515

Laravel이 비밀 토큰을 생성하도록 하려면 with-secret 옵션을 사용할 수 있습니다. 애플리케이션이 유지보수 모드로 전환되면 비밀 토큰이 표시됩니다.

php artisan down --with-secret

이 숨겨진 경로에 접근하면 애플리케이션의 / 경로로 리디렉션됩니다. 쿠키가 브라우저에 발급되면 마치 유지보수 모드가 아닌 것처럼 애플리케이션을 정상적으로 탐색할 수 있습니다.

여러 서버에서 유지보수 모드

기본적으로 Laravel은 파일 기반 시스템을 사용하여 애플리케이션이 유지보수 모드인지 여부를 결정합니다. 즉, 유지보수 모드를 활성화하려면 애플리케이션을 호스팅하는 각 서버에서 php artisan down 명령을 실행해야 합니다.

또는 Laravel은 유지보수 모드를 처리하기 위한 캐시 기반 방법을 제공합니다. 이 방법은 하나의 서버에서만 php artisan down 명령을 실행하면 됩니다. 이 접근 방식을 사용하려면 애플리케이션의 config/app.php 파일에서 "driver" 설정을 cache로 수정하십시오. 그런 다음 모든 서버에서 접근할 수 있는 캐시 store를 선택하십시오. 이렇게 하면 모든 서버에서 유지보수 모드 상태가 일관되게 유지됩니다.

'maintenance' => [
    'driver' => 'cache',
    'store' => 'database',
],

유지 보수 모드 뷰 사전 렌더링

배포 중에 php artisan down 명령어를 사용하는 경우, Composer 종속성 또는 기타 인프라 구성 요소가 업데이트되는 동안 사용자가 애플리케이션에 액세스하면 여전히 오류가 발생할 수 있습니다. 이는 Laravel 프레임워크의 상당 부분이 애플리케이션이 유지 보수 모드인지 확인하고 템플릿 엔진을 사용하여 유지 보수 모드 뷰를 렌더링하기 위해 부팅되어야 하기 때문입니다.

이러한 이유로 Laravel에서는 요청 주기 초기에 반환될 유지 보수 모드 뷰를 사전 렌더링할 수 있습니다. 이 뷰는 애플리케이션 종속성이 로드되기 전에 렌더링됩니다. down 명령어의 render 옵션을 사용하여 원하는 템플릿을 사전 렌더링할 수 있습니다:

php artisan down --render="errors::503"

유지 보수 모드 요청 리디렉션

유지 보수 모드에서 Laravel은 사용자가 액세스하려는 모든 애플리케이션 URL에 대해 유지 보수 모드 뷰를 표시합니다. 원하는 경우 Laravel에 모든 요청을 특정 URL로 리디렉션하도록 지시할 수 있습니다. 이는 redirect 옵션을 사용하여 수행할 수 있습니다. 예를 들어 모든 요청을 / URI로 리디렉션할 수 있습니다:

php artisan down --redirect=/

유지 보수 모드 비활성화

유지 보수 모드를 비활성화하려면 up 명령어를 사용합니다:

php artisan up

유지 관리 모드 및 큐

애플리케이션이 유지 관리 모드인 동안에는 대기열 작업이 처리되지 않습니다. 애플리케이션이 유지 관리 모드에서 해제되면 작업이 정상적으로 계속 처리됩니다.

유지 관리 모드의 대안

유지 관리 모드는 애플리케이션에 몇 초의 다운타임을 필요로 하므로 Laravel로 무중단 배포를 달성하기 위해 Laravel Vapor 및 Envoyer와 같은 대안을 고려해 보세요.