Функция WP_GET_ATTACHMENT_LINK() в WordPress: параметры, применение, примеры

# Функция WP_GET_ATTACHMENT_LINK() в WordPress

Функция wp_get_attachment_link() помогает получить ссылку на файл вложения или на страницу вложения в WordPress. Она возвращает HTML-код ссылки в формате <a>.

## Когда ссылка будет показана

Ссылка будет отображаться, если файл вложения или страница содержат:
- Изображение заданного размера (для изображений);
- Иконку медиа-файла, соответствующую вложению;
- Заголовок вложения в текстовом формате;
- Или ваш собственный текст.

Если такое вложение не найдено, функция вернет текстовый вывод: **"Missing Attachment"** (отсутствующее вложение).

### Используемые функции
- get_attachment_link()
- wp_get_attachment_url()

### Используемые хуки
- wp_get_attachment_link_attributes
- wp_get_attachment_link

## Возвращаемое значение

Функция возвращает строку:
- HTML-код ссылки.
- __('Missing Attachment'), если вложение не найдено.

## Применение функции

Функция вызывается следующим образом:

```php
wp_get_attachment_link( $post, $size, $permalink, $icon, $text, $attr );

Параметры функции

• $post (int|WP_Post): ID поста или объект поста.
• $size (string|int[]): Размер изображения. Принять можно любое зарегистрированное имя размера изображения или массив значений ширины и высоты в пикс��лях (в этом порядке).
  • По умолчанию: 'thumbnail'.
• $permalink (true|false): Нужно ли добавлять постоянную ссылку на изображение.
  • По умолчанию: false.
• $icon (true|false): Является ли вложение иконкой.
  • По умолчанию: false.
• $text (string|false): Текст ссылки. Активируется, если передать строку, иначе — false.
  • По умолчанию: false.
• $attr (array|string): Массив или строка атрибутов.
  • По умолчанию: ''.

Примеры использования

Пример 1: Получение ссылки на вложение среднего размера

По умолчанию WordPress использует следующие размеры изображений: thumbnail (эскиз), medium (средний), large (большой) и full (полный). Реальные размеры указаны на странице настроек: Настройки > Медиа.

$id = 12144; // ID вложения
echo wp_get_attachment_link( $id, 'medium' );
/*
Результат:

    

*/

Пример 2: Отображение ссылки на страницу вложения

$id = 12144;
echo wp_get_attachment_link( $id, 'thumbnail', true );
/*
Результат: 

    

*/

Пример 3: Установка пользовательского текста для ссылки

$id = 12144;
echo wp_get_attachment_link( $id, '', false, false, 'мой текст ссылки' );
// мой текст ссылки

Пример 4: Использование заголовка поста в качестве текста ссылки

$id = 12144;
echo wp_get_attachment_link( $id, '', false, false, ' ' );
// Оптимизация

Пример 5: Использование иконок для отображения вложений

Для изображений показываются их миниатюры, а для других файлов отображаются специальные иконки, соответствующие типу файла (например, иконка аудио).

Если вам нужно изменить каталог, в котором WordPress ищет такие иконки, создайте папку в теме, например, /wp-content/themes/yourtheme/images, добавьте туда иконки и используйте следующий код в файле functions.php вашей темы:

add_filter( 'icon_dir', 'my_theme_icon_directory' );
function my_theme_icon_directory($icon_dir) {
    return TEMPLATEPATH . '/images';
}

add_filter( 'icon_dir_uri', 'my_theme_icon_uri' );
function my_theme_icon_uri( $icon_dir ){
    return get_bloginfo('stylesheet_directory') .'/images';
}

Изменения в функции

• С версии 2.5.0 функция была введена.

• С версии 4.4.0 параметр $post теперь может принимать как ID поста, так и объект WP_Post.

  function wp_get_attachment_link( $post = 0, $size = 'thumbnail', $permalink = false, $icon = false, $text = false, $attr = '' ) {
  $_post = get_post( $post );
  
  if ( empty( $_post ) || ( 'attachment' !== $_post->post_type ) || ! wp_get_attachment_url( $_post->ID ) ) {
      return __( 'Missing Attachment' );
  }
  
  $url = wp_get_attachment_url( $_post->ID );
  
  if ( $permalink ) {
      $url = get_attachment_link( $_post->ID );
  }
  
  if ( $text ) {
      $link_text = $text;
  } elseif ( $size && 'none' !== $size ) {
      $link_text = wp_get_attachment_image( $_post->ID, $size, $icon, $attr );
  } else {
      $link_text = '';
  }
  
  if ( '' === trim( $link_text ) ) {
      $link_text = $_post->post_title;
  }
  
  if ( '' === trim( $link_text ) ) {
      $link_text = esc_html( pathinfo( get_attached_file( $_post->ID ), PATHINFO_FILENAME ) );
  }
  
  $attributes = apply_filters( 'wp_get_attachment_link_attributes', array( 'href' => $url ), $_post->ID );
  
  $link_attributes = '';
  foreach ( $attributes as $name => $value ) {
      $value            = 'href' === $name ? esc_url( $value ) : esc_attr( $value );
      $link_attributes .= ' ' . esc_attr( $name ) . "='" . $value . "'";
  }
  
  $link_html = "$link_text";
  
  return apply_filters( 'wp_get_attachment_link', $link_html, $post, $size, $permalink, $icon, $text, $attr );
  }