functions.phpで失敗しない！WordPress初心者が犯しやすい3つのミス｜現場で使える実践テクニック

#functions.php #PHPコード #WordPress #テーマ開発 #初心者向け
functions.phpで失敗しない！WordPress初心者が犯しやすい3つのミス｜現場で使える実践テクニック
C
クリオ
Web制作ディレクター / フロントエンジニア

こんにちは！
今日は「functions.phpで失敗しない！初心者が犯しやすいミス3つ」について解説します。

functions.phpはWordPressの心臓！でも危険がいっぱい

functions.phpって、めっちゃ便利なやつなんですよ。
テーマ機能の追加、カスタム投稿タイプの登録、スクリプトやスタイルシートの読み込み…本当に何でもできます。
でもその反面、ここに記述したコードに問題があると、ウェブサイト全体が壊れてしまうことも少なくありません。

僕も初心者の頃、functions.phpに適当にコードを追加して、サイト全体が真っ白になったことがあります。
その時の絶望感…ほんまにトラウマでした（笑）

ここからは、僕が現場で見かける「あ、これ初心者さんがやっちゃうよな」というミスを3つ紹介します。
これを知ってるだけで、大きなトラブルを防げますよ。

ミス1：クロージングタグ<?phpを記述してしまう

これ、ほんまに多いです。
functions.phpの一番最後に?>って書いちゃう人、めっちゃいます。

WordPress公式のルールでは、functions.php（とその他のテーマファイルの大部分）は、クロージングタグの?>を記述してはいけません。
なぜなら、ファイルの最後に余白があると、それが画面に出力されてしまう可能性があるからです。

特にヘッダーが既に出力された後だと、HTTPエラーが発生したり、JSONレスポンスが壊れたりするんです。

正しいコード例：

<?php
// コードをここに書く
add_action( 'wp_enqueue_scripts', 'my_custom_scripts' );
function my_custom_scripts() {
    wp_enqueue_style( 'my-style', get_stylesheet_uri() );
}
// ここで終わり。?>は書かない

間違った例：

<?php
// コードをここに書く
add_action( 'wp_enqueue_scripts', 'my_custom_scripts' );
function my_custom_scripts() {
    wp_enqueue_style( 'my-style', get_stylesheet_uri() );
}
?>  // これはダメ！削除しましょう

僕のチームでは、functions.phpを作成する時に、テンプレートから?>を自動で削除する仕組みを入れています。
そのくらい重要なルールです。

ミス2：古いフック名を使ってしまう

WordPressは毎回のバージョンアップで、ちょくちょくフック（add_actionやadd_filter）が変わります。
古いブログ記事やStack Overflowの回答をそのままコピペすると、これに引っかかることが多いです。

例えば、スクリプトを読み込む場合：

古いやり方（wp_head内で読み込み）：

<?php
add_action( 'wp_head', function() {
    echo '<script src="my-script.js"></script>';
} );

新しいやり方（wp_enqueue_scriptsを使う）：

<?php
add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script( 'my-script', get_template_directory_uri() . '/js/my-script.js', array(), '1.0', true );
} );

新しいやり方の方が、キャッシュの管理やスクリプトの依存関係を自動で処理できるので、めっちゃおすすめです。

現場では「なぜかスクリプトが反映されない」という相談をよく受けますが、大体これなんですよ。
古いコードの遺産が残っているパターンです。

バージョンを確認する癖をつけるといいですよ。
WordPress本体のバージョン番号、そしてそのバージョンで廃止されたフックはないか、チェックしてから実装するといいですよ。

ミス3：プラグインとの競合を防がない

これは、一見すると防ぎようのないように思えるかもしれません。
でも実は、コーディングの工夫で大抵の競合は防げます。

特に気をつけたいのは、グローバル変数やクラス名の名前衝突です。

危ないコード例：

<?php
// これはダメ。他のプラグインと同じ名前の関数があると競合する
function get_posts_custom() {
    // 何か処理
}

// グローバル変数も危ない
$my_data = array();

安全なコード例：

<?php
// テーマプレフィックスをつける
if ( ! function_exists( 'mytheme_get_posts_custom' ) ) {
    function mytheme_get_posts_custom() {
        // 何か処理
    }
}

// グローバル変数も避ける。クラスやクロージャの中で管理する
class MyTheme_Data {
    private $data = array();
    
    public function set_data( $key, $value ) {
        $this->data[ $key ] = $value;
    }
}

これだけで、プラグインとの競合がぐっと減ります。
僕のチームでは、テーマプレフィックスを「mytheme_」みたいに統一しています。

また、function_exists()で関数の重複をチェックするのも大事ですね。
ほんま、この一行が事故を防いでくれることがめっちゃ多いです。

まとめ

functions.phpは、WordPressテーマ開発の中心的なファイルです。
だからこそ、小さなミスが大きなトラブルに繋がることが多いんです。

今日紹介した3つのミスをまとめると：

  • クロージングタグ?>は記述しない
  • 古いフック名を使わない