WordPressのWP_FileSystemとは？ファイル操作で推奨されるAPIについて徹底解説

みなさんこんにちは！エンジニアの高澤です！

今回はファイル操作で推奨されるAPIであるWordPressのWP_FileSystemについて徹底解説していきたいと思います。

WordPressのテーマやプラグインを開発する際に、file_get_contents()関数やfopen()関数などのPHPのファイル操作関数を使用すると、テーマチェックツールで警告が出たり、セキュリティ的な問題を指摘されることがあります。実際、多くの開発者が「なぜダメなの？」と疑問を持ちつつ、代替手段を探した経験があるのではないでしょうか。

WordPressでは、独自のファイル操作APIであるWP_FileSystemを使用することが推奨されています。

このAPIを利用することで、環境に依存しない安全なファイルの読み書きが可能になり、テーマやプラグインをより適切に開発できるようになります。

本記事では、WP_FileSystemの基本概念や使用方法について詳しく解説していきます。

WP_FileSystemとは

WP_FileSystemは、WordPressのファイル操作を行うためのAPIです。

WordPressの標準機能として提供されているAPIで、セキュリティを考慮しながらテーマやプラグインの開発時にファイルを読み書きするために使用されます。

直接file_put_contents()関数やfile_get_contents()関数、fopen()関数を使用するよりも安全にファイル処理を行うことができるため、WP_FileSystemを使用することが推奨されております。

また、そもそもWordPressで定めたテーマの品質に対するガイドラインに違反した書き方になってしまい、テーマをテストして最新のテーマレビュースタンダードのスペックへの対応状況を確認できるTheme Checkプラグインなどでは、ガイドラインに反しているとして警告されてしまいます。

WP_FileSystemのAPIを利用できる関数であるWP_FileSystem()関数については、以下のWordPress公式ページにて解説しておりますので、よろしければご確認ください。

また、WP_FileSystem APIについてはこちらの公式ページで詳しく解説されておりますので、よろしければ合わせてご活用ください。

https://codex.wordpress.org/Filesystem_API

WP_FileSystemを使用するメリット

WP_FileSystemを使用するメリットは以下になります。

• セキュリティの向上
• 環境に応じた適応
• WordPressの推奨手法

それぞれ解説いたします。

セキュリティの向上

WP_FileSystemを利用する最大のメリットの一つは、セキュリティの向上です。

WordPressでは、file_get_contents()関数やfopen()関数などのPHP標準関数を直接使用すると、適切な権限設定が行われていない場合に不正なアクセスや改ざんのリスクが発生します。特に、サーバーの設定によっては意図しないファイルの読み書きが許可されてしまい、悪意のある攻撃者によって重要なファイルが操作される可能性があります。

WP_FileSystemでは、WordPressの安全性を確保しながら処理できる仕組みが備えられており、安心して開発を進めることができます。

環境に応じて適応

WordPressは、さまざまなサーバー環境で動作することを前提として設計されています。

しかし、サーバーによってはファイルシステムの設定が異なり、標準的なPHPのファイル操作関数が使えない場合があります。例えば、ある環境ではfile_put_contents()関数が利用できるのに対し、別の環境ではセキュリティの制限により実行できないことがあります。

そのため、WP_FileSystemは環境に応じて適切なファイル操作方法を自動で選択する仕組みを持っています。FTP、SSH、Direct（直接ファイル操作）の各方法を適用可能であり、環境に応じた最適なファイル操作手段を自動的に判断します。

これにより、開発者は環境ごとの違いを意識せずに安全にファイルを操作できるようになり、ユーザーにとっても互換性の高いテーマやプラグインを提供しやすくなります。

WordPressの推奨手法である

WordPressの公式開発ガイドラインでは、テーマやプラグインでファイルを操作する場合はWP_FileSystemを使用することが推奨されています。

file_get_contents()関数やfopen()関数などのPHP標準関数を使うと、環境によって動作しないことがあったり、セキュリティリスクが高まったりするため、WordPressの方針に沿った安全な方法を使うことが望ましいとされています。

また、WP_FileSystemを使うことで、WordPressの他の機能との統合が容易になります。例えば、自動更新機能やプラグインのインストール時にもWP_FileSystemが使用されており、WordPressのエコシステムに適応した設計が可能になります。

そのため、テーマやプラグインを作成する際には、互換性を高めるためにもWP_FileSystemを利用するのが理想的です。

WP_FileSystemの初期化方法

WP_FileSystemを使用する際は、まず初期化を行う必要があります。

<?php
if ( ! function_exists( 'WP_Filesystem' ) ) {
    require_once ABSPATH . 'wp-admin/includes/file.php';
}
WP_Filesystem();

初期化後、 $wp_filesystemグローバル変数を使用してファイル操作を行います。

WP_FileSystemを使用したファイル操作

それでは早速、WP_FileSystemを使用したファイル操作について解説いたします。

ここまで色々と説明してきましたが、難しいことは後にして、まずはWP_FileSystemを使いこなせるようにしましょう。

理解を深めていただくために、それぞれコードについて詳細に説明しておりますので、ご確認いただければと思います。

ファイルの読み取り

ファイルの内容を取得する場合は、以下のように記述します。

<?php
global $wp_filesystem;
$content = $wp_filesystem->get_contents( WP_CONTENT_DIR . '/example.txt' );
echo $content;

上記コードは、WordPressのWP_FileSystemを使用して、example.txtというファイルの内容を取得し、画面に出力する処理を行います。

まず、「global $wp_filesystem;」によって、グローバル変数$wp_filesystemを利用できるようにします。この変数には、WP_FileSystemのインスタンスが格納されており、WordPressのファイル操作機能を使用するために必要です。

次に、「$wp_filesystem->get_contents( WP_CONTENT_DIR . ‘/example.txt’ );」によって、WordPressの 「wp-content」ディレクトリ内にあるexample.txtの内容を取得します。WP_CONTENT_DIR定数は、WordPressの「wp-content」ディレクトリのパスを示す定数であり、これを使うことで環境に依存せずに適切なパスを指定できます。

最後に、「echo $content;」によって、取得したファイルの内容を画面に出力します。これにより、example.txtに記載されているテキストが、Webページ上に表示されることになります。

ファイルの書き込み

ファイルにデータを書き込む場合は、次のように記述します。

<?php
global $wp_filesystem;
$file_path = WP_CONTENT_DIR . '/example.txt';
$contents = "新しい内容を追加します。";
$wp_filesystem->put_contents( $file_path, $contents, FS_CHMOD_FILE );

上記コードは、WordPressのWP_FileSystemを使用して example.txtというファイルに新しい内容を書き込む処理を行います。

まず、「global $wp_filesystem;」によって、グローバル変数$wp_filesystemを利用できるようにします。この変数には、WP_FileSystemのインスタンスが格納されており、WordPressの安全なファイル操作を行うために必要です。

次に、「$file_path = WP_CONTENT_DIR . ‘/example.txt’;」によって、example.txtの保存先のパスを設定します。WP_CONTENT_DIR定数は、WordPressの「wp-content」ディレクトリのパスを示す定数であり、環境に依存しない形で正しいパスを取得するために使用されます。

続いて、「$contents = “新しい内容を追加します。”;」によって、書き込む内容を変数$contentsに代入します。これで、「新しい内容を追加します。」という文字列が設定されます。

最後に、「$wp_filesystem->put_contents( $file_path, $contents, FS_CHMOD_FILE );」によって、指定したファイルに$contents変数の内容を書き込みます。FS_CHMOD_FILE定数は適切なファイルの権限を設定するための定数であり、適切なパーミッションでファイルを作成・上書きすることを保証します。

このコードを実行すると、「wp-content」ディレクトリ内にexample.txtというファイルが作成され、そこに「新しい内容を追加します。」というテキストが保存されます。もしexample.txtがすでに存在する場合は、ここでの内容が上書きされます。

ディレクトリの作成

新しいフォルダを作成する場合は、以下のように記述します。

<?php
global $wp_filesystem;
$dir_path = WP_CONTENT_DIR . '/custom-directory';
$wp_filesystem->mkdir( $dir_path );

上記コードは、WordPressのWP_FileSystemを使用して「wp-content」ディレクトリ内に「custom-directory」というディレクトリを作成する処理を行います。

まず、「global $wp_filesystem;」によって、グローバル変数$wp_filesystemを利用できるようにします。この変数には、WP_FileSystem のインスタンスが格納されており、WordPressの推奨する方法でファイルやディレクトリを操作するために必要です。

次に、「$dir_path = WP_CONTENT_DIR . ‘/custom-directory’;」によって、新しく作成したいディレクトリのパスを変数$dir_pathに格納します。WP_CONTENT_DIR定数は「wp-content」フォルダの絶対パスを示すWordPressの定数であり、環境に依存せず正しいパスを取得するために使用されます。

最後に、「$wp_filesystem->mkdir( $dir_path );」を実行することで、「custom-directory」というディレクトリを作成します。「mkdir()」はWP_FileSystemのメソッドであり、適切なパーミッションを考慮した上でディレクトリを作成することが可能です。

このコードを実行すると、「wp-content」ディレクトリ内に「custom-directory」という名前のフォルダが作成されます。すでに同じ名前のフォルダが存在する場合は、フォルダは新しく作成されず、エラーにはならないで処理を終えます。

ディレクトリの作成に失敗した場合は、WP_FileSystemの設定やサーバーの書き込み権限を確認する必要があります。

WP_FileSystemの主なメソッド

WP_FileSystemの主なメソッドを表にまとめましたので、よろしければ実装の際にご確認ください。

しつこくて恐縮ですが、テーマやプラグイン開発時には、直接 file_get_contents()関数や fopen()関数を使うのではなく、これらのメソッドを活用するのが推奨されています。

WP_FileSystem を利用すると、サーバー環境に応じた安全なファイル操作が可能になりますので、ぜひ活用していきましょう。

ここからは簡単にサンプルコードを掲載しておきます。

実装コードを記述する際の感覚を掴んでいただければと思います。

ディレクトリの削除

$dir_path = WP_CONTENT_DIR . '/custom-folder';
if ( $wp_filesystem->is_dir( $dir_path ) ) {
    $wp_filesystem->rmdir( $dir_path );
    echo "ディレクトリを削除しました。";
} else {
    echo "削除するディレクトリが見つかりません。";
}

ファイルの削除

<?php
$file_path = WP_CONTENT_DIR . '/example.txt';
if ( $wp_filesystem->exists( $file_path ) ) {
    $wp_filesystem->delete( $file_path );
    echo "ファイルを削除しました。";
} else {
    echo "削除するファイルが見つかりません。";
}

ファイルのコピー

<?php
$source = WP_CONTENT_DIR . '/original.txt';
$destination = WP_CONTENT_DIR . '/copy.txt';
$wp_filesystem->copy( $source, $destination, true );
echo "ファイルをコピーしました。";

ファイルの移動

<?php
$source = WP_CONTENT_DIR . '/copy.txt';
$destination = WP_CONTENT_DIR . '/moved.txt';
$wp_filesystem->move( $source, $destination, true );
echo "ファイルを移動しました。";

ファイルの権限を変更

<?php
$file_path = WP_CONTENT_DIR . '/moved.txt';
$wp_filesystem->chmod( $file_path, 0644 );
echo "ファイルの権限を変更しました。";

ファイルが存在するか確認

<?php
$file_path = WP_CONTENT_DIR . '/moved.txt';
if ( $wp_filesystem->exists( $file_path ) ) {
    echo "ファイルは存在します。";
} else {
    echo "ファイルは存在しません。";
}

指定したパスがファイルかどうか確認

<?php
$file_path = WP_CONTENT_DIR . '/moved.txt';
if ( $wp_filesystem->is_file( $file_path ) ) {
    echo "これはファイルです。";
} else {
    echo "これはファイルではありません。";
}

指定したパスがディレクトリかどうか確認

<?php
$dir_path = WP_CONTENT_DIR . '/some-folder';
if ( $wp_filesystem->is_dir( $dir_path ) ) {
    echo "これはディレクトリです。";
} else {
    echo "これはディレクトリではありません。";
}

ファイルサイズを取得

<?php
$file_path = WP_CONTENT_DIR . '/moved.txt';
$file_size = $wp_filesystem->size( $file_path );
echo "ファイルサイズ: " . $file_size . " バイト";

ファイルのタイムスタンプを更新

<?php
$file_path = WP_CONTENT_DIR . '/moved.txt';
$wp_filesystem->touch( $file_path );
echo "ファイルのタイムスタンプを更新しました。";

全てのメソッドを確認する方法

WP_FileSystem の利用可能なメソッドをすべて一覧表示する方法として、get_class_methods()関数を使用すると、オブジェクトに登録されているメソッドを確認できます。以下のコードを実行すると、WP_FileSystem のメソッドを一覧で取得できます。

<?php
if ( ! function_exists( 'WP_Filesystem' ) ) {
    require_once ABSPATH . 'wp-admin/includes/file.php';
}
WP_Filesystem();
global $wp_filesystem;

echo "<pre>";
print_r( get_class_methods( get_class( $wp_filesystem ) ) );
echo "</pre>";

上記コードを実行すると、下図のように WP_FileSystem クラスで使用できるメソッド一覧が表示されます。

当記事で紹介しきれていないものに関してはこちらからご確認いただけましたら幸いです。（随時WordPressコアの方で増えたりしているかもしれないので）

まとめ

今回は、WordPressのファイル操作で推奨されるAPI「WP_FileSystem」について解説しました。

WordPressのテーマやプラグイン開発では、file_get_contents()関数や fopen()関数などのPHP標準のファイル操作関数を使用すると、テーマチェックツールで警告が出たり、セキュリティリスクを指摘されることがあります。そのため、WordPressでは環境に依存せず、安全にファイルを操作できるWP_FileSystemの利用が推奨されています。

WP_FileSystemを適切に活用することで、安全性と互換性を確保しながら、より洗練されたテーマやプラグインの開発が可能になります。ぜひ実際のお仕事などの実践に役立ててください。