PHP json_encode() 옵션 목록

PHP의 json_encode() 함수는 JSON 변환 시 다양한 플래그(옵션)를 사용할 수 있습니다. 각 옵션은 **비트 플래그(bit flag)**로 동작하며, 여러 개를 비트 OR(|) 연산자를 사용하여 함께 사용할 수 있습니다.

1. JSON_HEX_TAG (1)

• <와 > 문자를 \u003C, \u003E로 이스케이프합니다.
• XSS(크로스 사이트 스크립팅) 공격 방지에 도움을 줍니다.
• 예:

echo json_encode("<script>", JSON_HEX_TAG);

 

출력:

"\u003Cscript\u003E"

2. JSON_HEX_AMP (2)

• & 문자를 \u0026으로 변환합니다.
• HTML에서 &는 특수문자로 해석될 수 있어 이를 방지합니다.
• 예:

echo json_encode("Tom & Jerry", JSON_HEX_AMP);

 

출력:

"Tom \u0026 Jerry"

3. JSON_HEX_APOS (4)

• '(작은따옴표, apostrophe)를 \u0027로 변환합니다.
• JSON에서 작은따옴표를 이스케이프하여 안전하게 저장할 때 사용됩니다.
• 예:

echo json_encode("I'm fine", JSON_HEX_APOS);

 

출력:

"I\u0027m fine"

4. JSON_HEX_QUOT (8)

• "(큰따옴표)를 \u0022로 변환합니다.
• JSON 내에서 따옴표가 깨지는 것을 방지할 때 사용됩니다.
• 예:

echo json_encode('Hello "World"', JSON_HEX_QUOT);

 

출력:

"Hello \u0022World\u0022"

5. JSON_FORCE_OBJECT (16)

• 배열을 JSON 객체로 강제 변환합니다.
• 기본적으로 PHP에서 연관 배열(키가 있는 배열)은 JSON 객체로 변환되지만, 일반 배열(숫자 키를 가지는 배열)은 JSON 배열로 변환됩니다.
• 이 옵션을 사용하면 모든 배열을 JSON 객체로 변환합니다.
• 예:

$arr = ["apple", "banana"];
echo json_encode($arr, JSON_FORCE_OBJECT);

 

출력:

{"0":"apple","1":"banana"}

6. JSON_NUMERIC_CHECK (32)

• 문자열로 저장된 숫자를 숫자로 변환합니다.
• JSON은 기본적으로 모든 값을 문자열로 저장하는데, 숫자 값을 유지하고 싶을 때 사용합니다.
• 예:

$data = ["age" => "25", "height" => "175"];
echo json_encode($data, JSON_NUMERIC_CHECK);

 

출력:

{"age":25,"height":175}

7. JSON_UNESCAPED_SLASHES (64)

• 슬래시(/)를 이스케이프하지 않도록 합니다.
• 기본적으로 json_encode()는 /를 \/로 변환합니다(XSS 공격 방지 목적).
• 예:

echo json_encode("https://example.com", JSON_UNESCAPED_SLASHES);

 

출력:

"https://example.com"

8. JSON_PRETTY_PRINT (128)

• 사람이 읽기 쉽게 JSON을 들여쓰기(indent)하여 출력합니다.
• 예:

$data = ["name" => "John", "age" => 30];
echo json_encode($data, JSON_PRETTY_PRINT);

 

출력:

{
    "name": "John",
    "age": 30
}

9. JSON_UNESCAPED_UNICODE (256)

• 유니코드 문자를 이스케이프하지 않고 원래 문자 그대로 출력합니다.
• 기본적으로 json_encode()는 한글, 일본어, 중국어 등의 문자를 \uXXXX 형식으로 변환합니다.
• 예:

echo json_encode(["text" => "한글"], JSON_UNESCAPED_UNICODE);

 

출력:

{"text":"한글"}

10. JSON_PARTIAL_OUTPUT_ON_ERROR (512)

• JSON 변환 중 오류가 발생해도 가능한 데이터만 출력합니다.
• 기본적으로 PHP는 변환할 수 없는 데이터(예: NAN, INF 등)를 만나면 false를 반환합니다.
• 이 옵션을 사용하면 변환할 수 없는 값만 생략하고 나머지는 정상 출력됩니다.
• 예:

$data = ["value" => NAN, "text" => "hello"];
echo json_encode($data, JSON_PARTIAL_OUTPUT_ON_ERROR);

 

출력:

{"text":"hello"}

11. JSON_PRESERVE_ZERO_FRACTION (1024)

• 소수점이 있는 숫자를 정확하게 유지합니다.
• 기본적으로 json_encode()는 1.0을 1로 변환하지만, 이 옵션을 사용하면 원래 값 그대로 유지됩니다.
• 예:

echo json_encode(["value" => 1.0], JSON_PRESERVE_ZERO_FRACTION);

 

출력:

{"value":1.0}

12. JSON_UNESCAPED_LINE_TERMINATORS (2048, PHP 7.1 이상)

• JSON 내에서 줄바꿈 문자를 그대로 유지하도록 합니다.
• 기본적으로 JSON은 줄바꿈 문자를 \n 또는 \r로 변환하지만, 이 옵션을 사용하면 원래 형태를 유지합니다.

13. JSON_THROW_ON_ERROR (4194304, PHP 7.3 이상)

• JSON 인코딩 중 오류가 발생하면 false를 반환하는 대신 예외(Exception)를 던집니다.
• 오류를 감지하고 처리할 때 유용합니다.
• 예:

try {
    json_encode("\xB1\x31", JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo "JSON Error: " . $e->getMessage();
}

 

출력:

JSON Error: Malformed UTF-8 characters, possibly incorrectly encoded

✅ 옵션 조합 사용 예시

여러 옵션을 조합하여 사용할 수 있습니다. 예를 들어:

$data = ["text" => "한글", "url" => "https://example.com"];
echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT);

 

출력:

{
    "text": "한글",
    "url": "https://example.com"
}

 

이렇게 비트 OR 연산자(|)를 사용하면 여러 기능을 동시에 적용할 수 있습니다.