add_permastruct() │ WP 3.0.0

Добавляет новую структуру ЧПУ для постоянных ссылок.

Создает не одно правило, а несколько на основе одной указанной пермаструктуры, какие правила создать определяется в параметре $args и тегах самой структуры...

Объяснение

Структура постоянных ссылок - это абстрактное понятие и означает установку (определение) правил того, как должна выглядеть ЧПУ (человеко-понятная УРЛ).

Эта функция дает возможность быстро создать группу правил (с регулярными выражениями), которые перезапишут URL во внутренние параметры запроса. Новые правила будут добавленные в свойство WP_Rewrite::$extra_permastructs (массив).

Когда правила перезаписи создаются функцией WP_Rewrite::rewrite_rules(), все эти новые перма-структуры передаются в функцию WP_Rewrite::generate_rewrite_rules(), которая в свою очередь превращает их в регулярные выражения и то какой УРЛ должен получится, если регулярка подходит под текущий УРЛ запроса.

Параметр $args дает возможность контролировать как WP_Rewrite::generate_rewrite_rules() будет создавать новую перма-структуру.

Объяснение еще раз, другими словами.

Добавленная структура, например, book/%book% разбирается и на основе нее добавляются нужные правила перезаписи ЧПУ в настройки ЧПУ (смотрите глобальную переменную $wp_query).

Теги указанные в структуре, например %book%, заменяются на соответствующую часть регулярного выражения, которая указывается при регистрации тега перезаписи в add_rewrite_tag().

Если в структуре указаны неизвестные теги, то они не будут заменены на группы регулярного выражения и останутся в правилах перезаписи как есть. Например, ЧПУ получится следующий, если указан незарегистрированный тег %order_id%:

[order/%order_id%/?$] => index.php?%order_id%$matches[1]

Регистрировать тег (плейсхолдер) нужно отдельно с помощью функции add_rewrite_tag().

Эта функция обычно используется в связке с функциями: add_rewrite_tag() и add_rewrite_rule()

Работает на основе метода WP_Rewrite::add_permastruct( $name, $struct, $args ).

Работает на основе: WP_Rewrite()

Хуков нет.

Возвращает

null. Ничего.

Использование

add_permastruct( $name, $struct, $args );

$name(строка) (обязательный)

Название структуры. Название типа записи, для которого создается структура ЧПУ.

$struct(строка) (обязательный)

Сама структура ЧПУ.

$args(массив)

Параметры построения ссылки из указанной структуры.

Подробнее смотрите:

По умолчанию указываются следующие параметры:

$defaults = [
	'with_front'  => true,
	'ep_mask'     => EP_NONE,
	'paged'       => true,
	'feed'        => true,
	'forcomments' => false,
	'walk_dirs'   => true,
	'endpoints'   => true,
];

По умолчанию: [] (предустановки)

Возможные элементы массива:

with_front(логический)
Нужно ли предварять структуру параметром WP_Rewrite::$front.
По умолчанию true.
paged(логический)
Нужно ли добавлять правила для пагинации поста - /post_name/page/xx? Если указать true, то в записи можно будет использовать шоркод . Смотрите wp_link_pages().
По умолчанию true.
feed(логический)
Нужно ли добавлять правила для страниц фидов - /feed/?
По умолчанию true.
forcomments(логический)
Сделать ссылку фидов как запрос на фид комментариев. Будет добавлен параметр &withcomments=1.
По умолчанию false.
walk_dirs(логический)
Если указать true, то правило перезаписи будет создано для каждой директории указанной в структуре. Например, если структура указана как /%year%/%month%/%day/, то правила будут созданы для директорий: /%year%/, /%year%/%month%/ и /%year%/%month%/%day%/.
По умолчанию true.
ep_mask(число)
Указывает какие дополнительные (к базовому ЧПУ) точки входа WordPress должен создавать для правил перезаписи. EP - endpoints.

Объединять параметры нужно через побитовое OR:
```
'rewrite' => [
	'ep_mask' => EP_PERMALINK | EP_ROOT
],
```
Может быть:
```
EP_NONE         // отключает все endpoint-правила (attachment, comments, ...).
EP_PERMALINK    // одиночный пост
EP_ATTACHMENT   // страница вложения
EP_DATE         // любые архивы дат
EP_YEAR         // архив года
EP_MONTH        // архив месяца
EP_DAY          // архив дня
EP_ROOT         // главная страница блога
EP_COMMENTS     // страницы комментариев
EP_SEARCH       // страница поиска
EP_CATEGORIES   // архив рубрики
EP_TAGS         // архив метки
EP_AUTHORS      // архив автора
EP_PAGES        // страницы (post_type=page)
EP_ALL_ARCHIVES // EP_DATE | EP_YEAR | EP_MONTH | EP_DAY | EP_CATEGORIES | EP_TAGS | EP_AUTHORS
EP_ALL          // EP_PERMALINK | EP_ATTACHMENT | EP_ROOT | EP_COMMENTS | EP_SEARCH | EP_PAGES | EP_ALL_ARCHIVES
```
Код построения ЧПУ с этими флагами смотрете в WP_Rewrite::generate_rewrite_rules()

Как работает пошагово:
1. В начале функции значение маски передаётся как есть и больше не меняется.
2. Для каждого каталога структуры вычисляется вспомогательная маска $ep_mask_specific:
  - %year% → EP_YEAR
  - %monthnum% → EP_MONTH
  - %day% → EP_DAY
  - иначе EP_NONE
3. Правила комментариев
  - Если маска содержит EP_PAGES или EP_PERMALINK → добавляются /comment-page-N/.
  - Иначе, если содержит EP_ROOT и задана главная страница → добавляется /comment-page-N/ для корня.
4. Правила энд-поинтов ($this->endpoints)
  Для каждого зарегистрированного энд-поинта:
  - Если (endpoint_mask & $ep_mask) или (endpoint_mask & $ep_mask_specific) истинно → к текущему шаблону URL добавляется правило .../<endpoint>/....
5. Вложенные энд-поинты вложений
  - Для вложений проверяется только EP_ATTACHMENT у самих энд-поинтов, $ep_mask здесь не участвует.
6. Если $ep_mask = EP_NONE (по умолчанию)
  - Комментарии не добавляются.
  - Энд-поинты всё равно добавятся для дат (EP_YEAR|EP_MONTH|EP_DAY), потому что срабатывает ep_mask_specific.
7. Если $ep_mask содержит несколько флагов (например EP_PERMALINK|EP_PAGES)
  - Срабатывают все ветви, условие использует побитовое &.
8. Итог
  $ep_mask влияет только на:
  - генерацию правил постраничных комментариев;
  - выбор энд-поинтов, которые прикрепляются к шаблону URL.
По умолчанию EP_NONE
endpoints(логический)
Нужно ли добавлять конечные точки в конец правил перезаписи ЧПУ? Какие конечные точки добавить указывается в ep_mask.

По умолчанию true.

Примеры

#1 Структура ЧПУ для произвольного типа записи `book`

Допустим при регистрации типа записи с помощью register_post_type() в параметре rewrite мы указали false. И теперь мы хотим вручную установить ЧПУ для этого типа записи, тогда добавим такой код.

add_action( 'init', function(){
	$post_type = 'book';

	$permastruct = "$post_type/%book%"; // структура ЧПУ

	$args = [
		'with_front'  => true,
		'paged'       => true,
		'ep_mask'     => EP_NONE,
		'feed'        => false,
		'forcomments' => false,
		'walk_dirs'   => false,
		'endpoints'   => false,
	];

	add_permastruct( $post_type, $permastruct, $args );

	// добавим тег перезаписи, чтобы add_permastruct() его поняла
	// он потом будет заменен на часть регулярки указанной во втором параметре
	add_rewrite_tag( "%book%", '([^/]+)', "post_type=$post_type&name=" );
} );

Третий параметр в add_permastruct() можно не указывать, тогда аргументы будут по умолчанию.

После установки кода, нужно сбросить правила ЧПУ, для этого нужно просто сохраниться в настройках постоянных ссылок в админке. Или запустить функцию flush_rewrite_rules():

// Only flush rewrite rules, if your permalink changed (e.g. on plugin activation):
flush_rewrite_rules();

Заметки

Смотрите: WP_Rewrite::add_permastruct()
Global. WP_Rewrite. $wp_rewrite WordPress rewrite component.

Список изменений

С версии 3.0.0

Введена.

Код `add_permastruct() add permastruct` ^{WP 7.0}

wp-includes/rewrite.php

function add_permastruct( $name, $struct, $args = array() ) {
	global $wp_rewrite;

	// Back-compat for the old parameters: $with_front and $ep_mask.
	if ( ! is_array( $args ) ) {
		$args = array( 'with_front' => $args );
	}

	if ( func_num_args() === 4 ) {
		$args['ep_mask'] = func_get_arg( 3 );
	}

	$wp_rewrite->add_permastruct( $name, $struct, $args );
}

Денис

Здравствуйте! У меня для структуры

$permastruct = '/persons/%post_id%'

генерируется на постах типа 'persons' пермалинк www.example.com/persons/%post_id%. Никак не могу разобраться что не так...

9.8 лет назад #

Алексей

Поддерживаю вопрос.
Тоже интересно как делать, хочется сделать структуру с ID.

0

9.8 лет назад #
- Kama 9889
  
  Код того как создается тип записи приложите...
  
  0
  
  9.8 лет назад #

add_permastruct() │ WP 3.0.0

Объяснение

Возвращает

Использование

Примеры

#1 Структура ЧПУ для произвольного типа записи book

Заметки

Список изменений

Код add_permastruct() add permastruct WP 7.0

Cвязанные функции

Rewrite (ЧПУ перезапись)

#1 Структура ЧПУ для произвольного типа записи `book`

Код `add_permastruct() add permastruct` ^{WP 7.0}