설정

모든 프레임워크는 설정 파일을 사용하여 다양한 매개변수와 초기 설정을 정의합니다. CodeIgniter 설정 파일은 필요한 설정이 public 속성인 간단한 클래스를 정의합니다.

다른 많은 프레임워크와 달리 CodeIgniter의 설정 가능한 항목들은 하나의 파일에 모여 있지 않습니다. 대신 설정 가능한 항목이 필요한 각 클래스는 해당 클래스와 동일한 이름의 설정 파일을 가집니다. 애플리케이션 설정 파일은 app/Config 폴더에서 찾을 수 있습니다.

설정 클래스란 무엇입니까?

설정 클래스는 시스템 기본 설정 값을 정의하는 데 사용됩니다. 시스템 설정 값은 일반적으로 static입니다. 설정 클래스는 각 사용자의 개별 설정에 응답하는 것이 아니라, 애플리케이션이 동작하는 방식을 구성하는 설정을 유지하기 위한 것입니다.

설정 클래스를 인스턴스화할 때 설정된 값을 이후 실행 중에 변경하는 것은 권장되지 않습니다. 즉, 설정 클래스를 불변(immutable) 또는 읽기 전용(readonly) 클래스로 취급하는 것이 좋습니다. Config Caching을 활용하는 경우 이는 특히 중요합니다.

설정 값은 클래스 파일에 하드코딩하거나 인스턴스화 시 환경 변수에서 가져올 수 있습니다.

설정 파일 작업 

설정 객체 가져오기 

여러 가지 방법으로 클래스의 설정 파일에 접근할 수 있습니다.

new 키워드

new 키워드를 사용하여 인스턴스를 생성합니다.

<?php

// Creating new configuration object by hand
$config = new \Config\Pager();

config()

config() 함수를 사용합니다.

<?php

// Get shared instance with config function
$config = config('Pager');

// Access config class with namespace
$config = config('Config\\Pager');
$config = config(\Config\Pager::class);

// Creating a new object with config function
$config = config('Pager', false);

네임스페이스가 지정되지 않으면 먼저 app/Config 폴더에서 파일을 찾고, 찾지 못한 경우 정의된 모든 네임스페이스의 Config 폴더에서 찾습니다.

CodeIgniter와 함께 제공되는 모든 설정 파일은 Config 네임스페이스로 지정되어 있습니다. 애플리케이션에서 이 네임스페이스를 사용하면 파일의 위치를 정확히 알 수 있으므로 최상의 성능을 제공합니다.

참고

v4.4.0 이전에는 config(\Acme\Blog\Config\Blog::class)와 같이 완전히 정규화된(fully qualified) 클래스 이름을 지정하더라도, 동일한 짧은 클래스 이름(short class name)을 가진 클래스가 존재하면 config()가 app/Config/에서 해당 파일을 찾았습니다. 이 동작은 v4.4.0에서 수정되어, 지정한 인스턴스를 반환합니다.

설정 속성 가져오기 

모든 설정 객체의 속성은 public이므로, 다른 속성과 마찬가지로 설정에 접근할 수 있습니다.

<?php

$config = config('Pager');
// Access settings as object properties
$pageSize = $config->perPage;

설정 파일 생성 

새 설정이 필요한 경우 먼저 원하는 위치에 새 파일을 만듭니다. 기본 파일 위치(대부분의 경우 권장되는 위치)는 app/Config입니다.

다른 네임스페이스를 사용하면 어느 Config 폴더에든 설정 파일을 둘 수 있습니다.

클래스는 적절한 네임스페이스를 사용해야 하며, 환경별 설정을 받을 수 있도록 CodeIgniter\Config\BaseConfig를 확장해야 합니다.

클래스를 정의하고, 설정을 나타내는 public 속성들로 채웁니다.

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class CustomClass extends BaseConfig
{
    public $siteName  = 'My Great Site';
    public $siteEmail = 'webmaster@example.com';
    // ...
}

환경 변수 

오늘날 애플리케이션 설정의 모범 사례 중 하나는 환경 변수를 사용하는 것입니다. 그 이유 중 하나는, 코드를 변경하지 않고도 배포 환경마다 환경 변수를 쉽게 변경할 수 있기 때문입니다. 설정은 배포에 따라 많이 달라질 수 있지만 코드는 그렇지 않습니다. 예를 들어 개발자의 로컬 머신이나 프로덕션 서버와 같이 여러 환경에서는 일반적으로 각 환경마다 서로 다른 설정 값이 필요합니다.

환경 변수는 비밀번호, API 키 등 그 밖의 민감한 데이터와 같은 비공개 정보에도 사용해야 합니다.

Dotenv 파일 

CodeIgniter는 “dotenv” 파일을 사용하여 환경 변수를 간단하고 손쉽게 설정할 수 있게 해줍니다. 이 용어는 “env”라는 텍스트 앞에 점(dot)으로 시작하는 파일 이름에서 유래되었습니다.

Dotenv 파일 생성

CodeIgniter는 .env 파일이 app 디렉터리와 함께 프로젝트의 루트에 있을 것으로 예상합니다. CodeIgniter와 함께 배포되는 템플릿 파일이 프로젝트 루트에 env라는 이름으로 위치해 있습니다. (시작 부분에 점(.)이 없는 것을 확인하세요.)

이 파일에는 프로젝트에서 사용할 수 있는 다양한 변수들이 빈 값, 더미 값 또는 기본값이 할당된 상태로 다수 포함되어 있습니다. 템플릿의 이름을 .env로 바꾸거나, .env라는 이름의 복사본을 만들어 이 파일을 애플리케이션의 출발점으로 사용할 수 있습니다.

경고

버전 관리 시스템이 .env 파일을 추적하지 않도록 반드시 확인하세요. git의 경우 이는 .gitignore에 추가하는 것을 의미합니다. 그렇지 않으면 민감한 자격 증명이 외부에 노출될 수 있습니다.

변수 설정

설정은 등호(=)로 구분된 이름/값 쌍의 단순한 모음으로 .env 파일에 저장됩니다.

S3_BUCKET = dotenv
SECRET_KEY = super_secret_key
CI_ENVIRONMENT = development

애플리케이션이 실행되면 .env가 자동으로 로드되고 변수가 환경에 추가됩니다. 이미 환경에 존재하는 변수는 덮어쓰여지지 않습니다.

변수 가져오기

로드된 환경 변수는 getenv(), $_SERVER 또는 $_ENV 중 하나를 사용하여 접근합니다.

<?php

$s3_bucket = getenv('S3_BUCKET');
$s3_bucket = $_ENV['S3_BUCKET'];
$s3_bucket = $_SERVER['S3_BUCKET'];

경고

.env 파일의 설정 값이 $_SERVER와 $_ENV에 추가된다는 점에 주의하세요. 그 부작용으로, 예를 들어 CodeIgniter 애플리케이션이 디버깅 등의 정당한 이유로 var_dump($_ENV) 또는 phpinfo()를 생성하거나, development 환경에서 상세 오류 보고서가 표시되면 민감한 자격 증명이 공개적으로 노출됩니다.

중첩 변수

입력을 줄이기 위해, 파일에 이미 지정한 변수를 ${...} 안에 변수 이름을 감싸서 재사용할 수 있습니다.

BASE_DIR = "/var/webroot/project-root"
CACHE_DIR = "${BASE_DIR}/cache"
TMP_DIR = "${BASE_DIR}/tmp"

네임스페이스가 지정된 변수

동일한 이름을 가진 변수가 여러 개 존재하는 경우가 있습니다. 시스템에는 어떤 것이 올바른 설정인지 판별할 수 있는 방법이 필요합니다. 이 문제는 변수에 “네임스페이스를 지정(namespacing)”하여 해결합니다.

네임스페이스가 지정된 변수는 점 표기법을 사용하여 변수 이름을 한정하므로, 환경에 통합되더라도 고유성을 유지합니다. 이는 식별을 위한 접두사 뒤에 점(.)을 붙이고, 그 뒤에 변수 이름 자체를 작성하는 방식으로 수행됩니다.

// not namespaced variables
name = "George"
db = my_db

// namespaced variables
address.city = "Berlin"
address.country = "Germany"
frontend.db = sales
backend.db = admin
BackEnd.db = admin

네임스페이스 구분자

Docker, CloudFormation 같은 일부 환경에서는 점(.)이 포함된 변수 이름을 허용하지 않습니다. 이 경우 v4.1.5부터는 밑줄(_)을 구분자로 사용할 수도 있습니다.

// namespaced variables with underscore
app_forceGlobalSecureRequests = true
app_CSPEnabled = true

설정 클래스 및 환경 변수 

설정 클래스를 인스턴스화할 때, 모든 네임스페이스가 지정된(namespaced) 환경 변수가 설정 객체의 속성에 병합될 후보로 고려됩니다.

중요

환경 변수 설정으로는 새 속성을 추가하거나 스칼라 값을 배열로 변경할 수 없습니다. 데이터 값 대체용으로서의 환경 변수를 참조하세요.

참고

이 기능은 CodeIgniter\Config\BaseConfig 클래스에서 구현되어 있습니다. 따라서 해당 클래스를 확장하지 않는 app/Config 폴더 내 일부 파일에서는 동작하지 않습니다.

네임스페이스가 지정된 변수의 접두사가 설정 클래스의 네임스페이스와 정확히 일치하는 경우, 설정의 뒷부분(점 뒤)이 설정 속성으로 처리됩니다. 기존 설정 속성과 일치하면 환경 변수의 값이 설정 파일의 해당 값을 대체합니다. 일치하는 항목이 없으면 설정 클래스 속성은 변경되지 않고 그대로 유지됩니다. 이 사용 방식에서 접두사는 클래스의 전체(대소문자 구분) 네임스페이스여야 합니다.

Config\App.forceGlobalSecureRequests = true
Config\App.CSPEnabled = true

참고

네임스페이스 접두사와 속성 이름은 모두 대소문자를 구분합니다. 설정 클래스 파일에 정의된 전체 네임스페이스 및 속성 이름과 정확히 일치해야 합니다.

설정 클래스 이름의 소문자 버전만 사용하는 네임스페이스인 짧은 접두사(short prefix)의 경우에도 마찬가지입니다. 짧은 접두사가 클래스 이름과 일치하면 .env의 값이 설정 파일 값을 대체합니다.

app.forceGlobalSecureRequests = true
app.CSPEnabled = true

v4.1.5부터는 밑줄로도 작성할 수 있습니다.

app_forceGlobalSecureRequests = true
app_CSPEnabled = true

참고

짧은 접두사(short prefix)를 사용할 때에도 속성 이름은 클래스에 정의된 이름과 정확히 일치해야 합니다.

데이터 값 대체용으로서의 환경 변수 

.env에 포함된 환경 변수는 기존 스칼라 값을 대체하는 용도로만 사용된다는 점을 항상 기억해 두는 것이 매우 중요합니다.

간단히 말해, .env에서 값을 설정하여 변경할 수 있는 것은 Config 클래스에 이미 존재하는 속성의 스칼라 값뿐입니다.

Config 클래스에 정의되지 않은 속성은 추가할 수 없습니다.

속성의 스칼라 값을 배열로 변경할 수 없습니다.

기존 배열에는 요소를 추가할 수 없습니다.

예를 들어, .env에 app.myNewConfig = foo를 넣었다고 해서 런타임에 Config\App이 마법처럼 그 속성과 값을 갖게 될 것이라고 기대할 수는 없습니다.

Config\Database에 $default = ['encrypt' => false] 속성이 있는 경우, .env에 database.default.encrypt.ssl_verify = true를 넣더라도 encrypt 값을 배열로 변경할 수는 없습니다. 그렇게 하고 싶다면 Database Configuration을 참조하세요.

환경 변수를 배열로 처리 

네임스페이스가 지정된 환경 변수는 더 나아가 배열로도 처리될 수 있습니다. 접두사가 설정 클래스와 일치하고, 환경 변수 이름의 나머지 부분에 점이 포함되어 있으면 그 부분이 배열 참조로 처리됩니다.

// regular namespaced variable
Config\SimpleConfig.name = George

// array namespaced variables
Config\SimpleConfig.address.city = "Berlin"
Config\SimpleConfig.address.country = "Germany"

이것이 SimpleConfig 설정 객체를 참조한다면, 위의 예는 다음과 같이 처리됩니다.

<?php

$address['city']    = 'Berlin';
$address['country'] = 'Germany';

$address 속성의 다른 요소들은 변경되지 않습니다.

배열 속성 이름을 접두사로 사용할 수도 있습니다. 환경 파일에 다음과 같이 작성되어 있다면 결과는 위와 동일합니다.

// array namespaced variables
Config\SimpleConfig.address.city = "Berlin"
address.country = "Germany"

여러 환경 다루기 

해당 환경의 요구 사항에 맞게 값을 수정한 별도의 .env 파일을 사용하면, 여러 환경을 손쉽게 설정할 수 있습니다.

이 파일에는 애플리케이션에서 사용하는 모든 설정 클래스의 모든 설정 항목이 포함되어서는 안 됩니다. 사실상, 환경에 특화된 항목이나 비밀번호, API 키 등 노출되어서는 안 되는 민감한 정보만 포함해야 합니다. 다만 배포 환경에 따라 달라지는 항목이라면 무엇이든 포함해도 좋습니다.

각 환경마다 .env 파일을 프로젝트의 루트 폴더에 배치합니다. 대부분의 구성에서는 이것이 app 디렉터리와 동일한 수준에 위치하게 됩니다.

버전 관리 시스템으로 .env 파일을 추적하지 마세요. 추적한 상태에서 저장소가 공개되면, 누구나 찾을 수 있는 곳에 민감한 정보를 올려놓는 셈이 됩니다.

Registrar 

“Registrar”는 추가적인 설정 속성을 제공할 수 있는 모든 클래스를 말합니다. Registrar는 런타임 시에 네임스페이스와 파일 전반에 걸쳐 설정을 변경하는 수단을 제공합니다.

Modules에서 자동 검색가 활성화되어 있어야 Registrar가 동작합니다. Registrar는 Config 객체가 인스턴스화될 때 설정 속성을 변경합니다.

참고

이 기능은 CodeIgniter\Config\BaseConfig 클래스에서 구현되어 있습니다. 따라서 해당 클래스를 확장하지 않는 app/Config 폴더 내 일부 파일에서는 동작하지 않습니다.

Registrar를 구현하는 방법은 implicit(암시적)와 explicit(명시적)의 두 가지가 있습니다.

참고

.env의 값은 항상 Registrar보다 우선합니다.

암시적 Registrar 

암시적 Registrar는 모든 Config 클래스의 속성을 변경할 수 있습니다.

모든 네임스페이스는 Config/Registrar.php 파일을 사용해 암시적 Registrar를 정의할 수 있습니다. 이러한 파일은 확장하려는 각 설정 클래스의 이름을 메서드 이름으로 가지는 클래스입니다.

예를 들어, 서드파티 모듈이나 Composer 패키지가 개발자가 이미 설정해 둔 내용을 덮어쓰지 않고 Config\Pager에 추가 템플릿을 제공하고 싶을 수 있습니다. 이 경우 src/Config/Registrar.php에 Pager() 메서드 하나를 가진 Registrar 클래스가 있게 됩니다(대소문자 구분에 주의하세요).

<?php

namespace CodeIgniter\Shield\Config;

class Registrar
{
    public static function Pager(): array
    {
        return [
            'templates' => [
                'module_pager' => 'MyModule\Views\Pager',
            ],
        ];
    }
}

Registrar 메서드는 항상 대상 설정 파일의 속성에 대응하는 키를 가진 배열을 반환해야 합니다. 기존 값들은 병합되며, Registrar의 속성이 덮어쓰기 우선순위를 가집니다.

명시적 Registrar 

명시적 Registrar는 자신이 등록된 Config 클래스의 속성만 변경할 수 있습니다.

설정 파일에서는 원하는 만큼의 Registrar를 명시적으로 지정할 수도 있습니다. 이는 후보 Registrar들의 이름을 담은 배열을 가지는 $registrars 속성을 설정 파일에 추가하는 방식으로 수행합니다.

<?php

namespace Config;

// ...

class MyConfig extends BaseConfig
{
    public static $registrars = [
        SupportingPackageRegistrar::class,
    ];

    // ...
}

이렇게 식별된 클래스들이 “Registrar” 역할을 하려면, 설정 클래스와 동일한 이름의 정적(static) 함수를 가지고 있어야 하며, 속성 설정의 연관 배열을 반환해야 합니다.

설정 객체가 인스턴스화되면, $registrars에 지정된 클래스들을 차례로 순회합니다. 각 클래스에 대해 설정 클래스의 이름과 동일한 메서드를 호출하고, 반환된 속성들을 통합합니다.

이를 위한 샘플 설정 클래스 구성은 다음과 같습니다.

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class MySalesConfig extends BaseConfig
{
    public int $target        = 100;
    public string $campaign   = 'Winter Wonderland';
    public static $registrars = [
        '\App\Models\RegionalSales',
    ];
}

… 그리고 이와 연결된 지역 판매 모델은 다음과 같이 작성할 수 있습니다.

<?php

namespace App\Models;

class RegionalSales
{
    public static function MySalesConfig(): array
    {
        return [
            'target' => 45,
        ];
    }
}

위의 예에서 MySalesConfig가 인스턴스화되면 선언된 세 가지 속성을 갖게 되지만, $target 속성의 값은 RegionalSales를 “Registrar”로 처리하여 재정의됩니다. 결과 설정 속성은 다음과 같습니다.

<?php

$target   = 45;
$campaign = 'Winter Wonderland';

설정 값 확인 

실제 Config 객체의 속성 값은 런타임 시 Registrar, Environment Variables, Config Caching에 의해 변경됩니다.

CodeIgniter에는 실제 Config 값을 확인하기 위해 다음과 같은 명령어가 있습니다.

config:check 

Added in version 4.5.0.

예를 들어, Config\App 인스턴스를 확인하고 싶다면 다음과 같이 실행합니다.

php spark config:check App

출력은 다음과 같습니다.

Config\App#6 (12) (
    public 'baseURL' -> string (22) "http://localhost:8080/"
    public 'allowedHostnames' -> array (0) []
    public 'indexPage' -> string (9) "index.php"
    public 'uriProtocol' -> string (11) "REQUEST_URI"
    public 'defaultLocale' -> string (2) "en"
    public 'negotiateLocale' -> boolean false
    public 'supportedLocales' -> array (1) [
        0 => string (2) "en"
    ]
    public 'appTimezone' -> string (3) "UTC"
    public 'charset' -> string (5) "UTF-8"
    public 'forceGlobalSecureRequests' -> boolean false
    public 'proxyIPs' -> array (0) []
    public 'CSPEnabled' -> boolean false
)

Config Caching: Disabled

Config 캐싱이 활성화되어 있는지 여부를 확인할 수 있습니다.

참고

Config 캐싱이 활성화되면 캐시된 값이 영구적으로 사용됩니다. 자세한 내용은 Config Caching을 참조하세요.