WordPress 2.1 のアタッチメント API

WordPress 2.1 ではアタッチメント(編集画面からアップロードされた画像などのファイル) 管理のための API が拡張され、それ以前と比べて格段に充実しています。アタッチメント関連のプラグイン作者向けに、WordPress 2.1 の変更ポイントや今後の方向性についてまとめました。

参考: Hitting WordPress Attachment Handling by mdawaffe

DB スキーマの変更

WordPress のアタッチメントは変種のポストで、そのポストメタとしてファイルのパスや画像のサイズ、サムネイルのファイル名などの付随情報を保持する仕組みになっています。

通常のポストと静的なページ、さらにアタッチメントを区別するために、WordPress 2.0 までは posts テーブルの post_status が使われてきましたが、WordPress 2.1 では post_type が使われるようになりました。post_type 自体は以前からあったものですが WordPress 2.0 では使われていませんでした。

WordPress 2.0

カラム名	取り得る値
post_status	publish, draft, private, static, attachment
post_type	(N/A)

WordPress 2.1

カラム名	取り得る値
post_status	publish, draft, private, inherit, future
post_type	post, page, attachment

WordPress 2.1 ではアタッチメントの post_type は attachment に、 post_status は inherit に指定されます。inherit は「継承する」という意味なので、この場合アタッチメントの post_status は親ポストの post_status を継承するという扱いになります。

アタッチメント API

wp-includes の post.php と post-template.php に追加されたアタッチメント関連関数についてまとめます。

wp-includes/post.php

get_attached_file($attachment_id)

アタッチメントのファイルパスを返す。具体的にはアタッチメントの _wp_attached_file ポストメタに保存されたファイルパスを返す。適用フィルタ: get_attached_file

update_attached_file($attachment_id, $file)

アタッチメントのファイルパスを _wp_attached_file ポストメタに保存する。すでに値があればそれを更新する。適用フィルタ: update_attached_file

is_local_attachment($url)

URL がローカルのリソースを指していて、かつそのリソースがアタッチメントである場合に真を返す。

wp_insert_attachment($object, $file, $post_parent)

アタッチメントを保存する。既存のアタッチメントであれば更新する。$object は連想配列(wp-admin/upload-functions.php での実際の使われ方を見るとわかりやすい)。アタッチメントの ID を返す。適用フィルタ: content_save_pre, content_filtered_save_pre, excerpt_save_pre, title_save_pre, category_save_pre, name_save_pre, comment_status_pre, ping_status_pre, post_mime_type_pre 実行アクション: edit_attachment, add_attachment

wp_delete_attachment($attachment_id)

アタッチメントを削除する。コメントやポストメタなど付属のレコードとファイルも一緒に削除する。サムネイルは他のアタッチメントで使われていないことを確認して削除する。適用フィルタ: wp_delete_file 実行アクション: delete_attachment

wp_get_attachment_metadata($attachment_id)

アタッチメントの _wp_attachment_metadata ポストメタを返す。適用フィルタ: wp_get_attachment_metadata

wp_update_attachment_metadata($attachment_id, $data)

アタッチメントの _wp_attachment_metadata ポストメタを保存する。すでに値があればそれを更新する。適用フィルタ: wp_update_attachment_metadata

wp_get_attachment_url($attachment_id)

アタッチメントの URL を返す。具体的にはアタッチメントの GUID を返す。適用フィルタ: wp_get_attachment_url

wp_get_attachment_thumb_file($attachment_id)

サムネイルのファイルパスを返す。適用フィルタ: wp_get_attachment_thumb_file

wp_get_attachment_thumb_url($attachment_id)

サムネイルの URL を返す。適用フィルタ: wp_get_attachment_thumb_url

wp_attachment_is_image($attachment_id)

アタッチメントが画像(JPEG, GIF, PNG)であれば真を返す。拡張子が判断の基準になる。

wp_mime_type_icon($mime)

MIME タイプ別アイコンの URL を返す。$mime には MIME タイプかまたはアタッチメントの ID が指定できる。適用フィルタ: icon_dir, icon_dir_uri, wp_mime_type_icon

wp-includes/post-template.php

the_attachment_link($attachment_id, $fullsize, $max_dims)

内部で get_the_attachment_link を呼び出し、結果を書き出す。

get_the_attachment_link($attachment_id, $fullsize, $max_dims)

アタッチメント URL へのリンクを返す。内部で get_attachment_innerHTML を呼び出し、結果が a 要素の内容になる。

get_attachment_icon_src($attachment_id, $fullsize)

アタッチメントのアイコンを、アイコンの URL とファイルパスからなる配列として返す。$fullsize が偽で(偽がデフォルト)、かつサムネイルがある場合はサムネイルをアイコンとして使う。それ以外の場合はアタッチメント本体、MIME 別のアイコンの順でアイコンを探す。適用フィルタ: icon_dir

get_attachment_icon($attachment_id, $fullsize, $max_dims)

アタッチメントのアイコンを img 要素として返す。内部で get_attachment_icon_src を呼び出し、結果の URL が src 属性の値になる。$max_dims が指定されている場合は width 属性と height 属性の指定により表示サイズに上限をかける。$max_dims は画像の横と縦のピクセル数からなる配列。適用フィルタ: attachment_max_dims, attachment_icon

get_attachment_innerHTML($attachment_id, $fullsize, $max_dims)

アタッチメント URL へのリンクで使われる a 要素の内容を返す。内部で get_attachment_icon を呼び出し、アイコンが返された場合はそのアイコンを返し、アイコンがない場合はアタッチメントのタイトルを返す。適用フィルタ: attachment_innerHTML

今後の方向性

WordPress 2.1 で API の充実が見られましたが、アタッチメントについてはまだ大きな問題が残されています。

最たるものはファイルの絶対パス保存の問題です。WordPress ではファイルパスを絶対パスとして DB に保存しますが、これはポータビリティを損ねる要因になります。

たとえばブログを別のサーバに移し替えるようなケースを想像してみてください。ほとんどの場合、元サーバと新サーバでディレクトリ構成が異なるため、絶対パスで保存されたファイルパスは新サーバでは意味をなさなくなります。この結果アップロードされたファイルが見つからないなどの不具合が起こります。

これに対してファイルパスを相対パスで保存する改善案が現在上がっており、予定では4月にリリースされる WordPress 2.2 で導入されることになっています。

その他にサムネイルの作成をプラグインで変更できるようにする変更が WordPress 2.2 で予定されており、これによりビデオや PDF などの非画像ファイルのサムネイル作成がプラグインから可能になります(tam-attachment が前からやっていたことに近いですが、この変更により tam-attachment も以前よりシンプルなやり方で実現できるようになるはずです)。