WP_INSERT_CATEGORY() │ WP 2.0.0

Функция WP_INSERT_CATEGORY() позволяет добавить новую категорию в базу данных WordPress или обновить уже существующую категорию, если указать её ID.

Для добавления категории можно воспользоваться более простой функцией wp_create_category(). Для этого нужно всего лишь передать название категории и ID родительской категории.

Если у вас возникает ошибка Fatal error: Call to undefined function wp_insert_category(), вам нужно подключить файл /wp-admin/includes/taxonomy.php:

require_once ABSPATH . '/wp-admin/includes/taxonomy.php';

Использование функции

wp_insert_category( $catarr, $wp_error );

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

• $catarr (array) (обязательный) - параметры новой категории. Допустимые параметры:

$cat_defaults = [
  'cat_ID' => 0,                // ID категории для обновления. 0 - добавить новую категорию.
  'cat_name' => '',             // название категории. Обязательно.
  'category_description' => '', // описание категории
  'category_nicename' => '',    // "чистое" название категории (slug)
  'category_parent' => 0,       // ID родительской категории
  'taxonomy' => 'category'      // таксономия. Измените, чтобы добавить элемент другой таксономии.
                                // Например, для меток используйте 'post_tag'
];

Рекомендуется указывать только необходимые параметры.

• $wp_error (bool) - если true, функция вернет объект WP_Error при неудаче. По умолчанию: false.

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

• Возвращает ID новой или обновленной категории в случае успеха или 0 или WP_Error в случае ошибки (в зависимости от параметра $wp_error).

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

Пример 1: Добавление новой категории

Чтобы добавить новую категорию на сайт, используйте следующий код:

$cat_data = [
    'cat_name' => 'новая категория',
    'category_description' => 'Описание новой категории',
    'category_nicename' => 'novaia-kategoriia'
];

// добавление категории
$cat_id = wp_insert_category( $cat_data );

if( $cat_id ) {
    echo 'Категория добавлена';
} else {
    echo 'Не удалось добавить категорию';
}

Пример 2: Обновление существующей категории

Чтобы обновить существующую категорию с ID = 7, измените её название:

$updated = wp_insert_category( [
    'cat_ID' => 7,
    'cat_name' => 'Новое имя'
] );

if( $updated ) {
    echo "Категория с ID $updated была обновлена";
}

Пример 3: Добавление пользовательского элемента таксономии

Эта функция также позволяет добавлять элементы пользовательских таксономий, а не только категории. Например, чтобы добавить метку:

$tag_id = wp_insert_category( [
    'cat_name' => 'метка',
    'taxonomy' => 'post_tag'
] );

Изменения

• Команда была введена в версии 2.0.0.
• В версии 2.5.0 был добавлен параметр $wp_error.
• В версии 3.0.0 был добавлен аргумент taxonomy.

Исходный код функции

function wp_insert_category( $catarr, $wp_error = false ) {
    $cat_defaults = array(
        'cat_ID'               => 0,
        'taxonomy'             => 'category',
        'cat_name'             => '',
        'category_description' => '',
        'category_nicename'    => '',
        'category_parent'      => '',
    );
    $catarr = wp_parse_args( $catarr, $cat_defaults );

    if ( '' === trim( $catarr['cat_name'] ) ) {
        if ( ! $wp_error ) {
            return 0;
        } else {
            return new WP_Error( 'cat_name', __( 'Вы не ввели имя категории.' ) );
        }
    }

    $catarr['cat_ID'] = (int) $catarr['cat_ID'];

    // Обновляем или создаем?
    $update = ! empty( $catarr['cat_ID'] );

    $name        = $catarr['cat_name'];
    $description = $catarr['category_description'];
    $slug        = $catarr['category_nicename'];
    $parent      = (int) $catarr['category_parent'];

    if ( $parent < 0 ) {
        $parent = 0;
    }

    if ( empty( $parent )
        || ! term_exists( $parent, $catarr['taxonomy'] )
        || ( $catarr['cat_ID'] && term_is_ancestor_of( $catarr['cat_ID'], $parent, $catarr['taxonomy'] ) ) ) {
        $parent = 0;
    }

    $args = compact( 'name', 'slug', 'parent', 'description' );

    if ( $update ) {
        $catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args );
    } else {
        $catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args );
    }

    if ( is_wp_error( $catarr['cat_ID'] ) ) {
        if ( $wp_error ) {
            return $catarr['cat_ID'];
        } else {
            return 0;
        }
    }
    return $catarr['cat_ID']['term_id'];
}

Теперь вы знаете, как использовать функцию wp_insert_category() для добавления и обновления категорий в WordPress!