ACF（advanced custom fields）を使ってのfile項目入出力

ACFのプラグインからも、functions.phpからも、ファイルアップロード項目の設定を出来ますが、返り値を配列にした場合、どのキーになんのデータが入るのかという情報がなかなか検索できなかった為、したためさせていただきます。

ACF側の設定(下記のように設定をした場合）

このコードを入れることで、ACFの管理画面で手動設定をしなくても動作します。
これは「ACF Local JSON」と呼ばれる機能の一つで、PHPコードでフィールドを直接定義する方法です。

コードでフィールドを設定する場合のメリット：

• サイト移行が容易（ACFの設定をデータベースからエクスポート/インポートする必要がない）
• バージョン管理が可能（コードとしてGitなどで管理できる）
• 複数の環境で同じ設定を簡単に共有できる

ACF管理画面でフィールドを設定する場合のメリット：

• GUIで視覚的に設定できる
• 設定内容をリアルタイムで確認できる
• コードを書く必要がない

使い分けとしては：

• 開発時や複数サイトで同じ設定を使う場合 → PHPコードで定義
• 1サイトのみで使用し、頻繁に設定を変更する場合 → ACF管理画面で設定

function register_newsletter_acf_fields() {
  if(function_exists('acf_add_local_field_group')):
    acf_add_local_field_group(array(
      'key' => 'group_newsletter',
      'title' => 'ニュースレターPDF',
      'fields' => array(
          array(
              'key' => 'field_pdf_file',
              'label' => 'PDFファイル',
              'name' => 'pdf_file',
              'type' => 'file',
              'return_format' => 'array',  // 戻り値を配列にしたい場合
              'library' => 'all',
              'mime_types' => 'pdf'
          ),
      ),
      'location' => array(
          array(
              array(
                  'param' => 'post_type',
                  'operator' => '==',
                  'value' => 'newsletter',
              ),
          ),
      ),
    ));
  endif;
}
add_action('acf/init', 'register_newsletter_acf_fields');

取得方法

// 取得方法
$pdf_file = get_field('pdf_file');

// 取得できる配列の内容
array(
    'ID'          => 123,                      // 添付ファイルのID
    'url'         => 'http://..../sample.pdf', // ファイルのURL
    'title'       => 'サンプルPDF',            // タイトル
    'filename'    => 'sample.pdf',             // ファイル名
    'filesize'    => 12345,                    // ファイルサイズ
    'author'      => '1',                      // 投稿者ID
    'type'        => 'application/pdf',        // MIMEタイプ
    'subtype'     => 'pdf',                    // サブタイプ
    'description' => '説明文',                 // 説明
    'caption'     => 'キャプション',           // キャプション
)

使用例

$pdf_file = get_field('pdf_file');
if($pdf_file) {
    echo '<a href="' . esc_url($pdf_file['url']) . '">';
    echo esc_html($pdf_file['title']);
    echo '(' . size_format($pdf_file['filesize']) . ')';
    echo '</a>';
}

※esc_url()は、URLを安全にエスケープする関数で、XSSなどの攻撃を防ぎます。
主な機能:

• 危険な文字をエンコード
• 許可されたプロトコル(http, https, mailto等)のみ通過
• 不正なURLを空文字列に変換

※esc_html()
HTML特殊文字をエンティティに変換する関数で、XSSなどの攻撃を防ぎます。
主な変換:

& → &
< → &lt;
> → &gt;
" → &quot;
' → &#039;

※size_format()

• バイト数を人間が読みやすい形式に変換する関数です
• 単位を自動的に調整します(B, KB, MB, GB)
• 小数点以下は最大1桁まで表示