PHP

テーマカスタマイズ関係でWordPressコアのコードを調べた

テーマカスタマイザーにカラーピッカーを追加する際、引数をどうすればいいか分からなくて困ってしまったので、コアのコードまで辿って調べました。

関連記事:テーマカスタマイザーに自由にカスタマイズ項目を追加する方法

CodexのテーマカスタマイズAPIにはずばり、カラーピッカーを追加する際の例が載ってます。

$wp_customize->add_control( 
  new WP_Customize_Color_Control(
     $wp_customize,
    'link_color',
     array(
       'label'      => __( 'Header Color', 'mytheme' ),
       'section'    => 'your_section_id',
       'settings'   => 'your_setting_id',
     ) ) );

しかし、この引数になってる配列には何を指定すればいいのか、よく分かりません。というか、書いてありません。本家の英語版Codexも解説内容は同等です。「add_controlメソッドも参照せよ」とありますので移動します。

クラスリファレンスに飛びました、WordPressコアの仕様書です。
Class Reference/WP Customize Manager/add control

$wp_customize->add_controlメソッドが取る引数はCodexによると下記の通り。

Parameters
$id
(mixed) (required) A string or a specific customization controller object. Default: None
$args
(array) (required) Not used if $id is a control object, otherwise an instance of WP_Customize_Control() (plain text) is created using the specified arguments. Default: None

WP_Customize_Manager/add_control

第一引数は文字列かコントローラーオブジェクトが必須です。
第二引数の配列は、第一引数がオブジェクトの場合は使われないので、add_control()への引数はオブジェクト1個で、今回はnew WP_Customize_Color_Control()ですね。

ということは、WP_Customize_Color_Controlクラスのコンストラクタ引数を確認すればいいわけです。

しかし、その説明がWP_Customize_Color_Controlクラスのリファレンスにありません。

テーマカスタマイザーAPIのコード例と同じ!

Codexの右上の検索フォームからWordPress.org内を検索するとCodexでなくdeveloper.wordpress.orgのクラスリファレンスが見つかります。

Code Reference WP_Customize_Color_Control

しかし、コードリファレンスはまたしてもこれだけです。

説明らしい説明がありませんので、表示されているWordPressコアのコードもみてみます。

/**
 * Constructor.
 *
 * @since 3.4.0
 * @uses WP_Customize_Control::__construct()
 *
 * @param WP_Customize_Manager $manager Customizer bootstrap instance.
 * @param string               $id      Control ID.
 * @param array                $args    Optional. Arguments to override class property defaults.
 */
  • 第一引数:カスタマイズマネージャーのインスタンス
  • 第二引数:ID(識別子)
  • 第三引数:デフォルトのプロパティを上書きするための配列 (オプショナル、渡さなくてもいい)

記述はありましたが、結局、コンストラクタ引数の配列には何を入れたらいいんでしょうか?

ここで注目すべきはclass-wp-customize-color-control.php の最初の宣言です。

class WP_Customize_Color_Control extends WP_Customize_Control

WP_Customize_Color_ControlWP_Customize_Controlを継承したクラスです。
WP_Customize_Controlをベースに、カラーピッカーを表示するために必要な変数、関数を追加する形になっています。

よって、インスタンス引数は WP_Customize_Control と同じでよい、ということです。

参考:PHP公式 オブジェクトの継承

ということで、 CodexのWP_Customize_Cotrolリファレンスを確認します。

ようやく、辿り着きました。Arguments以下の定義リストが WP_Customize_Color_Controlにも指定できる引数一覧です。

テーマカスタマイザーに自由にカスタマイズ項目を追加する方法の記事では、ここから必要な項目のみを指定しています。

ちなみにWP_Customize_Controlクラスのリファレンスからソースコードをたぐると、コメントのConstructorセクションに引数の説明があります。

PHP7を単体でインストールする

例によってWindows10です。
ちょっとphpで書かれたツールを使ってます。phpのコードがコーディング規約に沿っているか調査&修正してくれるPHP CodeSnifferです。
しかし、私のWindows10にはphpの実行環境がインストールされていません。
WordPressのテーマを書いているのに!
そこで、phpの実行環境のみをインストールしました。
展開して、パスを通すだけ。簡単。

パッケージの選択

それでは、php公式サイトから単体の実行ファイルをダウンロードしましょう。
http://php.net/downloads.php
「Windows Downloads」とかあるから、ここでしょう。
php-downloads
リンクを先へ進むと……
php7-for-win
いくつもありますね、バージョンが7.0/5.6  x86/x64 スレッドセーフ・ノンスレッドセーフ。  一体どれがよいのやら。そしてVC14とは?
ご安心下さい、ちゃんと案内があります。読みましょう。
Windows 上での PHP の手動インストール

Non-Thread-Safe(NTS) – IIS やその他の FastCGI ウェブサーバー (Apache と mod_fastcgi など) 用。また、コマンドラインのスクリプト用にもおすすめ。
x64 PHP 7.0+ の実運用環境用 (ただし、32ビット版のWindowsでは使えない)。

私のPCはWindows10 64bitで、今回の主たる用途はコマンドラインです。
なのでx64 Non-Thread-Safe(NTS) 版をダウンロードします。

展開して配置

Zipを解凍して、フォルダごとCドライブ直下のphpフォルダに入れました。
フォルダの位置はどこでもよいです。
zip-decomp

パスを通す

Windows10ではパスを通す=環境変数へのPATH追記も人道的な記述方法になりました。

コントロールパネル > システム > システムの詳細設定 > 環境変数

と進みます。
set-path-process
ここでPATHを選択するとWindows7までは長い長い文字列の後ろに
C:\なんとかかんとかフォルダ名
を追記していました。
Windows10になって、リストで一覧できるようになりました!
(もっと早くこの機能は付けられなかったのか?)
ここに先に展開したphpのフォルダパスを追記します。

Visual Studio C++コンパイラのインストール

実行時に「DLLがない」とエラーが出る場合、コンパイラがインストールされてません。
PHP7.0を動かすにはVisual Studio 2015のVisual C++コンパイラが必要です。

PHP For Windows
The VC14 builds require to have the Visual C++ Redistributable for Visual Studio 2015 x86 or x64 installed

Microsoftより提供されていますので、インストールします。
Visual Studio 2015 の Visual C++ 再頒布可能パッケージ
x86/x64は、ダウンロードしたパッケージに合わせて選びましょう。
どっちも入れておいて問題ない気もします。
私のPCではVisual C++ 2012(VC11)などはx86/x64両方、ビルド番号違いで計4つも入っていました。

動作確認

Windows PowerShellなどでバージョンを確認してみましょう。

> php -v

php-v
表示されました。私のPCではバージョンは7.0.9です。
(2016年10月現在の最新は7.0.12)
これでPHP CodeSnifferが使えます。
CodeSniffer/WordPress用規約のインストールは今回は扱いませんが、サンプルとして掲載します。WordPressのテーマテンプレートへ実行するとこんな感じです。
codesniffer-sample
47行目に「インデントにスペースは許可されていない、タブを使うこと」というアラートが出ていますね。
また「PHPCBFにてFIX可能」とも。
そうです、CodeSnifferではコーディングスタイルの修正もできます。

「パスを通す」とは何なのか

「パスを通す」というと大体は「ここを開いてこれを追記しとけ」としか書いてありません。
Q.パスを通さなければコマンドからexeファイルは実行できないのか?
A.通さなくても、フルパスで指定すれば実行できます。
non-path
他にも、私はTV録画の動画フォーマットの変換にffmpegというアプリケーションを使ってます。
コマンドラインやバッチから操作できます。Youtubeがこれをカスタマイズして使っているとも。
自分のPCで、ffmpegを使う際はフルパスで

C:\ffmpeg\bin\ffmpeg.exe ^
-f mp4 -t 0:30:00 -aspect 16:9 -s 1440x1080 -r 29.97 -bufsize 10000 ^
なんか大量のオプション指定が4行ぐらい

と指定しています。
自分用のバッチ処理でディレクトリも固定なので、フルパスで指定しています。
「環境変数のパスに追記する」すなわち「パスを通す」とは、OSに「コマンドを実行するためのファイルはここにあるよ」ということをあらかじめ伝えておく方法なのです。
他のアプリケーションからの呼び出しは常にフルパスとは限りません。
また、仮にフルパスで書いたとして、どこに実行ファイルがあるかは分かりません。
今回の例ではC:\phpに入れていますが、Dドライブに入れていても、コマンドの実行そのものには問題ないです。
(Windows側の制約で、exeファイルの実行できるフォルダが制限されている場合もあります。)
一方、環境変数で「パスの設定」をしておけば、コマンドの実行ごとにフォルダから指定しなくても、OSが実行ファイルを探してくれます。
インストーラーから入れると、この辺りのOSへの設定をやっておいてくれる場合も多いです。
以上、phpの単体インストールは、要点を押さえておけば実は簡単だという紹介でした。
特にPATHは知っておいて損はないです。