라이믹스에도 1년 전부터 xpressengine/xe-core#1267 이 적용되어 템플릿에서 escape, noescape 등 간단한 필터의 사용이 가능했으나, 용도가 제한적이어서 널리 사용되지 못하고 있었습니다. 그래서 필터 기능을 대폭 확충하여 편리하게 사용할 수 있도록 하고, 기존의 escape 관련 문법도 여기에 흡수시켰습니다.

필터는 템플릿 컴파일 시점에 PHP 함수로 변환되고, 이후 캐시된 파일을 사용하므로 함수를 직접 사용하는 것과 속도 차이는 없습니다. 단, 필터를 많이 사용하는 템플릿을 처음 컴파일할 때 다소 시간이 소요될 수 있습니다.

필터 개요

템플릿에서 변수를 출력할 때

{$var|필터1|필터2|필터3}

이런 문법을 사용하면 나열한 필터들이 순서대로 적용됩니다.

구분에 사용되는 문자는 백스페이스 키와 + 키 사이에 있는 | (파이프 문자)입니다.

현재 지원하는 필터 목록

간단하게 지원할 수 있는 필터부터 먼저 넣었습니다. 세계적으로 많이 사용되는 템플릿 엔진들을 참고하여 더 많은 필터를 추가할 예정입니다.

• escape : 변수에 htmlspecialchars() 함수를 적용합니다.
• autoescape : 변수에 htmlspecialchars() 함수를 적용하되, 이미 인코딩된 & 같은 특수문자는 다시 인코딩하지 않습니다. (대부분의 경우 가장 적합한 방법)
• noescape : 템플릿에 auto-escape (htmlspecialchars 자동 적용) 기능 추가 xpressengine/xe-core#1267 의 방법대로 <config>를 사용하여 모든 변수에 htmlspecialchars() 함수를 일괄 적용하도록 설정해 두었더라도 이 변수에는 적용하지 않습니다. (글 내용 등 태그를 유지해야 하는 변수에만 사용)
• escapejs : 변수를 자바스크립트 문자열에 안전하게 넣을 수 있도록 인코딩합니다. (문자열의 일부로 출력하는 경우 사용, 양쪽에 따옴표 필수)
• json : 변수를 JSON으로 인코딩합니다. (배열이나 객체 등을 자바스크립트로 전달할 때 사용)
• strip : 변수에서 태그를 모두 제거합니다.
  • strip:<br> : <br> 태그만 남깁니다.
  • strip:<br><p> : <br><p> 태그만 남깁니다.
  • strip:$tags : 남길 태그 목록을 $tags 변수에서 불러옵니다.
• trim : 변수 앞뒤의 공백을 제거합니다.
• urlencode : 변수를 URL에 안전하게 넣을 수 있도록 인코딩합니다.
• lower : 변수를 소문자로 바꾸어 출력합니다.
• upper : 변수를 대문자로 바꾸어 출력합니다.
• nl2br : 변수 내의 줄바꿈 문자를 모두 <br> 태그로 바꾸어 출력합니다. (주의: nl2br 이후에 escape나 strip을 사용하면 태그가 사라지니 순서에 주의하십시오.)
• join : 배열 내용을 쉼표(,)로 구분하여 나열합니다.
  • join:/ : 배열 내용을 슬래시 문자(/)로 구분하여 나열합니다.
  • join:\| : 배열 내용을 파이프 문자(|)로 구분하여 나열합니다. 필터 구분에도 파이프 문자를 사용하므로 혼동을 막기 위해 여기서는 \를 붙여 \|로 표기해야 합니다.
  • join:$separator : 구분자로 사용할 내용을 $separator 변수에서 불러옵니다.
• date : 날짜 또는 시간을 년-월-일 시:분:초 형식으로 표시합니다. XE에서 흔히 쓰던 14자리 regdate 포맷과 유닉스 타임스탬프를 모두 지원합니다.
  • date:Y.m.d : 날짜 또는 시간을 년.월.일 형식으로 표시합니다.
  • date:H:i : 날짜 또는 시간을 시:분 형식으로 표시합니다.
  • date:$format : 표시할 형식을 $format 변수에서 불러옵니다.
• format : 숫자에 쉼표를 찍어서 표시합니다. (예: 12,345,678)
  • format:2 : 숫자에 쉼표를 찍고, 소수점 아래 2자리까지 표시합니다.
  • format:$num : 숫자에 쉼표를 찍고, 소수점 아래 표시할 자릿수는 $num 변수에서 불러옵니다.
• link : 문자열을 링크로 바꾸어 출력합니다.
  • link:https://www.rhymix.org : 링크할 주소를 직접 지정합니다.
  • link:$url : 링크할 주소를 $url 변수에서 불러옵니다.

필터 사용 예제

변수를 소문자로 바꾸어 출력

{$var|lower}

배열을 하나로 합친 후 (/ 구분자 사용) 특수문자를 인코딩하고 줄바꿈을 <br> 태그로 변환

{$array|join:/|escape|nl2br}

문서 작성 날짜를 년.월.일 형식으로 표시

{$oDocument->get('regdate')|date:Y.m.d}

변수의 특수문자를 인코딩한 후 링크로 변환

{$url|escape|link}

자바스크립트 변수 사용 예제

<script>
    var title = '제목은 {$title|escapejs}입니다';  // 문자열 내에 삽입
    var names = {$names|json};  // 배열을 통째로 전달 (따옴표 없음)
</script>

기타

PHP에서 사용하는 | (bitwise or) 및 || (boolean or) 연산자가 필터 구분자로 잘못 해석되지 않도록, | 문자 앞뒤에 공백이 있거나 | 문자 직후에 특수문자가 나오면 필터로 인식하지 않도록 했습니다.

필터 기능을 사용하지 않는 기존 레이아웃이나 스킨 등과의 호환성 문제는 발생하지 않는 것으로 보이며, 다수의 유닛 테스트를 작성하여 필터의 정상 작동을 확인했습니다.

HTML 필터링과 관련하여 xpressengine/xe-core#1267 과 다른 점이 한 가지 있습니다. autoescape 필터가 더이상 <config autoescape="on" /> 설정의 영향을 받지 않고 항상 htmlspecialchars() 함수를 적용합니다. 이중 인코딩을 하지 않을 뿐입니다. (설정의 영향을 받는 auto 필터는 호환성을 위해 그대로 두었으나 사용을 권장하지 않습니다. 현재 라이믹스 코어에서 이 기능을 사용하는 템플릿은 없습니다.)

기존 방식대로 <config autoescape="on" /> 설정이 되어 있더라도 escape, autoescape 등의 필터를 사용하면 필터가 우선순위를 가지므로 이중으로 인코딩될 위험은 없습니다.

관련 이슈

#269