wp_upload_dir() の使い方｜説明・引数・注意点

説明

基本構文

wp_upload_dir( string|null $time = null, bool $create_dir = true, bool $refresh_cache = false ): array

引数

• $time：年月（yyyy/mm）。省略すると現在
• $create_dir：ディレクトリを作成するか
• $refresh_cache：キャッシュを更新するか

戻り値

path、url、basedir、baseurl、error などを含む配列。

使い方（サンプル）

$dir = wp_upload_dir();
$base_url = $dir['baseurl'];

注意点

• error が false でない場合は、ディレクトリを作成できていません。
• ファイルを保存する場合は path、URLが欲しい場合は url を使います。

実務での使いどころ

• ファイルを、アップロードフォルダへ保存するとき。
• アップロードされたファイルの、URLやパスを組み立てるとき。

よくあるミスと対処

• 戻り値は配列。文字列として使うと、エラーや「Array」になる。
• パス用のキー（path・basedir）と、URL用のキー（url・baseurl）を取り違える。
• error を確認していない。ディレクトリを作成できないときは、メッセージが入る。

NG例

file_put_contents( wp_upload_dir() . '/a.txt', $data ); // 配列なので、パスにならない

OK例

$dir = wp_upload_dir();
if ( empty( $dir['error'] ) ) {
	file_put_contents( $dir['path'] . '/a.txt', $data );
	$url = $dir['url'] . '/a.txt';
}

使い分け早見表

関連項目

wp_get_attachment_url()、wp_handle_upload()、get_theme_file_path()

公式リファレンス：wp_upload_dir() | Function | WordPress Developer Resources