정의 및 사용 방법

PHP 버전
4+

htmlentities() 함수는 주어진 문자열에서 HTML에 정의된 모든 특수 문자를 엔티티(entities)로 변환합니다.

HTML에 정의된 모든 특수 문자는 표준화된 'HTML Named Character References'를 의미하며, 자세한 목록은 HTML 표준 문서에서 확인할 수 있습니다.

이 함수는 주로 HTML에서 특수 문자들을 화면에서 제대로 표현하기 위해 사용됩니다.

특수 문자를 HTML 엔티티(entities)로 변환해야 하는 이유는 예약된 문자와의 충돌을 피하고, 웹 콘텐츠를 안전하고 일관되게 출력하기 위함이며, 자세한 내용은 HTML 특수 문자 사용법과 의의 – 예약된 문자와의 충돌을 피하며 웹 콘텐츠 작성하기에서 설명하고 있습니다.

주의하세요!
htmlentities() 함수는 HTML에 정의된 예약 문자와 특수 문자만 엔티티로 변환합니다.
따라서 HTML 엔티티로 정의되지 않은 특수 문자(예: [, ], ^, {, } 등)를 포함한 보안 관련 입력(예: SQL 구문, 일부 XSS 공격 코드 등)은 변환되지 않으므로, 보안 목적으로 사용하는 것은 안전하지 않습니다.

기본 예제

PHP 
$str = 'htmlentities() 함수는 <, >, &, ", \', ©, ™ 등을 HTML 엔티티(entities)로 변환합니다.';
$encode = htmlentities($str);

var_dump($encode);
출력

htmlspecialchars() 함수는 HTML에서 코드로 인식하게 하여 특별한 의미를 가지고 있는 다섯 개의 HTML 예약 문자(<, >, &, ", ')만을 인코딩하지만, htmlentities() 함수는 이 다섯 개의 HTML 예약 문자 이외에도 이름 엔티티가 정의된 목록(HTML Named Character References)에 있는 나머지 문자들(예: ©, €, ™ 등)을 추가로 인코딩한다는 차이점이 있습니다.

구문

PHP 
htmlentities(
    string $string,
    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
    ?string $encoding = null,
    bool $double_encode = true
): string

매개변수

htmlentities() 함수의 매개변수
$string 필수. 변환하려는 원본 문자열입니다.
$flags 옵션. 어떤 따옴표를 HTML 엔티티로 변환할지 등, 함수의 동작 방식을 지정하는 상수 옵션입니다. 여러 옵션을 함께 사용하려면 | (비트 OR) 연산자를 사용합니다. 옵션은 다음과 같습니다.
  • ENT_QUOTES (기본값): 쌍따옴표(")와 홑따옴표('') 모두 변환합니다.
    💡 참고: 홑따옴표(')는 HTML 문서 표준 지정 옵션에 따라 엔티티가 다르게 변환됩니다.
    • ENT_HTML401(HTML 4.01 문서 표준을 기준으로 문자열을 처리): &#039;로 변환됩니다.
    • ENT_XML1, ENT_XHTML, ENT_HTML5(각각 XML 1, XHTML, HTML5 문서 표준을 기준으로 문자열을 처리): &apos;로 변환됩니다.
  • ENT_COMPAT: 쌍따옴표(")만 변환하고, 홑따옴표('')는 그대로 둡니다.
  • ENT_NOQUOTES: 쌍따옴표와 홑따옴표를 변환하지 않습니다.
  • ENT_IGNORE: 잘못된 코드 유닛 시퀀스를 무시하고 빈 문자열을 반환하지 않습니다. (보안상 권장되지 않음)
  • ENT_SUBSTITUTE: 잘못된 코드 유닛 시퀀스를 유니코드 대체 문자(U+FFFD 또는 &#xFFFD;)로 대체합니다.
  • ENT_DISALLOWED: 문서 유형에서 허용되지 않는 코드 포인트를 유니코드 대체 문자로 대체합니다. XML 문서 등에서 유용합니다.
  • ENT_HTML401: 문자열을 HTML 4.01 규칙에 맞게 처리합니다.
  • ENT_XML1: 문자열을 XML 1 규칙에 맞게 처리합니다.
  • ENT_XHTML: 문자열을 XHTML 규칙에 맞게 처리합니다.
  • ENT_HTML5: 문자열을 HTML5 규칙에 맞게 처리합니다.
$encoding 옵션. 입력 문자열의 인코딩을 지정합니다. 기본값은 null이며, 이 경우 php.ini 파일의 default_charset 설정을 따릅니다. 대부분의 경우 'UTF-8'을 명시적으로 지정하는 것이 좋습니다. 지원하는 값은 다음과 같습니다.
  • 'ISO-8859-1': Western European, Latin-1
  • 'ISO-8859-5': 거의 사용되지 않는 키릴 문자셋 (Latin/Cyrillic)
  • 'ISO-8859-15': Western European, Latin-9. Euro 기호와 Latin-1에 없는 일부 프랑스어, 핀란드어 문자 포함
  • 'UTF-8': ASCII 호환 다중 바이트 8비트 유니코드
  • 'cp866': DOS용 키릴 문자셋
  • 'cp1251': Windows용 키릴 문자셋
  • 'cp1252': Western European용 Windows 문자셋
  • 'KOI8-R': 러시아 문자셋
  • 'BIG5': 번체 중국어, 주로 대만 사용
  • 'GB2312': 간체 중국어, 중국 국가 표준
  • 'BIG5-HKSCS': Big5 + 홍콩 확장, 번체 중국어
  • 'Shift_JIS': 일본어 문자셋
  • 'EUC-JP': 일본어 문자셋
  • 'MacRoman': Mac OS에서 사용되던 문자셋
  • ''(빈 문자열): 스크립트 인코딩, default_charset, 현재 로케일 순으로 자동 감지 (권장하지 않음)
참고: 다른 문자 집합은 인식되지 않습니다. 기본 인코딩이 대신 사용되고 경고가 표시됩니다.
$double_encode 옵션. 이미 HTML 엔티티로 변환된 문자열을 다시 변환할지 여부를 결정합니다. 기본값은 true입니다.
  • true: 이미 엔티티로 변환된 문자를 다시 변환합니다. 예를 들어, &amp;와 같은 기존의 HTML 엔티티를 &amp;&amp;와 같이 다시 변환합니다.
  • false: 이미 엔티티화된 문자는 변환하지 않습니다. 불필요한 중복 변환을 막고 싶을 때 사용합니다.

반환 값

인코딩된 문자열을 반환합니다.

변경 이력

htmlspecialchars() 함수의 변경 이력
버전설명
8.1.0 $flags가 ENT_COMPAT에서 ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401로 변경되었습니다.
8.0.0 $encodng은 이제 null 값을 가질 수 있습니다.

활용 예제

PHP 
$str = '<script>alert("\n,;[]")</script>';
echo htmlentities($str);

var_dump($encoded);
// 출력: string(52) "&lt;script&gt;alert(&quot;\n,;[]&quot;)&lt;/script&gt;"

참고문헌

같이 보기