Laravel 설정

Configuration

설정

• https://laravel.com/docs/11.x/configuration

1 소개

Laravel 프레임워크의 모든 설정 파일은 config 디렉토리에 저장됩니다. 각 옵션은 문서화되어 있으므로 파일을 살펴보면서 사용가능한 옵션을 익히는 것이 좋습니다.

이 설정 파일들을 통해 데이터베이스 연결 정보, 메일 서버 정보 등 다양한 핵심 설정 값들을 설정할 수 있습니다. 예를 들어, 애플리케이션의 시간대나 암호화 키 등을 설정할 수 있습니다.

about 명령어

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

php artisan about

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

php artisan about --only=environment

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

php artisan config:show database

2 환경 설정

애플리케이션이 실행되는 환경에 따라 다른 설정 값을 사용하는 것이 종종 유용합니다. 예를 들어, 로컬 환경에서는 다른 캐시 드라이버를 사용하고 프로덕션 서버에서는 또 다른 캐시 드라이버를 사용하고자 할 수 있습니다.

이를 간편하게 하기 위해, Laravel은 DotEnv PHP 라이브러리를 활용합니다. 새로운 Laravel 설치에서는 애플리케이션의 루트 디렉토리에 .env.example 파일이 포함되어 있으며, 이 파일에는 많은 일반적인 환경변수가 정의되어 있습니다. Laravel 설치 과정에서 이 파일은 자동으로 .env 파일로 복사됩니다.

Laravel의 기본 .env 파일은 애플리케이션이 로컬에서 실행 중인지 프로덕션 웹 서버에서 실행 중인지에 따라 달라질 수 있는 공통적인 설정 값을 포함하고 있습니다. 이러한 값들은 Laravel의 env 함수를 사용하여 config 디렉토리 내의 설정 파일들에서 읽어들입니다.

팀과 함께 개발하는 경우, .env.example 파일을 계속 포함하고 업데이트하는 것이 좋습니다. 예제 설정 파일에 플레이스홀더 값을 넣음으로써, 팀의 다른 개발자들이 애플리케이션을 실행하는 데 필요한 환경변수가 무엇인지 명확하게 볼 수 있습니다.

Note

.env 파일의 모든 변수는 서버 수준 또는 시스템 수준의 환경변수와 같은 외부 환경변수에 의해 재정의될 수 있습니다.

2.1 환경변수 타입

.env 파일의 모든 변수는 일반적으로 문자열로 파싱됩니다. 그러나 env() 함수에서 더 다양한 유형을 반환할 수 있도록 몇 가지 예약된 값이 만들어졌습니다:

.env 값	env() 값
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string)
(empty)	(string)
null	(null) null
(null)	(null) null

공백을 포함하는 값으로 환경변수를 정의해야 하는 경우, 값을 큰따옴표로 감싸서 사용할 수 있습니다:

APP_NAME="My Application"

2.2 환경 설정 조회하기

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

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

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

2.3 현재 환경 결정

현재 애플리케이션 환경은 .env 파일의 APP_ENV 변수를 통해 결정됩니다. 이 값을 App 파사드의environment 메소드를 통해 접근할 수 있습니다:

use Illuminate\Support\Facades\App;

$environment = App::environment();

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

if (App::environment('local')) {
    // 현재 환경은 local입니다.
}

if (App::environment(['local', 'staging'])) {
    // 현재 환경은 local이거나 staging입니다.
}

Note

현재 애플리케이션 환경 감지는 서버 수준의 APP_ENV 환경변수를 정의하여 재정의할 수 있습니다.

2.4 환경 파일 암호화하기

암호화되지 않은 환경 파일은 소스 컨트롤에 저장해서는 안 됩니다. 하지만 Laravel에서는 환경 파일을 암호화할 수 있으므로 애플리케이션의 나머지 부분과 함께 소스 컨트롤에 안전하게 추가할 수 있습니다.

3 설정 값 접근하기

애플리케이션의 어디에서나 Config 파사드 또는 전역 config 함수를 사용하여 설정 값을 쉽게 접근할 수 있습니다. 설정 값은 "점(dot)" 구문을 사용하여 접근할 수 있으며, 여기에는 접근하고자 하는 파일 이름과 옵션이 포함됩니다. 기본값도 지정할 수 있으며, 설정 옵션이 존재하지 않을 경우 해당 기본값이 반환됩니다.

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');

4 캐싱 설정

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

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

설정이 캐시되면, 요청이 오거나 Artisan 명령어를 수행하는 경우에 .env 파일이 프레임워크에 의해 로드되지 않으므로, env 함수는 외부, 시스템 수준의 환경변수만 반환합니다.

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

config:clear 명령어는 캐시된 설정을 삭제하는 데 사용됩니다:

php artisan config:clear

Warning

배포 과정에서 config:cache 명령어를 실행하는 경우, env 함수는 설정 파일 내에서만 호출하도록 해야 합니다. 설정이 캐시된 후에는 .env 파일이 로드되지 않으므로 env 함수는 외부, 시스템 수준의 환경변수만 반환합니다.

5 퍼블리싱 설정

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

하지만, 기본적으로 퍼블리싱되지 않은 설정 파일을 퍼블리싱하려면 config:publish Artisan 명령어를 사용할 수 있습니다:

php artisan config:publish

php artisan config:publish --all

6 디버그 모드

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

Warning

로컬 개발 환경에서는 APP_DEBUG 환경 변수를 true로 세팅해야 합니다. 프로덕션 환경에서는 이 값을 항상 false로 세팅해야 합니다. 프로덕션 환경에서 이 변수가 true로 설정되어 있으면 애플리케이션의 최종사용자에게 민감한 설정 값이 노출될 위험이 있습니다.

7 유지보수 모드

애플리케이션이 유지보수 모드일 때, 애플리케이션으로 들어오는 모든 요청에 대해 커스텀 뷰가 표시됩니다. 이를 통해 애플리케이션을 업데이트하거나 유지보수 작업을 수행하는 동안 애플리케이션을 "비활성화"하기가 쉬워집니다. 유지보수 모드 확인은 애플리케이션의 기본 미들웨어 스택에 포함되어 있습니다. 애플리케이션이 유지보수 모드에 있으면, 상태 코드 503과 함께 Symfony\Component\HttpKernel\Exception\HttpException 인스턴스가 발생합니다.

유지보수 모드를 활성화하려면, down Artisan 명령어를 실행하십시오:

php artisan down

만약 모든 유지보수 모드 응답에 Refresh HTTP 헤더를 보내고 싶다면, down 명령어를 호출할 때 refresh 옵션을 붙일 수 있습니다. Refresh 헤더는 브라우저에게 지정한 초(seconds) 수 후에 페이지를 자동으로 새로고침하도록 지시합니다:

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"

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

php artisan down --with-secret

이 숨겨진 라우트에 접근하면, 애플리케이션의 루트(/) 라우트로 리디렉션됩니다. 쿠키가 브라우저에 발급된 후에는 유지보수 모드가 아닌 것처럼 애플리케이션을 정상적으로 브라우즈할 수 있습니다.

Note

유지보수 모드 비밀은 일반적으로 영숫자 문자와 선택적으로 대시(-)로 구성되어야 합니다. ?, &와 같이 URL에서 특별한 의미를 가지는 문자는 사용하지 않는 것이 좋습니다.