워드프레스 functions.php 직접 수정이 위험한 이유와 안전한 기능 추가 방법
워드프레스에서 몇 줄의 PHP 코드만 추가해도 관리자 화면, 게시물 표시 방식, 사용자 권한, 테마 동작 등을 바꿀 수 있습니다. 그래서 검색 결과에는 “functions.php에 코드를 추가하세요”라는 안내가 자주 등장합니다. 다만 이 파일은 단순한 설정 파일이 아니라 워드프레스가 테마를 불러올 때 함께 실행하는 PHP 파일입니다. 문법 오류 하나로 사이트와 관리자 화면이 동시에 열리지 않을 수 있고, 부모 테마를 직접 수정하면 다음 업데이트에서 변경 내용이 사라질 수 있습니다.
안전한 커스터마이징의 핵심은 코드를 어디에 넣느냐보다 기능의 소속을 먼저 구분하는 데 있습니다. 현재 테마의 디자인이나 출력 방식에 속한 코드는 자식 테마에서 관리하고, 테마를 바꿔도 남아야 하는 사이트 기능은 별도 플러그인으로 분리하는 편이 유지보수에 유리합니다.
functions.php는 실행되는 테마 코드다
functions.php는 현재 활성화된 테마에서 필요한 PHP 동작을 등록하는 파일입니다. 테마의 기능 지원 설정, 스타일과 스크립트 등록, 특정 화면의 출력 변경, 워드프레스 훅(hook) 연결 등에 사용할 수 있습니다. 훅은 워드프레스가 특정 시점에 사용자 코드를 실행하도록 연결하는 장치입니다.
중요한 점은 이 파일이 활성화된 테마와 함께 동작한다는 사실입니다. 테마를 바꾸면 기존 테마의 functions.php는 더 이상 실행되지 않습니다. 따라서 사이트 전체에서 계속 필요한 기능을 이곳에 넣으면 디자인과 운영 기능이 서로 묶이는 문제가 생깁니다.
작은 코드라도 PHP 문법 오류가 있으면 문제가 커질 수 있습니다. 닫히지 않은 괄호나 따옴표, 잘못된 함수 선언, 이미 사용 중인 함수명 재선언, 존재하지 않는 함수나 클래스를 호출하는 코드 등이 대표적인 원인입니다. 코드 스니펫 플러그인을 사용해도 이 위험 자체가 사라지는 것은 아닙니다.
부모 테마 직접 수정이 업데이트에 취약한 이유
부모 테마의 functions.php를 직접 고치는 방식은 처음에는 가장 간단해 보입니다. 그러나 테마 업데이트가 진행되면 기존 테마 파일이 새 버전으로 교체되는 것이 일반적입니다. 이 과정에서 직접 추가한 코드가 삭제될 수 있습니다.
예를 들어 몇 달 동안 사용자 정의 코드를 쌓아 둔 뒤 보안 패치나 기능 개선을 위해 테마를 업데이트했다고 가정해 보겠습니다. 업데이트 후 특정 기능이 사라졌다면 플러그인 문제가 아니라 테마 파일 교체로 인해 코드가 없어졌을 가능성도 확인해야 합니다.
업데이트 전 파일을 백업하는 것만으로는 충분하지 않습니다. 백업에서 복원할 수는 있지만, 매번 변경 내용을 다시 확인하고 적용해야 하므로 관리 부담이 커집니다. 더 나은 방법은 애초에 업데이트되는 원본 파일과 사용자 코드를 분리하는 것입니다.
테마 관련 코드는 자식 테마에서 관리한다
자식 테마는 부모 테마의 디자인과 기능을 바탕으로 필요한 변경 사항을 별도로 관리하는 구조입니다. 부모 테마가 제공하는 기본 템플릿을 사용하면서 자식 테마에 추가 파일과 사용자 정의 코드를 둘 수 있습니다. 부모 테마가 업데이트되어도 자식 테마의 파일은 별도로 유지됩니다.
테마의 레이아웃, 특정 영역의 표시 방식, 현재 디자인에만 필요한 PHP 동작처럼 테마와 밀접한 기능이라면 자식 테마가 자연스러운 위치입니다. 다만 자식 테마의 functions.php가 부모 테마 파일을 자동으로 대체하는 것은 아닙니다. 부모 파일 전체를 복사해 수정하는 방식도 피해야 합니다. 필요한 코드만 자식 테마의 functions.php에 추가해야 부모 테마의 기존 기능과 불필요하게 충돌할 가능성을 줄일 수 있습니다.
자식 테마를 사용한다고 해서 테마와 무관한 모든 기능까지 그 안에 넣어야 하는 것은 아닙니다. 사이트의 핵심 기능이 테마 변경과 함께 사라져도 되는지 먼저 판단해야 합니다.
테마와 무관한 기능은 플러그인으로 분리한다
사용자 역할 처리, 사이트 운영 규칙, 관리 도구, 외부 서비스 연동처럼 디자인과 관계없이 계속 유지되어야 하는 기능은 별도 플러그인이 더 적합합니다. 테마에 기능을 넣으면 테마를 바꾸는 순간 해당 로직도 함께 중단되지만, 플러그인으로 분리하면 테마 변경의 영향을 덜 받습니다.
사이트 전용 플러그인
이 플러그인은 반드시 규모가 클 필요가 없습니다. 사이트 하나에서만 사용할 작은 PHP 기능을 모은 사이트 전용 플러그인(site-specific plugin)으로도 충분합니다. 여러 인터넷 자료에서 가져온 코드를 functions.php 끝에 계속 붙이는 것보다 기능별로 설명을 남기고 하나의 관리 단위로 묶는 편이 나중에 오류를 찾기 쉽습니다.
MU Plugin
일반 플러그인은 관리자 화면에서 활성화와 비활성화를 할 수 있습니다. 반면 MU Plugin(Must-Use Plugin)은 보통 wp-content/mu-plugins 디렉터리에 PHP 파일을 두면 자동으로 로드됩니다. 관리자가 실수로 비활성화하면 안 되는 사이트 수준의 기능에 유용하지만, 자동 활성화라는 특성 때문에 존재를 잊기 쉽고 관리자 화면의 일반 플러그인 목록에서 다루는 방식과도 다릅니다. 꼭 필요한 경우에만 사용해야 합니다.
코드 스니펫 플러그인은 편리하지만 검토가 필요하다
PHP 파일을 직접 열지 않고 사용자 정의 코드를 관리하려면 코드 스니펫 플러그인을 이용할 수 있습니다. 스니펫별로 활성화하거나 비활성화할 수 있는 도구라면 여러 코드를 하나씩 시험하거나 문제가 된 코드를 끄기도 편합니다.
하지만 입력 위치만 바뀌었을 뿐 PHP 코드는 여전히 사이트에서 실행됩니다. 출처가 불분명한 코드를 그대로 붙여 넣기 전에 어떤 훅에서 실행되는지, 관리자에게만 적용되는지, 모든 방문자 요청에서 실행되는지 확인해야 합니다. 오래된 워드프레스나 PHP 버전을 기준으로 작성된 코드는 현재 환경에서 경고나 오류를 일으킬 수도 있습니다.
코드에는 목적, 추가한 날짜, 관련 테마나 플러그인, 참고한 공식 문서, 제거했을 때 영향을 받는 기능을 짧게 기록해 두는 것이 좋습니다. 특히 여러 개의 스니펫을 관리할수록 주석과 이름 규칙이 원인 추적 시간을 크게 줄여 줍니다.
운영 사이트에 바로 넣기 전 확인할 것
PHP 코드를 수정하기 전에는 오류가 발생해도 파일을 되돌릴 수 있는 경로를 확보해야 합니다. 호스팅 업체의 파일 관리자, SFTP, SSH 등 현재 서버 환경에서 사용할 수 있는 방법을 미리 확인해 두어야 합니다. 관리자 페이지가 열리지 않더라도 문제 코드를 제거할 수 있어야 합니다.
가능하다면 다음 순서로 작업하는 편이 안전합니다.
- 운영 사이트 파일과 데이터베이스를 백업합니다.
- 운영 환경과 비슷한 스테이징 사이트를 준비합니다.
- 스테이징에서 코드를 추가하고 문법 오류와 실제 기능을 확인합니다.
- 로그인, 로그아웃, 글 작성, 주요 페이지, 모바일 화면 등 관련 기능을 테스트합니다.
- 문제가 없을 때 운영 사이트에 반영하고 변경 내용을 기록합니다.
워드프레스 관리자 파일 편집기는 접근성이 좋지만 변경 이력을 관리하기 어렵고, 저장 즉시 운영 사이트에 영향을 줄 수 있습니다. 여러 사람이 사이트를 관리한다면 누가 무엇을 왜 바꿨는지 남기기도 어렵습니다. 작은 수정이라도 스테이징이나 최소한 복구 가능한 파일 접근 방법을 먼저 준비하는 이유입니다.
기능의 소속에 따라 위치를 정하면 된다
판단 기준은 다음처럼 단순화할 수 있습니다.
| 기능의 성격 | 둘 곳 | 테마를 바꾸면 | 관리자가 끌 수 있나 |
|---|---|---|---|
| 현재 테마의 디자인·출력에만 필요 | 자식 테마 functions.php |
함께 사라짐 | 테마 교체로 |
| 테마와 무관한 운영 기능 | 사이트 전용 플러그인 | 그대로 유지 | 가능 |
| 실수로 꺼지면 안 되는 사이트 기능 | MU Plugin | 그대로 유지 | 불가(파일 삭제만) |
| 짧은 코드를 켜고 끄며 시험 | 코드 스니펫 도구 | 도구에 따라 다름 | 가능 |
반대로 부모 테마의 원본 functions.php를 장기간 직접 수정하는 방식은 피하는 편이 좋습니다. 코드를 추가하기 전에 “테마를 바꿔도 이 기능이 남아야 하는가?”, “관리자 화면이 막혀도 파일을 복구할 수 있는가?”, “다음 업데이트 후에도 이 코드를 다시 확인할 방법이 있는가?”를 점검해 보세요.
워드프레스 커스터마이징에서 중요한 것은 현재 한 번 작동하는 코드가 아닙니다. 업데이트 이후에도 유지되고, 문제가 생겼을 때 원인을 추적할 수 있으며, 필요할 때 안전하게 제거할 수 있는 구조가 더 오래 갑니다.
