get_sites(), описание функции, параметры

Функция позволяет получить сайты сети WordPress Мультисайт, соответствующие переданным в неё параметрам.

Мы уже рассматривали с вами подобные функции, например:

• get_terms() – для таксономий,
• get_posts() – для постов

Теперь пришло время познакомиться с функцией, предназначенной для получения / вывода сайтов сети.

get_sites( $args = array() )

Как работать с функцией get_sites() ?

Функция возвращает нам массив объектов WP_Site (если только не заданы параметры count или fields), например:

$sites = get_sites();
 
print_r( $sites );
 
/*
Array
(
	[0] => WP_Site Object
		(
			[blog_id] => 1
			[domain] => misha.blog
			[path] => /
			[site_id] => 1
			[registered] => 2020-01-07 22:14:23
			[last_updated] => 2020-01-13 09:06:55
			[public] => 1
			[archived] => 0
			[mature] => 0
			[spam] => 0
			[deleted] => 0
			[lang_id] => 0
		)
 
	[1] => WP_Site Object
		(
			[blog_id] => 2
			[domain] => misha.blog
			[path] => /surf/
			[site_id] => 1
			[registered] => 2020-01-07 19:15:56
			[last_updated] => 2020-01-13 09:08:43
			[public] => 0
			[archived] => 0
			[mature] => 1
			[spam] => 0
			[deleted] => 0
			[lang_id] => 0
		)
)
*/

В качестве примера давайте выведем ссылки на все сайты сети:

$sites = get_sites();
foreach( $sites as $site ){
	echo '<a href="' . $site->domain . $site->path . '">' . get_blog_details( $site->blog_id )->blogname . '</a>';
}

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

Функция имеет немало параметров (с WP_Query конечно не сравнится), которые позволяют нам четко задать, какие конкретно сайты сети мультисайт мы хотим получить.

site__in

(массив|целое число) Если при помощи функции get_sites() вы хотите получить определённые сайты сети и вы знаете их ID, то передайте айдишники в этот параметр в виде массива. Например array( 1, 5, 10 ), либо, если значение одно, то можете передать его в виде целого числа.

По умолчанию: пустая строка.

site__not_in

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

$sites = get_sites( array( 
	'site__not_in' => get_current_blog_id()
) );

Как видите, я воспользовался функцией get_current_blog_id() для получения ID текущего сайта сети и даже не стал закидывать её в массив.

По умолчанию: пустая строка.

count

Если вы установите этот параметр равным true (по умолчанию false), то функция вернет вам лишь одно целое число – количество сайтов, удовлетворяющих всем остальным значениям параметров.

date_query

Как и посты, мы можем очень детально фильтровать получение сайтов по дате. Вэйт, вэйт, какая дата имеется ввиду в этом случае? Дата регистрации сайта конечно же! 😁

Подробнейшие примеры по работе с date_query вы сможете найти тут.

fields

В каком формате вы хотите ожидать ответ от функции? Как вы помните, я уже сказал чуть выше, что функция возвращает массив объектов WP_Site. Данный параметр позволяет изменить это и вернуть (пока что) только ID удовлетворяющих условиям сайтов. Для этого передайте в него значение: ids.

Ну хорошо, уговорили, пример:

$sites = get_sites( array( 'fields' => 'ids' ) );
/*
 Результат:
 Array
 (
    [0] => 11
    [1] => 251
 )
*/

ID

(целое число) Укажите ID конкретного сайта, который хотите получить.

В чем отличие от site__in ? Без понятия. Если кто знает, велкам в комментарии, обсудим. Кстити говоря, оба параметра – и ID и site__in допускают возможность использования других параметров! Что это значит – если вы указали параметр archived равный единице и передали в параметр ID сайт, который НЕ заархивирован, то функция вернёт пустой массив, о да.

number

(целое число) Тут всё легко – укажите максимальное число сайтов, которые хотите получить.

По умолчанию – Сотня.

offset

(целое число) И тут всё нам должно быть знакомо. Сколько сайтов с начала нужно пропустить. Например если вы укажете offset равным 2, а всего найдено сайтов 5, то будут получены последние 3 сайта.

orderby

(строка|массив) Вот тут и начинают получать смысл наши параметры number и offset. Ведь теперь вы можете выбрать, в каком порядке отображать возвращаемые сайты, параметр может принимать значения:

• id (по умолчанию)
• domain – по доменному имени (в случае если подсайты – на поддоменах/доменах),
• path – по пути (в случае если мультисайт установлен в поддиректории),
• last_updated – сайты сети, в которых недавно были добавлены посты,
• registered – по дате регистрации сайтов,
• domain_length – по длине доменного имени,
• path_length – по длине пути,
• site__in – по порядку, указанному в параметре site__in.

Параметр также принимает значение false, пустой массив или none, если вы хотите вообще отключить в SQL запросе кусок ORDER BY.

Также вы можете указать например два значения orderby в виде массива, тогда сортировка будет сначала по первому параметру, а потом по второму:

$sites = get_sites( array(  
	'orderby' => array( 'registered', 'domain' ) 
	// сначала по дате регистрации, потом по доменному имени
) );

order

(строка) Порядок сортировки:

• ASC – по возрастанию (по умолчанию)
• DESC – по убыванию

domain

(строка) Ограничить получаемые функцией результаты определённым доменом.

domain__in

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

domain__not_in

(массив) Укажите список доменов в виде массива, которые нужно исключать.

path

(строка) Укажите путь сайта, который хотите получить, если вы не уверены, как оно должно выглядеть, можете найти намёки в таблице wp_blogs в базе данных, не забывайте также слеши в начале и в конце.

path__in

(массив) Список путей сайтов, которые включить в результат.

path__not_in

(массив) Список путей сайтов, которые вы хотите исключить из результата.

public

(целое число) Если указать 1 (по умолчанию), то возвращает все открытые сайты, 0 – закрытые. true/false тут не робят!

По умолчанию null – то есть и открытые и закрытые.

Теперь давайте разберемся, что такой открытый или закрытый сайт. Закрытый сайт это когда выполняется хотя бы одно из следующих условий:

• Галочка «Открыто» не отмечена
• Заархивирован
• Спам
• Удалён
• Для взрослых

Во всех остальных случаях сайт считается открытым.

archived

(целое число) Это уже более частные случаи, 1 – возвращает заархивированные сайты, 0 – не заархивированные. По умолчанию null – то есть и те и другие.

mature

(целое число) 1 – сайты, отмеченные как «Для взрослых», 0 – не отмеченные. По умолчанию null – то есть и те и другие.

spam

(целое число) 1 – сайты, отмеченные как спам, 0 – не отмеченные. По умолчанию null – то есть и те и другие.

deleted

(целое число) 1 – деактивированные сайты, 0 – не деактивированные. По умолчанию null – то есть и те и другие.

lang_id

(целое число) Можно ограничить получаемые результаты запроса значением колонки lang_id в таблице wp_blogs. Обратите внимание, что оно не является фактическим языком сайта. И я так понимаю, пока что даже не используется в ядре WordPress. Параметр добавлен в WordPress версии 4.8.

lang__in

(массив) Укажите значения колонки lang_id, которыми вы хотите ограничить результаты запроса. С версии 4.8.

lang__not_in

(массив) Укажите значения колонки lang_id, которые вы хотите исключить из результатов запроса. С версии 4.8.

search

(строка) Укажите часть домена или пути, по которым нужно искать сайты

search_columns

(массив) Массив, содержащий одно или оба следующих значений: domain, path – то, по чему производить поиск в параметре search.

$args = array(
	'search' => 'misha.blog',
	'search_columns' => array( 'domain' )
);
$sites = get_sites( $args );

meta_query

С тех пор, как в версии WordPress 5.1 появилась поддержка мета данных для сайтов сети мультисайт, мы можем запускать и meta_query в качестве параметра функции get_sites() 🚀

Про WP_Meta_Query у меня есть отдельный подробный урок, конечно там для постов в контексте WP_Query, но работает оно точно так же!

Миша

Впервые познакомился с WordPress в 2009 году. Организатор и спикер на конференциях WordCamp. Преподаватель в школе Нетология.

Пишите, если нужна помощь с сайтом или разработка с нуля.