PHP 파일 업로드 핵심 환경 설정

PHP는 HTML 양식(form) 전송을 통해 클라이언트의 파일을 서버 컴퓨터 디스크로 안전하게 업로드하는 기능을 네이티브하게 제공합니다.

그러나 실무에서 기가바이트(GB) 단위나 수십 메가바이트(MB) 수준의 이미지를 웹 서버에 올릴 때 오류 메시지 없이 파일이 증발하거나 오류 코드가 반환되는 현상이 잦은데, 이는 php.ini의 관련 한도 옵션들이 상호 유기적으로 결합되어 제한을 걸고 있기 때문입니다.

이 장에서는 대용량 파일 전송을 안착시키기 위한 필수 지시어들과 그들 사이의 설정 크기 서열 규칙을 명쾌하게 해설합니다.

1. 파일 업로드 핵심 4대 지시어

php.ini 파일을 열고 검색을 실행하여 다음 핵심 파라미터들의 상한 한도를 조정합니다.

; 1. 파일 업로드 허용 여부 (기본값: On)
file_uploads = On

; 2. 단일 파일 하나당 허용할 최대 업로드 용량
upload_max_filesize = 100M

; 3. 한 번의 HTTP POST 전송 요청으로 보내는 전체 바디 데이터의 최대 용량
post_max_size = 120M

; 4. 단 한 번의 요청 페이지에서 한꺼번에 전송 선택할 수 있는 최대 파일 개수
max_file_uploads = 20

; 5. 업로드 중인 파일 조각이 완료 전까지 임시 보관되는 하드디스크 경로
; 지정하지 않으면 운영체제 기본 임시 폴더(/tmp 등)를 자동 사용합니다.
; upload_tmp_dir = "/var/www/temp"

2. 매우 중요: 업로드 용량 서열 공식 (Hierarchy Rule)

파일 업로드 설정을 조율할 때 절대로 잊어서는 안 되는 절대 규칙 공식이 있습니다. 이 서열이 깨져 하위 한도가 상위 한도를 침범하면, 설정값에 상관없이 용량 초과 에러가 터집니다.

• 공식의 논리적 이유:
  1. 클라이언트가 보내는 파일(upload_max_filesize)은 파일 외의 다른 텍스트 폼 데이터들과 함께 HTTP POST 요청 본문(Body)으로 감싸져 서버에 송출됩니다. 따라서 당연히 전체 POST 바디 크기 제한인 post_max_size가 단일 파일 크기 한도보다 항상 크거나 최소한 같아야만 데이터 수신이 가능합니다.
  2. 수신된 POST 데이터 전체를 PHP 엔진이 메모리에 상주시켜 파싱하고 확장 모듈로 던져 처리하려면, 해당 단일 PHP 스크립트 프로세스가 운영체제로부터 빌려 사용할 수 있는 최대 메모리 뱅크 한계치인 memory_limit이 POST 전체 크기보다 반드시 여유 있게 커야 프로세스가 메모리 고갈(Out of memory)로 뻗지 않고 연산을 완료합니다.
     • 예시 설정: upload_max_filesize = 100M ➡️ post_max_size = 120M ➡️ memory_limit = 256M

3. 대용량 전송을 위한 타임아웃(Timeout) 및 버퍼 제어

파일의 물리 용량이 커지면 네트워크 회선을 타고 클라이언트가 업로드하는 전송 시간 자체가 길어집니다. 이를 커버하기 위해 시간 제약 조건을 함께 늘려주어야 합니다.

• max_input_time (기본값: 60):
  • PHP 엔진이 클라이언트가 밀어 넣는 폼 데이터나 업로드 파일 스트림을 전부 수신해서 구조 분석을 마치기까지 허용하는 데이터 수신 대기 최대 시간(초)입니다. 기가 단위 파일의 업로드가 오래 걸려 끊긴다면 이 값을 충분히 늘려줍니다. (예: 300초)
• max_execution_time (기본값: 30):
  • 파일이 온전히 서버 디스크에 올라온 후, PHP 파일 복사나 DB 갱신 등 실제 비즈니스 로직 코드를 구동하는 연산 처리 대기 시간입니다. 파일 업로드 완료 후 로직 처리 시간이 30초를 초과하여 터지지 않도록 여유 있게 설정합니다.