ServBay에서 `.user.ini` 파일 사용법: 로컬 PHP 설정 가이드

ServBay는 개발자를 위해 설계된 강력한 통합 로컬 웹 개발 환경으로, 다양한 언어와 기술 스택을 지원하며 유연한 PHP 버전 관리 및 간편한 설정 옵션을 제공합니다. 실제 개발 현장에서는 프로젝트별로 파일 업로드 크기 제한, 메모리 한도, 오류 보고 레벨 등 PHP 설정이 다를 수 있습니다. 전역 php.ini 파일을 직접 수정하면 모든 프로젝트에 영향을 미치므로, 다수의 프로젝트를 관리할 때 매우 불편할 수 있습니다.

다행히 PHP에서는 .user.ini 파일 기능을 제공하여, 특정 디렉터리와 하위 디렉터리에서만 적용되는 개별 PHP 설정을 지정할 수 있습니다. 전역 php.ini를 건드릴 필요 없이, ServBay는 이러한 .user.ini 파일을 완벽하게 지원해 프로젝트 또는 디렉터리 단위로 PHP 환경을 빠르고 효과적으로 조정할 수 있습니다.

이 문서에서는 .user.ini 파일의 작동 원리, ServBay에서의 실제 활용법, 그리고 구체적인 설정 예시를 통해 프로젝트별 PHP 설정 방법을 자세히 소개합니다.

`.user.ini` 파일이란?

.user.ini 파일은 PHP 5.3.0 버전부터 도입된 기능으로, 과거 웹 서버 설정(예: Apache의 .htaccess)에서 php_value, php_flag 등으로 PHP 옵션을 지정하던 것보다 훨씬 유연하고 안전하게 동작합니다. .user.ini 파일을 웹 루트 또는 접근이 가능한 디렉터리에 두면, 해당 디렉터리와 하위 디렉터리 내 PHP 스크립트에만 설정이 적용됩니다.

주요 특징

로컬 범위: .user.ini 파일의 설정은 해당 디렉터리와 하위 디렉터리 내에서만 적용되어, ServBay의 전역 php.ini 혹은 다른 프로젝트에는 영향을 주지 않습니다.
높은 유연성: 각 프로젝트별로 필요한 PHP 설정을 개별적으로 지정할 수 있습니다.
간편한 관리: 서버 전체 또는 PHP 설정 파일을 수정할 필요가 없어, 환경간 충돌을 줄이고 프로젝트마다 독립적인 구성이 가능합니다.
재시작 불필요: 보통 php.ini를 수정하면 PHP-FPM이나 웹서버 재시작이 필요하지만, .user.ini 수정은 PHP의 user_ini.cache_ttl 값(기본 300초 — 5분)만큼 대기 후 자동 반영됩니다.

설정 가능한 지시문

모든 PHP 설정이 .user.ini에서 가능한 것은 아닙니다. 설정 가능 여부는 각 PHP 옵션의 “변경 모드(Changeable Modes)”에 따라 다릅니다. PHP_INI_USER, PHP_INI_PERDIR, PHP_INI_ALL 모드만 .user.ini에서 설정할 수 있습니다.

.user.ini에서 자주 사용하는 설정 예시는 다음과 같습니다.

upload_max_filesize
post_max_size
memory_limit
display_errors
log_errors
max_execution_time
session.save_path
date.timezone

PHP_INI_SYSTEM 모드(예: extension_dir, zend_extension, disable_functions 등)의 설정은 .user.ini에서 불가합니다. 이들은 반드시 주 설정파일(php.ini)나 웹 서버 설정을 통해 지정해야 합니다.

각 PHP 옵션의 변경 가능 모드는 PHP 공식 매뉴얼 ini 설정 목록에서 확인하세요.

ServBay에서 `.user.ini` 사용하기

ServBay 환경에서 .user.ini 파일을 적용하는 절차는 매우 간단합니다. 여기서는 upload_max_filesize 및 memory_limit 설정 과정을 예로 설명합니다.

예시로, ServBay의 기본 웹사이트 루트가 /Applications/ServBay/www/이고, myproject라는 프로젝트가 /Applications/ServBay/www/myproject/public 디렉터리를 웹 루트로 사용한다고 가정합니다.

1단계: 대상 디렉터리 선정

먼저, 맞춤 PHP 설정을 적용하고자 하는 디렉터리를 결정하세요. 보통 프로젝트 웹 루트(예: Laravel, Symfony 등에서는 public 디렉터리)거나, 별도의 설정이 필요한 하위 디렉터리입니다.

예: /Applications/ServBay/www/myproject/public

2단계: `.user.ini` 파일 생성 또는 수정

위 디렉터리에 .user.ini라는 이름의 새 파일을 만듭니다. (기존에 파일이 있다면 열어서 수정) 참고로, 마침표로 시작하는 파일(.user.ini)은 대부분의 파일 탐색기에서 숨김 파일로 간주됩니다. 숨김 파일 보기 설정을 활성화하세요.

터미널에서 파일을 생성하는 방법:

bash

cd /Applications/ServBay/www/myproject/public
touch .user.ini

그리고 텍스트 편집기로 .user.ini 파일을 열어 설정을 추가하세요. 한 줄에 한 가지 PHP 설정을 입력합니다. 예시:

ini

; 최대 업로드 파일 크기를 20MB로 설정
upload_max_filesize = 20M

; PHP 스크립트 메모리 제한을 256MB로 설정
memory_limit = 256M

; 오류 표시 활성화 (개발 환경에서만 권장)
display_errors = On

수정 후 저장하고 닫으세요.

3단계: 설정 반영 대기 또는 강제 새로고침

.user.ini 파일의 변경은 즉시 적용되지 않고, PHP에서 설정에 따라 캐시됩니다. 기본적으로는 user_ini.cache_ttl 값(대부분 300초, 즉 5분)이 지나야 자동으로 반영됩니다.

변경 사항을 즉시 반영하고 싶다면 아래 방법 중 하나를 시도할 수 있습니다. (ServBay 버전 및 설정에 따라 달라질 수 있습니다.)

해당 PHP-FPM 프로세스 재시작: ServBay 앱에서 현재 웹사이트가 사용하는 PHP 버전을 찾아 PHP-FPM 서비스를 중지했다가 재시작합니다.
ServBay 전체 재시작: 모든 로컬 서비스를 중단하므로 마지막 수단으로 사용하세요.
캐시 만료를 기다림: 급하지 않다면 이 방법이 가장 안전합니다.

4단계: `.user.ini` 적용 여부 확인

.user.ini 파일이 제대로 적용됐는지 확인하려면 간단한 PHP 파일로 PHP의 설정 정보를 출력해볼 수 있습니다.

.user.ini 파일이 위치한 디렉터리(예: /Applications/ServBay/www/myproject/public)에 info.php라는 파일을 아래처럼 만드세요.

php

<?php
phpinfo();
?>

info.php 파일을 저장하세요.

이제 브라우저에서 ServBay 웹사이트의 해당 info.php로 접근합니다. 예를 들어 프로젝트 도메인이 myproject.servbay.demo이고, info.php가 public 폴더 내에 있다면, 접속 주소는 https://myproject.servbay.demo/info.php가 됩니다.

브라우저에 표시된 phpinfo() 페이지에서 .user.ini에 지정한 옵션들(e.g. upload_max_filesize, memory_limit, display_errors)을 찾아보세요. 각 항목에는 Master Value(전역 php.ini 값)와 Local Value(현재 스크립트 적용 값)가 있습니다.

Master Value: 전체 환경에 적용된 php.ini 값
Local Value: .user.ini나 웹 서버 설정 등으로 개별 조정된 현재값

.user.ini에 적은 값(e.g. 20M, 256M, On)이 Local Value로 표시된다면, 설정이 정상 적용된 것입니다.

보안 안내: 설정 적용 확인 후에는 info.php 파일을 반드시 삭제하거나 외부 접근을 차단하세요. 이 파일은 서버 환경 정보를 외부에 노출시킬 수 있습니다.

추가 설명 및 주의사항

파일명 및 위치: 파일 이름은 반드시 .user.ini로, 적용할 디렉터리에 정확히 위치해야 하며 하위 디렉터리까지 영향을 미칩니다.
옵션 적용 가능 모드: 설정 가능한 옵션만 .user.ini에 작성 가능하며 (PHP_INI_USER, PHP_INI_PERDIR, PHP_INI_ALL). 만약 지원하지 않는 옵션을 입력하면 적용되지 않으나 별도의 오류 메시지는 나오지 않을 수 있습니다. 자세한 목록은 PHP 공식 문서 참고.
캐시: .user.ini 변경이 잦고 즉시 반영되어야 한다면, 글로벌 php.ini에서 user_ini.cache_ttl 값을 일시적으로 줄일 수 있습니다(e.g. user_ini.cache_ttl = 5). 단, 운영 환경에서는 너무 낮게 설정하지 않는 것이 성능상 바람직합니다. php.ini를 수정하면 PHP-FPM 재시작이 필요합니다.
우선순위: PHP 설정 우선순위는 일반적으로: 기본값 < php.ini (< 추가 로드된 .ini 포함) < 웹서버 설정(php_value/php_flag, Apache/nginx 모듈 사용 시) < .user.ini < 스크립트 내 ini_set() 순서입니다. 즉, .user.ini에서 지정한 값은 글로벌 설정을 덮어쓰지만, 스크립트에서 ini_set()으로 재설정하면 그 값이 최종적으로 적용됩니다.
보안: .user.ini에는 민감 정보를 저장하지 마세요. 비록 설정 서브디렉터리에만 적용되지만, (대부분 접근은 차단되나) 웹 루트 아래 위치한 파일임을 명심하세요.

자주 묻는 질문 (FAQ)

Q: .user.ini 파일을 만들고 설정을 추가했는데 적용이 안 됩니다. 원인이 뭔가요?

A: 원인으로는 다음과 같은 것들이 있습니다:

파일명·위치 오류: 정확히 .user.ini로, 적용하고 싶은 디렉터리에 위치했는지 확인하세요.
지원하지 않는 옵션 입력: 일부 PHP 설정은 .user.ini에서 지원되지 않습니다. PHP 매뉴얼에서 지원 모드를 확인하세요.
캐시 미갱신: user_ini.cache_ttl(기본 5분)이 지나기 전엔 변경 사항이 적용되지 않습니다. 대기하거나 PHP-FPM을 재시작하세요.
문법 오류: .user.ini 내에 오타 또는 형식 오류가 있는지 확인하세요.
우선순위에 밀림: 스크립트 내에서 ini_set() 등으로 이미 값을 덮어썼을 수 있습니다.

Q: .user.ini와 전역 php.ini의 차이는 뭔가요?

A: 전역 php.ini 파일은 해당 PHP 버전의 모든 애플리케이션/스크립트에 적용되는 환경설정 파일입니다. 반면, .user.ini는 위치한 디렉터리 및 하위 디렉터리 내 스크립트에만 영향이 있으며, 일부 설정만 지정할 수 있습니다. .user.ini의 강점은 필요할 때만 국지적으로 PHP 환경을 맞춤화할 수 있다는 점입니다.

결론

ServBay에서 .user.ini 파일을 활용하면 각 프로젝트별 PHP 설정을 완벽하게 제어할 수 있습니다. 완벽한 유연성과 분리성 덕분에, 개발자는 전체 환경을 건드리지 않고도 프로젝트마다 요구되는 조건에 맞게 PHP 환경을 신속하게 조정할 수 있습니다. 이번 가이드와 예제를 토대로, ServBay 환경에서 .user.ini 파일을 능숙하게 사용해 개발 생산성과 환경 관리의 효율성을 높이시길 바랍니다. ServBay는 개발자에게 강력하고 유연한 로컬 개발 툴을 제공하기 위해 설계되었으며, .user.ini에 대한 탄탄한 지원 역시 이러한 철학을 잘 보여줍니다.

ServBay에서 .user.ini 파일 사용법: 로컬 PHP 설정 가이드 ​

.user.ini 파일이란? ​

주요 특징 ​

설정 가능한 지시문 ​

ServBay에서 .user.ini 사용하기 ​

1단계: 대상 디렉터리 선정 ​

2단계: .user.ini 파일 생성 또는 수정 ​

3단계: 설정 반영 대기 또는 강제 새로고침 ​

4단계: .user.ini 적용 여부 확인 ​

추가 설명 및 주의사항 ​

자주 묻는 질문 (FAQ) ​

결론 ​