【WordPress】Filesystem API 「request_filesystem_credentials」の使い方メモ

request_filesystem_credentialsを使っている例は、WordPress本体の中から見つけられます。

テーマ編集ページである /wp-admin/themes.php では、テーマファイルの削除でdelete_theme関数を呼び出しており、そのdelete_theme関数の中でFilesystem APIが使われており、request_filesystem_credentialsも当然呼び出されています。

そのソースコードはこちら「/wp-admin/includes/theme.php」

細かい呼び出し方やエラーハンドリングはリンク先のソースを読めば参考になるのですが、とりあえず概要を言うと、「request_filesystem_credentialsでファイルの操作権限を取得」して、「その権限オブジェクトをWP_Filesystem」に渡すと、「$wp_filesystemというFilesystem API呼び出し用オブジェクトが利用可能になる」という３ステップです。

ソースコードの雰囲気は次のようになります。

global $wp_filesystem;
...
$redirect = wp_nonce_url('themes.php?action=delete', 'delete-theme'); // nonce付きURL作成
if ( false === ($credentials = request_filesystem_credentials($redirect)) ) { // 権限取得
...エラー対策...
}
if ( ! WP_Filesystem($credentials) ) { // 権限登録
...エラー対策...
}
...
$wp_filesystem->delete( $theme_dir, true); // Filesystem APIの呼び出し
...

さて、この流れでまず難しいのが、wp_nonce_urlを使って、リダイレクト用URLを作り、それをrequest_filesystem_credentialsに渡している点です。

そもそもリダイレクトなんてどうして起こるんだ？と思ってしまうのですが、それはrequest_filesystem_credentialsの機能を知ればよくわかります。

実は、request_filesystem_credentialsの「権限取得」は、ユーザーにFTPアカウント・パスワードの入力を要求する画面を表示する機能も含んでいます。

もちろん、FTPパスワードが必要ないサーバ環境であれば、尋ねること無く権限が取得できるのですが、FTPパスワードのような、ユーザーからの追加情報が必要になった場合は、追加情報を受け取るフォームを表示してしまいます。

つまり、一度目的のページから離れることになってしまいます。

じゃぁ、FTPパスワードを送信（POST）した後はどうなるのか。そのPOSTの送信先URLを $redirect で指定していたのです。

基本的に、このリダイレクトURLは、もう一度やり直すようなことを意味するので、request_filesystem_credentialsを呼び出すに至ったPOSTリクエストのURLをもう一度登録してあげるのに近いかたちになると思います。

そして、そのPOSTメッセージを、しっかりと処理して、もう一度同じ処理のrequest_filesystem_credentialsのところまで戻ってくれば、今度はrequest_filesystem_credentialsが、その入力されたFTPパスワードなどを$_POSTから読み込むので、今度はめでたくフォームを表示すること無く認証オブジェクト（$credentials）が取得でき、そのまま処理（Filesystem関連操作）を継続できる、というわけです。

また、このような場合であっても、nonceのチェックは必須であるため、nonce付きのURLを生成し、POSTを処理する部分では、check_admin_referer（※wp_verify_nonceは？）を使って、nonceを確認することになります。

request_filesystem_credentialsには、先ほどの$redirect (本当の関数定義的には$form_post)以外にも、$type、$error、$context、$extra_fieldsがあります。

ここで注目したいのが$extra_fieldsです。

request_filesystem_credentialsのソースを読むと、先ほど紹介したフォームを生成するコードの本当に最後の最後で、$extra_fields (array) に対して「foreach ( (array) $extra_fields as $field ) 」でループを行い、type=hiddenのinputタグに対して、$_POST[$field]の値をコピーしています。

つまり、もともとのPOST（request_filesystem_credentialsにたどりつく原因になったPOST）のパラメータを、request_filesystem_credentialsが表示するフォームのPOST先に引き継ぐ作業をしているようです。

なので、引き継いでほしいパラメターの名前を、最後の引数 $extra_fields に array( 'field1', 'field2' ) のように指定しておいたほうが良さそうです（あまり確認していない）。