안녕하세요.

린치핀소프트 한광희입니다.

“워드프레스 함수 주석 이해하기!”

워드프레스의 테마&플러그인 개발을 하면서 가장 많이 참조하는 문서는 WordPress Codex입니다. 저는 테마나 플러그인 개발을 하면서 과거 프로젝트에서 작성했던 코드들도 참조하여 재사용을 하지만 그래도 WordPress Codex문서를 참조할 수 밖에 없는 때가 종종 있습니다.

테마나 플러그인에서 이용되어야 할 함수API에 대한 자세한 명세를 보기위해서 Codex를 이용하는 편이죠. 하지만 이 Codex는 위키(Wiki)시스템이고 워드프레스 개발진은 항시 릴리즈되는 워드프레스 최신 버전에 맞추어 위키가 갱신되도록 책임지지는 않고 있습니다. 위키 시스템의 특성그대로 전세계 워드프레스 개발자들이 위키문서를 계속 수정,업데이트하여 만들어 나가는 시스템이기 때문이죠. 이렇게 워드프레스가 최신 릴리즈된후 위키문서가 갱신이 안되었을때 확실한 API나 함수 명세를 보고 싶을때는 어떻게 해야될까요?

 

그때는 워드프레스 최신버전의 소스코드를 직접 찾아보면 됩니다.

아래는 FTP로 접속한 워드프레스 루트 디렉토리의 리스트입니다.

screenshot-search.naver.com 2015-08-12 21-39-36

 

이 많은 파일들을 모두 워드프레스 코어 파일이라고 볼수 있습니다. 사실 플러그인/테마와 워드프레스 유저가 미디어파일들이 업로드 되는 wp-content 폴더를 제외하고 wp-admin, wp-includes 폴더와 루트디렉토리 하위의 모든 파일들이 “코어 파일”이라고 할 수 있습니다.

이 “코어 파일”들은 워드프레스 시스템 구동에 핵심이 되는 함수와 클래스가 선언되어 있기 때문에, 함부로 수정 및 삭제를 할 경우 워드프레스 시스템 전체가 붕괴될 가능성이 있습니다.

워드프레스는 GPL 라이센스 기반의 오픈소스로서 라이센스에서는 이런 코어파일들의 “수정”도 허용됩니다. 자신이 워드프레스의 어떤 시스템의 변경이 필요하거나 정말 코어시스템 자체를 수정해야한다면 수정할 수는 있다는 거죠.

하지만, 워드프레스 커뮤니티에서는 이 “코어 파일”들의 수정을 권장하지 않고 오히려 금지하는 편입니다.

워드프레스의 최신버전이 릴리즈되어 워드프레스를 업데이트 할 경우 워드프레스의 코어파일들이 최신 버전의 파일들로 “덮어 쓰기”되어 수정되는데, 이때 수정한 소스까지 덮어씌어져 추가로 코어를 수정한 부분이 결국 변경이 되지 않기 때문입니다. 이를 막기 위해서는 워드프레스 업데이트 이후 다시 수정코드를 추가해주어야 하는데, 매 업데이트 때마다 수정하고 변경하기에는 아주 귀찮고 업데이트도 수동으로 해야하므로 보안패치라든가 프로그램의 최신 보완이 뒤쳐질수 있죠.

이런 현상은 테마를 업데이트할때도 유사한 현상이 발생되는데요. 유료테마를 구입하고 해당 테마를 커스터마이징 하면서, 테마또한 최신버전으로 지속적으로 업데이트하여 유지하고 싶을때 테마 개발자들이 “자식 테마(Childe Theme)”를 이용하여 수정된 부분이 최신업데이트를 통해 초기화되는것을 막는 개발방법이죠. 이렇게 테마 개발을 진행하며 유료 테마인 부모테마가 최신 버전으로 업데이트 되어도 자식테마는 변경이 되지 않지요.

 

 

다시 오늘 포스트 주제로 돌아와서, 이제 WordPress Codex가 아닌 워드프레스 파일 자체에서 API와 주석에 대해 이해하는 방법을 알아보겠습니다.

저는 워드프레스에 “.js” 스크립트를 등록하고 추가하는 “wp_enqueue_script” 함수에대해서 알아보도록 하겠습니다.

우선 위의 함수가 정의된 목록은 찾는 방법중 가장 쉬운것은 워드프레스 전체 폴더에서 위의 함수를 검색하여 찾는 것입니다.

보통 함수가 선언된 부분을 찾아야 하기에 “function 함수명”을 검색합니다.

저는 “function wp_enqueue_script”를 검색하여 이 함수가 functions.wp-scripts.php 파일에서 선언되어 있는것을 알아내고 파일에서 함수가 선언되어 있는 부분을 찾았습니다.

 


screenshot-bpconcjcammlapcogcnnelfmaeghhagj 2015-08-12 21-51-06

 

함수 명의 위의 있는 /** ~ */ 이 부분이 모두 주석부분으로 함수에 대한 설명을 담고 있습니다.

/**
* Enqueue a script.

*
* Registers the script if $src provided (does NOT overwrite), and enqueues it.
* : 가장 먼저 함수에 대한 설명이 나옵니다. script를 등록 또는 큐에 추가한다는 것을 알수 있습니다.
* @see WP_Dependencies::add(), WP_Dependencies::add_data(), WP_Dependencies::enqueue()
* @global WP_Scripts $wp_scripts The WP_Scripts object for printing scripts.
* : 이 함수 내부에서 사용되는 Global(전역변수)의 목록과 함수에 대한 설명입니다. 여기서는 $wp_scripts 전역변수가 이용됨을 알수 있습니다.
* @since 2.6.0
* : since 부분은 해당 함수가 워드프레스의 어느 버전부터 등록되었는지를 말해줍니다. wp_enqueue_scirpt는 워드프레스 2.6.0 버전에서 추가된 함수임을 알수 있습니다.
* @param string $handle Name of the script.
* @param string|bool $src Path to the script from the root directory of WordPress. Example: ‘/js/myscript.js’.
* @param array $deps An array of registered handles this script depends on. Default empty array.
* @param string|bool $ver Optional. String specifying the script version number, if it has one. This parameter
* is used to ensure that the correct version is sent to the client regardless of caching,
* and so should be included if a version number is available and makes sense for the script.
* @param bool $in_footer Optional. Whether to enqueue the script before </head> or before </body>.
* Default ‘false’. Accepts ‘false’ or ‘true’.

* : @param은 Parameter를 의미하며 각 파라미터의 타입과 해당 파라미터가 함수에서 어떻게 활용되는지을 알려줍니다. 위의 함수에서 마지막 매개변수를 지정된 $in_footer는 기본값으로 false로 지정되어 있고 true일 경우에는 </body>태그 이전에 해당 script가 추가되며 false일 경우에는 </head> 태그 이전에 스크립트가 추가되는것이라고 알 수 있습니다.
*/

 

워드프레스의 함수 주석들은

1. 함수의 간단한 설명

2. 전역변수 또는 참조되어지는 클래스 목록과 메서드

3. 등록 시기(since)

4.매개변수

등의 정보로 이루어져 있고 대부분의 핵심 API의 함수들이 위처럼 소스코드에 함수주석이 기입되어 있습니다.

 

워드프레스 시스템 개발을 하다가 Codex문서뿐만 아니라 위처럼 간단한 검색을 통해 해당 함수의 API의 함수주석을 참조하면 더욱 명확히 함수를 파악하여 개발할 수 있는 이점이 있습니다!