개발자 가이드

  • XE3 엔진
  • 일반적인 가이드
  • 언어 작성 표준
    • PHP 작성 표준 (psr-2)
    • 보완 PHP 작성 표준
    • HTML 작성 표준
    • Javascript 작성 표준
    • CSS 작성 표준
  • 데이터베이스 가이드
  • 보안 가이드
  • 플러그인 로드
  • 설치와 삭제
  • 번역
  • 환경 설정

XE3 엔진

XE를 설치하기 위해서는 아래의 요구사항이 만족되어야 합니다.

  • 웹서버(Apache, Nginx 등)
  • PHP 7 이상(XE3.0.0-beta.24 부터)
    • PDO PHP Extension
    • cURL PHP Extension
    • FileInfo PHP Extension
    • GD PHP Extension
    • Mbstring PHP Extension
    • OpenSSL PHP Extension
    • Zip PHP Extension
  • MariaDB or MySQL 5.1 이상
  • 터미널 접속 환경
  • 디스크 300M 이상의 여유 공간
    • 500M 이상 권장

XE3는 아래와 같은 사항들이 지켜져야 합니다.

  • Deprecated 된 함수는 사용하지 않습니다
  • 관리자 코드는 다른 공개된 코드와 별개로 작성되어야합니다. auth()→user()→isAdmin()를 사용해서 관리자인 지 확인할 수 있습니다.
  • 모든 함수와 클래스, 콜백, 변수, 데이터베이스에는 구분되는 식별자 접두어(prefix)를 붙여 다른 플러그인과 충돌이 일어나지 않도록 방지해야 합니다.
  • 필요한 기능들이 이미 XE3에서 제공되는 경우 만들어진 것을 그대로 사용합니다.
  • 타사의 API 호출은 적극적으로 캐싱하여 추가적인 호출이 없도록 제한해야 합니다.
  • 작성된 플러그인이 이전 버전에 호환되도록 작성된 경우에도 XE3 최신 버전에서 작동하도록 설계해야 합니다. 다른 타사 플러그인이 중요한 업데이트를 수신하도록 설정되어 있을 수 있으므로 사용자가 이전 버전을 계속 사용한다고 볼 수 없습니다.

일반적인 가이드

  • 모든 도큐먼트는 온라인 상에서 공개되어 있거나 오프라인상에서 아카이빙 파일을 포함하여 제공되어야 합니다.
  • 사용자에게 충분히 고지하지 않고 허가받지 않았다면, 플러그인은 어떤 데이터도 해당 서버를 포함한 어느 제3의 서버에 전송할 수 없습니다.
  • 플러그인은 관리자페이지를 통해서 프리미엄 서비스를 상향하거나 광고를 포함해서는 안됩니다. (유로플러그인과 무료플러그인은 별개로 작성되어야 합니다.)
  • 사용자 정의 업데이트 로직이 다른 업데이트를 감지 못하게 하거나 알람을 표시하지 않게 하거나 업데이트 처리를 못하도록 방해해서는 안됩니다.
  • 사용자에게 플러그인을 활성화하거나 리뷰를 남기도록 요청하는 전역 알림 메시지는 허용되지만 사용자가 해지 할 수 있어야 하며 해지되면 다시 표시 되어선 안됩니다.

언어작성 표준

PHP 작성 표준 (psr-2)

  1. PHP 파일
    • 모든 PHP 파일은 Unix LF 줄마침을 사용합니다.
    • 모든 PHP 파일은 마지막에 공백줄 하나가 삽입되어야 합니다.
    • PHP파일이 PHP언어만 가질 경우에 PHP 마감 문법인 '?>'은 사용하지 않습니다.
  2. 줄(lines)
    • 강제적으로 한 줄의 길이를 제한하지는 않습니다.
    • 권장하는 가장 보수적인 길이는 120자 입니다. 스타일 체커는 경고는 하지만 에러는띄우지 않을 것 입니다.
    • 보통 80자를 넘어가지 않도록 작성합니다. 그 이상을 넘어가면 줄을 바꿔서 작성합니다.
    • 비어있지 않는 줄의 마지막에 공백을 넣어선 안됩니다.
    • 코드의 가독성을 위해서 구분되는 코드블록 사이에 공백줄을 넣을 수 있습니다.
    • 한 줄에 하나 이상의 주석이 있어선 안됩니다.
  3. 들여쓰기(Indent)
    • 코드는 하나의 4번의 띄어쓰기를 사용해 구분합니다. 탭을 사용하지 않습니다.
  4. PHP 키워드와 true/false/null
    • PHP 키워드는 소문자(lower case)로 작성합니다.
    • true/false/null도 소문자로 작성합니다.
  5. 네임스페이스와 선언
    • 네임스페이스를 선언한 후에 반드시 공백줄을 하나 아래에 추가합니다.
    • use는 반드시 네임스페이스 공백줄 아래부터 작성합니다.
    • 선언할 때마다 use 하나를 사용합니다.
    • use블록 다음에 반드시 공백줄을 하나 아래에 추가합니다.
  6. 클래스, 속성, 메소드
    1. 상속과 구현
      • extends와 implements는 반드시 클래스네임과 같은 줄에 작성합니다.
      • implements하는 클래스가 많은 경우에는 implements 다음 줄바꿈한 후에 클래스를 한줄에 하나씩 작성합니다.
    2. 속성
      • 범위(public, private, protected)는 반드시 모든 변수에 선언되어야합니다.
      • var는 변수명으로 사용할 수 없습니다.
      • 한 문장에 하나 이상의 속성이 선언되어선 안됩니다.
      • protected나 private 속성을 나타낼 때에 하나의 밑줄(_)을 접두어로 사용할 수 없습니다.
    3. 메소드
      • 범위(public, private, protected)는 반드시 모든 메소드에 선언되어야합니다.
      • protected나 private 속성을 나타낼 때에 하나의 밑줄(_)을 접두어로 사용할 수 없습니다.
      • 메소드명 이후에 공백을 두어선 안됩니다. 바로 다음 줄에 중괄호로 열고나서 그 다음줄에 코드를 작성하고 작성을 마친후 그 다음 라인에서 중괄호로 닫습니다.
      • 여는 중괄호 위나 닫는 중괄호 아래에 공백이 있으면 안됩니다.
    4. 메소드 전달자(arguments)
      • 콤마 이전에 공백을 두지 않고 콤마 이후에 공백을 하나 넣어 작성합니다.
      • 기본값을 선언하는 전달자의 경우에는 목록에 가장 나중에 삽입합니다.
      • 메소드명과 전달자를 여는 소괄호사이에 공백은 두지 않습니다.
      • 한 줄에 넣기 많은 전달자를 사용하는 경우에는 여러 줄에 나누어 삽입할 수 있습니다. 여는 소괄호를 작성하고 줄바꿈을 한 이후에 들여쓰기를 하고 전달자 하나와 콤마 하나를 한 줄에 삽입합니다.
      • 여러 줄에 전달자를 나누어 삽입하는 경우에 목록을 닫는 소괄호는 메소드를 시작하는 중괄호와 같은 줄에 배치시킵니다.
    5. abstract, final, and static
      • abstract와 final은 범위(public, private, protected)앞에 선언합니다.
      • static은 뒤에 선언합니다.
    6. 메소드와 함수 호출
      • 메소드와 함수를 호출 할 때에는 호출하는 클래스와 메소드명 사이에 공백을 넣지 않습니다.
      • 전달자를 시작하는 소괄호에도 공백을 넣지 않습니다.
      • 각 전달자 사이의 콤마에만 뒤에 공백을 붙입니다.
      • 전달자를 여러 줄에 나누어 작성할 때가 있습니다. 메소드를 작성할 때와 마찬가지로 각 항목과 괄호를 한 줄에 담아 나누어 작성합니다.
  7. 제어 연산자
    1. if, elseif, else
      • 소괄호 양쪽으로 공백을 작성합니다. 여는 중괄호 이후에 공백없이 줄바꿈을 하고, 닫는 중괄호 이 후에 else가 오는 경우에 여는 중괄호를 같은 줄에 작성합니다.
    2. switch
      • if와 마찬가지로 중괄호를 열고 닫습니다.
      • case를 작성할 때에는 줄바꿈후에 들여쓰기를 해야합니다. 이후 코드와 break문은 한번 더 들여씁니다.
    3. while, do while
      • if와 마찬가지로 중괄호를 열고 닫습니다.
      • do while 문의 경우에도 do에 괄호가 없을 뿐 while문과 동일하게 작성합니다.
    4. for
      • if문과 마찬가지로 중괄호를 열고 닫습니다.
      • 소괄호 내의 세미콜론 앞에는 공백을 삽입하지 않고, 뒤에 삽입합니다.
      • 각 비교연산자의 양 옆으로 공백을 삽입합니다.
    5. foreach
      • as 양 옆에는 공백을 붙입니다.
    6. try, catch
      • if, elseif 문과 크게 다르지 않습니다.
  8. 클로져
    • function 키워드와 use 키워드 양쪽에는 공백을 삽입합니다.
    • 되도록 function 과 use를 한 줄에 삽입하며, 다른 함수와 마찬가지로 중괄호까지 연후에 줄바꿈 합니다.

XE용 PHP 작성 표준 개선

PSR-2 권고안을 그대로 사용하되 몇 군데를 완화하거나 수정하여 사용합니다.

  • 여백(들여쓰기)은 코드의 논리적인 구조에 맞추어서 일정하게 이루어져야 합니다.
  • 탭은 여백의 대안으로 사용할 수 있습니다.
  • 테스트할 때에 config/production/app.php 파일에 debug값을 true로 맞추면 디버깅항목이 뷰페이지에 나타납니다.
  • 코드는 기본 PHP의 알림이나 경고 에러를 일으켜서는 안됩니다.
  • PHP파일은 <?php 로 시작하고 축약형 <?은 사용하지 않습니다.
  • PHP 파일은 BOM(byte of mask)이 제거된 UTF-8 으로 작성되어야합니다. ( UTF-8 without BOM)
  • POSIX Regex 함수(ereg_*)를 사용하는 것은 허용되지 않습니다.
  • 모호한 비교연산자인 ==보다는 ===와 같은 엄격한 비교연산자를 사용하도록 합니다.
  • 블록은 항상 중괄호를 사용합니다. 여는 중괄호는 함수 정의, 조건부 또는 루프와 같은 줄에 있어야합니다. 닫는 중괄호는 블록의 마지막 문 바로 다음 줄에 위치해야 합니다.
  • eval() 함수는 사용하지 않습니다.
  • 규모가 큰 소스는 종속성관리를 하는 것이 좋습니다.

HTML 작성 표준

  • 분류되지 않은 태그, 중첩 오류, 중복 된 ID 등은 심각한 에러이지만 브라우저별로 중요하지 않은 에러로 처리하거나 무시될 수 있습니다. 작성자는 W3C 유효성 검사기를 통해 모든 코드를 실행하는 것이 좋습니다.
  • HTML도 마찬가지로 논리적인 구조에 맞추어 여백이 이루어져야 합니다.
  • 마찬가지로 탭도 여백의 대안으로 사용될 수 있습니다.

Javascript 작성 표준

  • JS 코드 스타일은 standardJS를 권장합니다.
  • Modern browser에 최적화하고, IE10 및 IE9 또한 고려될 수 있습니다. 오류로 인해 사이트 이용에 영향을 주지 않도록해야 합니다.
  • 템플릿에 JS 코드를 작성하지 않고 .js 파일로 분리하여 작성하는 것을 권장합니다.
  • 브라우저에 로드하여 사용하는 최종 파일은 minify/uglify를 거친 최적화된 형태를 권장합니다.
  • 브라우저에 로드하여 사용하는 최종 파일은 반드시 browserify, babel 등을 이용해 ES5를 지원해야합니다.
  • 여러 DOM 변경은 단일 작업으로 적용되거나 전체 DOM 조각을 제거한 후 요소를 업데이트하고 다시 삽입해야 적용되어야 합니다.
  • PHP와 마찬가지로 블록은 항상 중괄호를 사용합니다. 여는 중괄호는 함수 정의, 조건부 또는 루프와 같은 줄에 있어야합니다. 닫는 중괄호는 블록의 마지막 문 바로 다음 줄에 위치해야 합니다.
  • 정말 필요한 경우가 아니라면 전역 변수/함수는 사용하지 않습니다.
  • 전역 변수/함수가 꼭 필요하면 window.varianceName과 같이 window 객체를 통해 명시적으로 선언하고 사용해야합니다.
  • 전역 변수/함수가 꼭 필요하면 고유한 접두어를 사용해 분리시켜야 합니다.
  • PHP와 마찬가지로 모호한 비교연산자인 ==보다는 ===와 같은 엄격한 비교연산자를 사용하도록 합니다.
  • 다른 함수에서 함수를 중첩 사용해야하는 경우가 있지만 이러한 중첩사용은 종종 성능저하나 좋지 않은 결과를 야기하기도 합니다.
  • 이벤트 리스너 및 다량 호출하여 사용하는 동작에서는 결과 값 등을 변수에 저장하여 불필요한 동작을 줄여야 합니다.
  • 지역 변수를 재선언하는 것은 권장하지 않습니다.
  • 3개 이상에 요소에 동일한 함수를 바인딩한다면 익명 함수보다는 명명된 함수를 사용합니다.
  • 코드는 개발자콘솔에서 어떠한 알림이나 에러도 생성해서는 안됩니다.
  • 코드는 standardJS 규칙을 통과해야 합니다. standardJS 페이지에서 텍스트 에디터 플러그인 및 툴에 대한 정보를 찾아볼 수 있습니다.

CSS 작성 표준

  • 셀렉터에는 반드시 필요한 것을 제외하고는 태그 이름을 사용하지 않습니다.
  • id와 class는 목적에 맞도록 적절하게 명명되어야 합니다.
  • BEM 이름 규칙 사용을 권장합니다.
  • 태그 이름 등을 사용하여 절대 스타일을 제거(CSS Reset 등)하거나 변경하지 않아야 합니다.
  • id보다 class 기반 작성을 권장하며, prefix 사용을 권장합니다.
  • 지나친 셀렉터 사용은 피하여 가능한 CSS 명시도를 낮춰 최종사용자가 이를 쉽게 변경, 확장할 수 있도록해야 합니다.
  • SASS 등을 사용할 수 있으며, 최종 파일은 CSS 포맷으로 생성해야 합니다.
  • 마크업에 직접적으로 inline CSS를 사용하는 것은 지양합니다.
  • 2개의 공백으로 들여쓰기 합니다.
  • 중괄호는 셀렉터와 같은 줄에서 열고, 마지막 속성 정의에서 줄을 바꿔 닫아야 합니다.
  • 셀렉터와 속성 정의는 줄을 바꿔 구분해야합니다.
  • 모든 속성 정의는 반드시 세미콜론으로 닫아야 합니다. 마지막 항목에 세미콜론을 생략하지 마세요.
  • 섹션을 열고 닫을 때에 사용되는 주석은 유용하고 사용목적을 나타내기 때문에 권장합니다.
  • !important는 절대 사용하지 않습니다.
  • 요소를 다룰때에는 반드시 의도한 요소들만 다뤄지도록 주의해야합니다. 익스텐션, 테마의 이름 등을 활용해 상위 요소에 class를 추가하거나 prefix를 사용하세요.

데이터베이스 가이드

  • 직접적으로 db에 접근하는 것을 금합니다. 대신에 laravel과 xe에서 제공하는 쿼리빌더를 사용해주세요.
  • 플러그인은 최소한의 갯수로 테이블을 생성해야하고, 가능한 변경과 조작이 가능한 게시 유형 및 분류를 사용해야합니다.
  • 모든 쿼리는 sql인젝션에서 보호받아야 하며, DB::beginTransaction(), DB::commit()과 같은 함수를 통해 관리할 수 있습니다.
  • 정적인 데이터에 굉장히 많은 쿼리가 들어가야하는 경우 가능하면 캐싱하세요.
  • *를 통해 모든 정보를 불러오기보다는 필요한 항목만 로드하도록 합니다.
  • 테이블을 생성할 때에는 목적에 따라 일반적으로 검증된 테이블설계를 사용합니다.

보안 가이드

  • 모든 것을 검증하고 필터링하고 이스케이프 합니다.
  • 사용자가 입력한 값이 어플리케이션에 입력되기전에 되도록 충분한 검증과 필터링을 거쳐야 합니다.
  • 사용자 입력을 필터링 할때에는 되도록 화이트리스트 (정해진 포맷 이외는 받아들이지 않음. 반대는 블랙리스트: 정해진포맷외의 모든 것을 받아들임) 방식을 사용하도록 합니다.
  • post방식의 폼을 받을 때에는 csrf 취약점 공격을 방지하기위해 csrf_field() 또는 csrf_token()값을 사용하여 함께 전달합니다.
  • 모든 쿼리는 쿼리빌더를 사용하여 sql 인젝션에서 보호받을 수 있도록합니다.
  • 관리자페이지는 항상 주의를 기울여 권한이 없는 사용자의 접근에서 보호받도록 조치해주십시오.

플러그인 로드

  • XE3 코어에서 사용하고 있는 jQuery 버전은 등록해제하지 않습니다.
  • javascript와 css는 직접적으로 호출하지 않습니다.
  • 이미 XE3 코어에서 등록되어있는 라이브러리를 다른 버전이나 같은 버전의 라이브러리로 교체하여 사용하지 않습니다.

설치와 삭제

  • 플러그인은 비활성화 되어있는 상태에서는 사용하던 데이터를 삭제하지 않아야합니다.
  • 플러그인은 삭제가 되는 시점에서 사용자에게 데이터에 삭제에 대한 안내문구를 띄우고 확인을 받는 절차를 통해 데이터를 삭제하거나 또는 데이터를 지우지않고 보호할 수 있어야 합니다.
  • 데이터를 삭제하기전에 데이터를 import하거나 export할 수 있는 옵션을 제공하여, XE3 외부에 설정을 저장할 수 있도록 합니다.

번역

다음과 같은 다국어 규칙을 적용합니다.

  • 번역가능한 문장 : 모든 텍스트들은 다국어적용이 가능해야하고 적절하게 이스케이프되어 사용자가 테마와 같은 옵션 수정을 하지 않더라도 번역된 내용을 확인할 수 있어야합니다.
  • 번역가능한 변수 : 동적인 내용들은 번역할 수 없으므로 텍스트 문자열에는 상수나 변수가 그대로 들어가서는 안됩니다. __() 함수나 xe_trans 함수를 통해서 미리 정의해둔 언어로케일에 따라서 해당 문자열을 반환할 수 있도록 해주십시오.
  • 도메인 정의 : 상수, 변수 또는 정의를 사용하여 테마의 텍스트 도메인을 정의해서는 안됩니다. 텍스트 도메인은 밑줄(_)이 아닌 대시(-)를 사용해야하며 소문자 일반 텍스트 여야합니다.
  • 불필요한 도메인 정의 : 테마와 관련없는 텍스트 도메인은 허용되지 않으므로 제거해야합니다.
  • 다국어 에셋 : 코어에서 제공하는 다국어파일은 resoures/lang 폴더에, 나머지 플러그인에서 등록하는 언어들은 database에 translation테이블에 등록됩니다. XeLang::save()함수를 사용해서 각 언어에 맞는 언어를 등록할 수 있습니다.
상단으로 이동