[PHP] Blueimp jQuery File Upload 라이브러리에서 UploadHandler의 handle_file

PHP

[PHP] Blueimp jQuery File Upload 라이브러리에서 UploadHandler의 handle_file_upload()가 자동 실행 되는 이유

teamnova 2025. 4. 30. 14:05

728x90

안녕하세요.

오늘은 웹에서 자주 사용하는 파일 업로드 라이브러리인 Blueimp jQuery File Upload를 사용할 때 헷갈릴 수 있는 포인트를 하나 정리해보려고 합니다.

바로, UploadHandler.php 안에 있는 handle_file_upload() 함수는 직접 호출한 적이 없는데 왜 실행될까? 라는 부분입니다.

Blueimp jQuery File Upload란?

Blueimp jQuery File Upload는
웹사이트에 파일 업로드 기능을 쉽게 붙일 수 있게 해주는 jQuery 기반의 플러그인입니다.

여러 파일 선택
드래그 앤 드롭
업로드 상태바
미리보기
업로드된 파일 삭제 등

다양한 기능을 지원하며, 서버 사이드에서는 PHP, Node.js 등과 호환됩니다.

특히 내부적으로 jQuery 문법을 기반으로 하기 때문에, 간결하게 코드를 작성할 수 있고, 브라우저 간 호환성 문제도 자동으로 처리해준다는 장점이 있습니다.

1. UploadHandler.php 파일이란

먼저, 동영상 업로드를 하기 위해 UploadHandler.php 파일을 사용해야 합니다. 이 파일은 Blueimp jQuery File Upload 라이브러리의 핵심 PHP 백엔드 파일이며, 주로 업로드 요청 처리와 관련된 모든 기능을 담당하는 파일입니다. 주요 기능들은 아래와 같습니다.

UploadHandler.php 안에 들어 있는 주요 기능들

1. 생성자 (__construct)

객체가 생성되면 실행됨
내부에서 initialize() 호출
업로드 요청 방식(GET/POST 등)에 따라 적절한 처리를 실행하게 함

2. initialize()

현재 HTTP 요청 방식(POST, GET, DELETE 등)을 판별해서 처리할 함수를 분기함

3. post()

파일 업로드 처리의 핵심
업로드된 파일 데이터를 받아서 → handle_file_upload()를 호출해서 실제 저장

4. handle_file_upload()

진짜 파일을 디렉토리에 저장하는 역할
파일 이름, 사이즈, 타입, 오류 여부 등을 받아 처리
저장 후 JSON 응답도 생성함

5. get()

업로드된 파일 목록을 불러올 때 사용 (예: 파일 리스트 보기 기능 만들 때)

6. delete()

특정 파일을 삭제하는 기능
클라이언트에서 삭제 요청이 오면 해당 파일을 서버에서 제거함

등등이 있습니다.

2. handle_file_upload 는 누가 호출하는가?

위 기능 중 가장 핵심이 되는 handle_file_upload 함수는 직접 호출해서 사용하지 않습니다.

파일 어디에도 $this->handle_file_upload() 같은 코드가 명시적으로 보이지 않았는데도
파일 업로드 시 이 함수가 자동으로 실행되는 것을 확인할 수 있습니다.

파일이 업로드 되는 흐름을 따라가보면

1) 먼저 로컬에서 업로드하고자 하는 file을 선택한 후, 업로드 버튼을 클릭합니다.

그럼 main_video.js 파일 내에 위치한 아래 코드가 실행됩니다.

$('#fileupload').fileupload({
    url: '실제로 파일 업로드 처리를 맡을 서버측 PHP 파일 경로/'  // ← 본인이 설정한 경로
});

- 즉, 브라우저에서 파일을 업로드하면 url 에 지정한 경로로 POST 요청이 가고, 서버에서는 이 요청을 받아 파일 업로드를 처리합니다.

- 언급한 자바 스크립트의 파일명은 본인이 업로드 하고자 하는 파일의 타입에 따라 main_image.js, main_video.js, main_audio.js 등으로 달라질 수 있습니다.

2) UploadHandler 클래스의 인스턴스 생성 (php 파일)

require('UploadHandler.php');
$upload_handler = new UploadHandler(); // ← 이 줄이 핵심!

- 여기서 UploadHandler 클래스의 인스턴스를 생성해주면 생성자(__construct)가 자동으로 실행되며 업로드한 방식에 따라 (post, get) post() 함수가 자동 실행됩니다.

3) UploadHandler 인스턴스 생성 후 동작 흐름

// 1. construct 
public function __construct(...) {
    if ($initialize) {
        $this->initialize(); // ← 초기화 함수 실행
    }
}

// 2. initialize 
protected function initialize() {
    switch ($this->get_server_var('REQUEST_METHOD')) {
        case 'POST':
            $this->post($this->options['print_response']); // ← post 함수 실행
            break;
    }
}

// 3. post() 함수
$files[] = $this->handle_file_upload(...);

- 클라이언트 측에서 사용자가 파일 업로드 버튼을 클릭하면, UploadHandler 클래스의 인스턴스가 생성됩니다.

- 생성자는 초기화 함수를 실행하고, 업로드 방식이 post 인 경우 post() 함수를 실행합니다.

- post() 함수 내부에 파일 업로드의 가장 핵심적인 함수인 handle_file_upload () 가 위치해있습니다.

handle_file_upload() 함수의 실행 조건

// post 함수 실행 조건 
if ($upload) {
    ...
    $this->handle_file_upload(...);
}

- handle_file_upload 함수의 실행 조건은 if ($upload) 로 여기서 $upload 변수 값은

- $upload = $this->get_upload_data($this->options['param_name']); 입니다.

- 즉, 사용자가 실제로 파일을 업로드 했다면 위 흐름을 따라 자동으로 handle_file_upload () 까지 도달하게 됩니다!

중요한 것은 UploadHandler 클래스의 인스턴스를 "직접" 생성하는 것

$upload_handler = new UploadHandler();

- 라이브러리에 포함된 파일인 라이브러리인 UploadHandler.php는 단순히 include한다고 실행되지 않고, 직접 new로 생성해야 실행 흐름이 시작됩니다.

- 작성자의 경우, index.php 파일에서 업로드 요청과 함께 바로 실행했지만, 특정 조건을 커스텀하여 실행되게 만들 수도 있습니다.

- Blueimp jQuery File Upload는 강력하고 편리하지만, 내부 구조를 명확히 모르면 동작 원리를 이해하기 어렵습니다.

감사합니다