PHP json_encode 한글 깨짐 막아내는 비결

PHP에서 데이터를 JSON 형식으로 변환할 때, 특히 한글이 포함된 경우 깨짐 현상이 발생하는 경우가 많습니다. 이는 PHP의 기본 `json_encode` 함수가 UTF-8 인코딩을 가정하지만, 데이터 소스의 인코딩이 다르거나 설정이 잘못된 경우 발생할 수 있습니다. 이 문제를 해결하기 위해서는 몇 가지 명확한 단계를 따르는 것이 중요합니다. 가장 먼저 고려해야 할 것은 PHP 스크립트 파일 자체의 인코딩과 PHP에서 처리하는 문자열의 인코딩을 일관되게 관리하는 것입니다. 일반적으로 UTF-8로 통일하는 것이 가장 좋은 방법이며, 이를 통해 불필요한 인코딩 변환 과정을 줄일 수 있습니다. 데이터베이스에서 데이터를 가져오는 경우에도 마찬가지로 데이터베이스 연결 시 UTF-8 설정을 확인하는 것이 필수적입니다. 이렇게 기본 설정들을 점검하는 것만으로도 많은 경우 한글 깨짐 문제를 예방할 수 있습니다.

또한, PHP 설정 자체에서 JSON 관련 옵션을 조절하는 것도 한 가지 방법입니다. `json_encode` 함수는 다양한 옵션을 제공하는데, 이를 활용하면 인코딩 관련 문제를 보다 유연하게 대처할 수 있습니다. 예를 들어, `JSON_UNESCAPED_UNICODE` 옵션을 사용하면 유니코드 문자를 이스케이프하지 않고 그대로 출력하여 가독성을 높이고, 의도치 않은 변환으로 인한 깨짐 현상을 방지할 수 있습니다. 이 옵션은 한글을 포함한 다양한 비ASCII 문자를 다룰 때 매우 유용하게 활용될 수 있습니다. 이러한 설정들을 체계적으로 관리하는 것이 PHP json_encode 한글 깨짐을 방지하는 첫걸음이라 할 수 있습니다.

항목	설명
PHP 스크립트 인코딩	반드시 UTF-8로 저장 및 설정해야 합니다.
데이터베이스 연결	MySQL 등의 데이터베이스 연결 시 문자셋을 UTF-8로 지정합니다.
`json_encode` 옵션	`JSON_UNESCAPED_UNICODE` 옵션 활용을 고려합니다.

가장 직접적으로 한글 깨짐을 해결할 수 있는 방법은 `json_encode` 함수에 특정 옵션을 추가하는 것입니다. 바로 `JSON_UNESCAPED_UNICODE` 옵션입니다. 이 옵션을 사용하면 PHP가 문자열 내의 유니코드 문자를 `\uXXXX`와 같은 형식으로 이스케이프하는 대신, 원래의 문자로 그대로 출력하게 됩니다. 예를 들어, "안녕하세요"라는 문자열은 `JSON_UNESCAPED_UNICODE` 옵션 없이 `json_encode`를 하면 "\\uc548\\ub155\\ud558\\uc138\\uc694" 와 같이 변환되지만, 이 옵션을 사용하면 "안녕하세요" 그대로 출력됩니다. 이 변환 결과는 JSON 데이터를 파싱하는 클라이언트 측 JavaScript 등에서 별도의 디코딩 과정 없이 바로 사용할 수 있다는 장점이 있습니다.

따라서, `json_encode` 함수를 사용할 때 배열이나 객체 앞에 해당 옵션을 비트 OR 연산자(`|`)를 사용하여 추가해주는 것이 좋습니다. 예를 들어, `$data`라는 배열을 JSON으로 변환해야 한다면 다음과 같이 코드를 작성할 수 있습니다. `` 여기서 `JSON_PRETTY_PRINT`는 가독성을 위해 JSON을 보기 좋게 포맷팅해주는 옵션으로, `JSON_UNESCAPED_UNICODE`와 함께 자주 사용됩니다. 이러한 옵션의 적절한 사용은 json_encode 한글 문제를 해결하는 데 있어 매우 효과적입니다. 이를 통해 데이터 전송 및 처리 과정에서의 혼란을 줄이고, 보다 안정적인 시스템을 구축할 수 있습니다.

▶ 1단계: PHP 스크립트 파일을 UTF-8 인코딩으로 저장합니다.

▶ 2단계: 데이터베이스 연결 시 문자셋을 UTF-8로 설정합니다.

▶ 3단계: `json_encode` 함수 사용 시 `JSON_UNESCAPED_UNICODE` 옵션을 추가합니다.

위에서 언급된 기본적인 설정과 `json_encode` 함수의 옵션 활용 외에도, 간혹 예상치 못한 상황에서 한글이 깨지는 경우가 발생할 수 있습니다. 이러한 상황에 대비하여 데이터를 JSON으로 변환하기 전에 데이터 자체의 인코딩을 다시 한번 확인하고 필요하다면 명시적으로 UTF-8로 변환해주는 과정이 도움이 될 수 있습니다. PHP 함수 중 `mb_convert_encoding` 함수를 사용하면 문자열의 인코딩을 다른 인코딩으로 변경할 수 있습니다. 예를 들어, 데이터가 EUC-KR로 되어 있다면 이를 UTF-8로 변환한 후 `json_encode`를 호출하는 방식입니다.

또한, 브라우저에서 JSON 데이터를 처리할 때에도 주의가 필요합니다. 클라이언트 측 JavaScript에서 JSON 데이터를 파싱할 때, JavaScript 파일 자체의 인코딩이 UTF-8이 아니거나, 응답 헤더에 적절한 Content-Type (예: `application/json; charset=utf-8`)이 설정되어 있지 않으면 클라이언트 측에서 문자가 깨져 보일 수 있습니다. 따라서 서버 측에서는 물론이고, 클라이언트 측 설정과 응답 헤더까지 종합적으로 점검하는 것이 PHP json_encode 한글 깨짐 방지를 위한 완벽한 솔루션이라고 할 수 있습니다. 이러한 다각적인 접근 방식을 통해 복잡한 데이터 교환 환경에서도 안정적으로 한글 데이터를 처리할 수 있습니다.

핵심 포인트: 데이터 소스의 인코딩 확인 및 `mb_convert_encoding` 활용, 그리고 클라이언트 측 Content-Type 헤더 설정을 잊지 마세요.

상황	해결 방안
데이터베이스에서 가져온 한글이 깨지는 경우	DB 연결 시 문자셋을 UTF-8로 설정하고, `mysqli_set_charset($conn, 'utf8');` 와 같이 명시적으로 지정합니다.
데이터 자체의 인코딩이 불확실한 경우	`mb_convert_encoding($data, 'UTF-8', 'auto');` 와 같이 인코딩 변환을 시도합니다.
클라이언트 측에서 JSON 데이터가 깨져 보이는 경우	서버 응답 헤더에 `header('Content-Type: application/json; charset=utf-8');` 를 추가합니다.

JSON_ENCODE 기본 활용 및 한글 깨짐의 원인

PHP에서 배열이나 객체를 JSON 형식으로 변환할 때 json_encode 함수를 사용합니다. 이 함수는 웹 API 통신이나 클라이언트-서버 간 데이터 교환에 매우 유용하게 쓰입니다. 기본적인 사용법은 간단합니다. PHP 배열을 첫 번째 인자로 넘겨주기만 하면 됩니다. 예를 들어, `json_encode(['name' => '홍길동', 'age' => 30])`와 같이 사용하면 '{"name":"\u3061\u3097\u3083\u3092\u306e\u3057\u305f\u3089\u3099\u3076\u3057\u3085\u3046"}' 와 같은 형식으로 출력됩니다. 하지만 한글 데이터가 포함될 경우, 예상치 못한 '유니코드 이스케이프' 현상, 즉 '깨짐'이 발생하곤 합니다. 이는 json_encode 함수가 기본적으로 UTF-8 인코딩된 문자열을 유니코드 이스케이프 시퀀스(예: \uXXXX)로 변환하기 때문입니다. 이 기본 동작 때문에 사람이 읽기 어려운 형태로 표시되며, 이는 JSON_ENCODE 한글 깨짐의 가장 흔한 원인입니다.

이러한 한글 깨짐 현상을 이해하기 위해, json_encode 함수의 기본 동작과 이를 해결하기 위한 옵션을 비교하는 표를 살펴보겠습니다.

옵션	설명	결과 (한글 데이터 포함 시)
옵션 없음 (기본값)	UTF-8 문자를 유니코드 이스케이프 시퀀스로 변환	"name": "\u3061\u3097\u3083\u3092\u306e\u3057\u305f\u3089\u3099\u3076\u3057\u3085\u3046" (깨짐)
JSON_UNESCAPED_UNICODE	유니코드 이스케이프 시퀀스 대신 원래 문자로 출력	"name": "홍길동" (정상)
JSON_UNESCAPED_SLASHES	슬래시(/)를 이스케이프하지 않고 그대로 출력	JSON_UNESCAPED_UNICODE와 함께 사용 시 "url": "https://example.com"

해결책 JSON_UNESCAPED_UNICODE 옵션의 힘

앞서 언급했듯이, json_encode 함수가 기본적으로 한글을 유니코드 이스케이프 문자로 변환하는 것이 문제입니다. 이 문제를 해결하는 가장 간단하고 효과적인 방법은 json_encode 함수에 JSON_UNESCAPED_UNICODE 옵션을 함께 사용하는 것입니다. 이 옵션은 말 그대로 유니코드 문자를 이스케이프하지 않고 원래의 UTF-8 문자 그대로 출력하도록 지시합니다. 이를 통해 PHP 배열에 담긴 한글 데이터가 JSON 문자열로 변환될 때 깨지지 않고 정상적으로 표시됩니다. 예를 들어, `json_encode(['name' => '홍길동', 'greeting' => '안녕하세요'], JSON_UNESCAPED_UNICODE)`와 같이 코드를 작성하면 '{"name":"홍길동","greeting":"안녕하세요"}'와 같이 원하는 결과값을 얻을 수 있습니다. 이 옵션은 PHP json_encode 한글 깨짐 방지를 위한 핵심적인 해결책입니다.

이 옵션을 사용했을 때와 사용하지 않았을 때의 차이를 명확하게 이해하기 위해, 다음과 같은 절차로 직접 확인해볼 수 있습니다.

▶ 1단계: PHP 배열에 한글 데이터를 포함하여 정의합니다.

▶ 2단계: JSON_UNESCAPED_UNICODE 옵션 없이 json_encode를 호출하여 결과를 확인합니다. (한글이 깨져 보일 것입니다.)

▶ 3단계: JSON_UNESCAPED_UNICODE 옵션을 추가하여 json_encode를 다시 호출하고, 결과가 정상적으로 출력되는지 확인합니다.

추가 팁 JSON_UNESCAPED_SLASHES 함께 사용하기

JSON_UNESCAPED_UNICODE 옵션은 한글 깨짐을 해결하는 데 탁월하지만, 때로는 URL이나 파일 경로 등 슬래시('/')가 포함된 데이터를 다룰 때 추가적인 고려가 필요할 수 있습니다. 기본적으로 json_encode 함수는 슬래시를 이스케이프하지 않지만, 다른 옵션과 함께 사용하거나 특정 환경 설정에 따라 슬래시가 이스케이프될 가능성도 배제할 수는 없습니다. 이를 확실히 방지하기 위해 JSON_UNESCAPED_UNICODE 옵션과 함께 JSON_UNESCAPED_SLASHES 옵션을 동시에 사용하는 것이 좋습니다. 이 두 옵션을 함께 사용하면, 한글 데이터는 물론 슬래시가 포함된 문자열까지 모두 본래의 형태로 유지되어 JSON 출력이 더욱 깔끔하고 일관되게 관리될 수 있습니다. 예를 들어, API 응답에 URL이 포함되어 있다면 `json_encode(['url' => 'https://api.example.com/data'], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)`와 같이 코드를 작성하면 됩니다.

이 두 가지 옵션을 함께 사용할 때의 이점을 정리하면 다음과 같습니다.

핵심 포인트: JSON_UNESCAPED_UNICODE와 JSON_UNESCAPED_SLASHES를 함께 사용하면 한글뿐만 아니라 URL 등에서 슬래시 깨짐 없이 데이터를 안전하게 JSON으로 변환할 수 있습니다. 이는 JSON_ENCODE 함수의 유연성을 극대화하는 방법입니다.

JSON_UNESCAPED_UNICODE 옵션의 올바른 활용

PHP에서 `json_encode` 함수를 사용하여 데이터를 JSON 형식으로 변환할 때 가장 흔하게 마주치는 문제가 바로 한글 깨짐 현상입니다. 특히 한글이 포함된 문자열을 JSON으로 만들면 유니코드 이스케이프 시퀀스(예: `\uXXXX`)로 변환되어, 이를 수신하는 쪽에서 올바르게 디코딩하지 못하면 깨져 보이게 됩니다. 이를 방지하기 위한 가장 직접적이고 효과적인 방법은 `JSON_UNESCAPED_UNICODE` 옵션을 사용하는 것입니다. 이 옵션을 `json_encode` 함수의 세 번째 인자로 전달하면, PHP는 한글과 같은 유니코드 문자를 이스케이프하지 않고 그대로 UTF-8 형태로 인코딩합니다. 이는 JSON 데이터를 읽는 대부분의 최신 시스템이나 JavaScript 환경에서 직접적으로 인식하고 처리할 수 있어, 별도의 디코딩 과정 없이 한글이 깨지지 않고 올바르게 표시되도록 합니다. 예를 들어, PHP 배열에 '안녕하세요'라는 한글이 있을 때, 이 옵션을 사용하지 않으면 `{"key":"\ud558\uc138\uc694"}` 와 같이 변환되지만, `JSON_UNESCAPED_UNICODE` 옵션을 사용하면 `{"key":"안녕하세요"}` 와 같이 사람이 읽기 쉬운 형태로 출력됩니다. 이 옵션의 적용은 단순히 보기 좋은 것을 넘어, API 통신 등 다양한 상황에서 데이터의 무결성을 보장하는 데 필수적입니다. JSON_UNESCAPED_UNICODE 옵션의 정확한 사용법과 그 효과를 이해하는 것이 한글 깨짐 문제 해결의 핵심입니다.

옵션	기능	한글 처리 결과
미사용	기본값, 유니코드 이스케이프	`\ud558\uc138\uc694` (깨짐 가능성 있음)
JSON_UNESCAPED_UNICODE	유니코드 문자를 이스케이프하지 않음	`안녕하세요` (정상 표시)

캐릭터 인코딩과 UTF-8의 중요성

`json_encode` 함수에서 한글이 깨지는 문제를 해결하는 또 다른 중요한 측면은 바로 데이터의 캐릭터 인코딩 문제입니다. JSON 표준은 기본적으로 UTF-8 인코딩을 사용하도록 권장하고 있습니다. 따라서 PHP 스크립트 파일 자체, 데이터베이스에 저장된 문자열, 그리고 PHP 내부에서 다루는 문자열들이 모두 UTF-8로 일관되게 인코딩되어 있어야 합니다. 만약 PHP 스크립트 파일이 UTF-8이 아닌 다른 인코딩(예: EUC-KR)으로 저장되어 있다면, `json_encode` 함수는 이미 깨진 문자열을 입력받게 되어 아무리 `JSON_UNESCAPED_UNICODE` 옵션을 사용해도 결과는 올바르지 않습니다. 따라서 개발 환경 및 서버 설정을 UTF-8로 통일하는 것이 필수적입니다. PHP에서 파일 인코딩을 확인하고 설정하는 방법은 텍스트 에디터의 설정을 통해 간단히 할 수 있으며, 데이터베이스 연결 시에도 UTF-8 문자셋을 사용하도록 명시해야 합니다. 이러한 사전 준비 작업이 뒷받침될 때, `JSON_UNESCAPED_UNICODE` 옵션은 비로소 그 제 역할을 다하게 됩니다. 텍스트 인코딩의 차이로 인해 발생하는 문제는 JSON 함수 자체의 문제가 아니라, 데이터를 처리하는 전체적인 파이프라인의 문제입니다.

▶ 1단계: PHP 파일 저장 시 UTF-8 인코딩을 사용합니다.

▶ 2단계: 데이터베이스 문자셋 설정을 UTF-8로 합니다.

▶ 3단계: PHP 스크립트 내에서 `json_encode` 사용 시 `JSON_UNESCAPED_UNICODE` 옵션을 적용합니다.

핵심 요약

• PHP `json_encode`에서 한글 깨짐은 `JSON_UNESCAPED_UNICODE` 옵션으로 해결 가능합니다.
• UTF-8 인코딩을 전반적으로 사용하여 데이터의 일관성을 유지하는 것이 중요합니다.
• PHP 파일, 데이터베이스, 내부 처리 문자열 모두 UTF-8로 통일해야 합니다.

주요 질문 FAQ

Q. PHP json_encode 시 한글이 깨져서 '???', '\uXXXX' 형태로 표시돼요. 어떻게 해결해야 하나요?

PHP에서 json_encode 함수를 사용할 때 한글이 깨지는 가장 흔한 이유는 문자열의 인코딩이 UTF-8이 아니기 때문입니다. 서버 환경이나 데이터베이스, 또는 PHP 스크립트 자체의 인코딩 설정이 UTF-8로 통일되어 있지 않으면 이런 문제가 발생할 수 있습니다. 해결 방법은 다음과 같습니다. 첫째, PHP 파일의 인코딩을 UTF-8로 저장하세요. 둘째, 데이터베이스 연결 시 문자셋을 UTF-8로 설정하세요. 셋째, PHP 코드 내에서 함수로 데이터를 가공할 때 `mb_internal_encoding('UTF-8');` 와 같이 내부 문자 인코딩을 UTF-8로 설정하고, `json_encode` 함수에 `JSON_UNESCAPED_UNICODE` 옵션을 함께 사용하면 됩니다.

Q. `json_encode` 함수에 `JSON_UNESCAPED_UNICODE` 옵션을 사용했는데도 여전히 한글이 깨져 보입니다. 왜 그런가요?

`JSON_UNESCAPED_UNICODE` 옵션은 PHP 문자열을 JSON 형식으로 변환할 때 유니코드 이스케이프 시퀀스(예: `\uXXXX`) 대신 실제 한글 문자로 출력하도록 지시하는 역할을 합니다. 하지만 이 옵션을 사용했음에도 한글이 깨진다면, 데이터가 PHP 스크립트로 넘어오는 과정에서 이미 다른 인코딩으로 변환되었거나, JSON 데이터를 받는 클라이언트(JavaScript 등) 측에서 해당 JSON 문자열을 올바르게 디코딩하지 못하고 있을 가능성이 높습니다. 데이터를 PHP로 가져올 때, 혹은 클라이언트에서 JSON을 파싱할 때 UTF-8로 제대로 처리되고 있는지 확인해야 합니다.

Q. 모든 PHP 배열이나 객체를 JSON으로 변환할 때 항상 한글이 깨지지 않도록 하는 좋은 습관이 있을까요?

네, 있습니다. 가장 중요한 습관은 '모든 곳에서 UTF-8 사용'입니다. PHP 스크립트 파일 자체를 UTF-8로 저장하고, 데이터베이스 연결 시에도 `SET NAMES utf8;` 또는 PHP PDO/MySQLi 연결 옵션으로 문자셋을 UTF-8로 설정하세요. 또한, 사용자 입력이나 외부 API에서 받은 데이터를 PHP 내부에서 처리할 때도 `mb_convert_encoding` 함수 등을 사용하여 UTF-8로 변환하는 것을 고려할 수 있습니다. 마지막으로, `json_encode` 함수 사용 시에는 항상 `JSON_UNESCAPED_UNICODE` 옵션을 함께 사용하여 일관성을 유지하는 것이 좋습니다.

Q. 데이터베이스에서 가져온 한글 데이터가 이미 이상하게 저장되어 있는데, json_encode 전에 수정할 방법이 있나요?

네, `json_encode`를 호출하기 전에 데이터를 수정할 수 있습니다. 만약 데이터베이스에서 가져올 때부터 이미 깨진 문자열(예: `��`)이라면, 이는 데이터베이스 저장 시점이나 연결 시점의 인코딩 문제가 원인일 가능성이 높습니다. PHP 코드에서는 `mb_convert_encoding` 함수를 사용하여 현재 인코딩을 UTF-8로 변환해보는 것을 시도해볼 수 있습니다. 예를 들어, `mb_convert_encoding($broken_string, 'UTF-8', 'auto');` 와 같이 사용해 볼 수 있습니다. 하지만 근본적인 해결책은 데이터베이스 테이블의 문자셋 설정과 PHP와의 연결 문자셋을 UTF-8로 통일하는 것입니다.

Q. JavaScript에서 `JSON.parse()`로 받은 JSON 문자열의 한글이 깨질 때는 어떻게 해야 하나요?

JavaScript에서 `JSON.parse()`를 통해 JSON 데이터를 받았을 때 한글이 깨진다면, 이는 대부분 서버에서 JSON을 생성할 때 `JSON_UNESCAPED_UNICODE` 옵션을 사용하지 않았거나, 혹은 클라이언트 측에서 JSON 데이터를 처리하는 방식에 문제가 있을 수 있습니다. 서버에서는 반드시 `JSON_UNESCAPED_UNICODE` 옵션을 사용하여 JSON을 생성하세요. 만약 서버에서 올바르게 생성되었는데도 클라이언트에서 문제가 발생한다면, JavaScript 코드 내에서 `JSON.parse()` 결과를 받은 후 DOM에 출력하거나 다른 방식으로 처리할 때 UTF-8을 제대로 인식하지 못하는 환경일 수 있습니다. `` 태그가 HTML 헤더에 올바르게 포함되어 있는지 확인하는 것도 도움이 됩니다.

Q. `json_encode` 시 `JSON_PRETTY_PRINT` 옵션과 `JSON_UNESCAPED_UNICODE` 옵션을 함께 사용할 수 있나요? 한글 깨짐 방지에 도움이 되나요?

네, `JSON_PRETTY_PRINT`와 `JSON_UNESCAPED_UNICODE` 옵션은 비트 OR 연산자(|)를 사용하여 함께 사용할 수 있습니다. 예를 들어 `json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);` 와 같이 사용합니다. `JSON_PRETTY_PRINT`는 JSON 출력을 들여쓰기하여 사람이 읽기 쉽게 만들어주는 옵션이며, 한글 깨짐 방지 자체에는 직접적인 영향을 주지 않습니다. 하지만 `JSON_UNESCAPED_UNICODE` 옵션과 함께 사용하면, 예쁘게 포맷된 JSON 안에서도 한글이 정상적으로 표시되어 가독성과 문제 해결에 더 큰 도움이 됩니다.

Q. 특정 서버 환경에서만 PHP json_encode 한글 깨짐 현상이 발생합니다. 어떤 부분을 중점적으로 점검해야 할까요?

이런 경우, 해당 서버 환경의 PHP 설정, 웹 서버(Apache, Nginx) 설정, 그리고 PHP 스크립트가 실행되는 환경 변수들을 종합적으로 점검해야 합니다. 우선 PHP 설정 파일(`php.ini`)에서 `default_charset`이 'UTF-8'로 설정되어 있는지 확인하세요. 또한, PHP 스크립트 시작 부분에 `header('Content-Type: application/json; charset=utf-8');`를 명시적으로 추가하는 것도 도움이 될 수 있습니다. 서버의 운영체제 수준에서 Locale 설정이 UTF-8로 되어 있는지, 그리고 PHP가 해당 Locale 정보를 제대로 인식하는지도 간과해서는 안 됩니다.