WC_Order

includes / abstracts / abstract-wc-order.php / Кодекс WordPress

Итак, WC_Order – это объект заказа в WooCommerce. На этой странице вы найдёте описание его методов и примеры использования.

Также очень хороший пример вы можете найти в уроке, где мы создавали заказ через код.

Документация не всегда позволяет последовательно разобраться в теме, поэтому не могу не порекомендовать вам свой видеокурс по созданию темы для WooCommerce.

Методы

В целом все методы, которые есть, можно разделить на три больших категории:

Получение информации о заказе, например $order->get_id().
Аля «условные теги», возвращающие true или false, и предназначенные для использования в условиях, например if( $order->is_paid() ).
Методы, изменяющие объект заказа, например $order->set_billing_country(), тут важный момент в том, что эти методы, хоть и изменяют объект заказа для последующего использования в запросе, но в базу данных изменений они не сохраняют, поэтому после всех изменений этими методами (не всеми, но большинством), мы должны сохранить изменения в базу данных методом $order->save(). Не беспокойтесь, вас ждут примеры ниже.

Важный момент, для получения информации о заказе мы используем методы, а не свойства. То есть $order->get_id() – хорошо, $order->id – не хорошо.

Основное

get_id(): Возвращает ID заказа.
get_order_key(): Возвращает ключ заказа (используется например при отображении страницы «Заказ принят»).
get_order_number(): Возвращает номер заказа, который по умолчанию совпадает с его ID.
get_data(): Возвращает ассоциативный массив со всеми данными заказа, например вы сами можете посмотреть, что в массиве:

$order = wc_get_order( 100 );
print_r( $order->get_data() );

get_currency(): Возвращает код валюты заказа, например RUB.
get_customer_note(): Возвращает примечание к заказу, оставленное клиентом при его оформлении.
get_customer_order_notes(): Возвращает массив из объектов заметок к заказу. Это кстати WP_Comment.
get_date_created(): Возвращает дату создания заказа, в виде объекта WC_DateTime.
get_date_completed(): Возвращает дату, когда заказ был выполнен, в виде объекта WC_DateTime.
get_date_modified(): Возвращает дату последнего изменения заказа.
get_date_paid(): Возвращает дату оплаты заказа, например:

$order = wc_get_order( 100 );
$date = $order->get_date_paid(); // объект WC_DateTime
echo $date->date( 'd.m.Y' ); // 17.09.2021

get_status(): Возвращает текущий статус заказа без внутреннего префикса wc-.

Например стандартные статусы: pending, processing, on-hold, completed, cancelled, refunded, failed. Также это могут быть кастомные статусы.
has_status( $status ): Проверяет, есть ли у заказа заданный статус сейчас, true/false.
is_paid(): Оплачен ли заказ true/false.
needs_payment(): Проверяем, нуждается ли заказ в оплате, true/false. Метод в основном ориентируется на стоимость заказа (должна быть больше 0) и на то, какой статус у заказа. Но может быть изменён фильтром woocommerce_order_needs_payment.

add_order_note( $note, $is_customer_note, $added_by_user ): Добавляет заметку к заказу. В первом параметре – текст заметки. Второй параметр true/false – является ли это заметка для клиента. Третий параметр true/false – добавлена ли заметка пользователем.

$order = wc_get_order( 100);
$order->add_order_note( 'Привет', true, true );

Заметки заказа WooCommerce add_order_note()

Все методы ниже, которые начинаются со слова set_..., должны отдельно сохранять изменения в базу данных методом save().

set_currency( $currency ): Изменяет валюту заказа, например RUB.
set_customer_note( $note ): Изменяем примечание к заказу.
set_date_created( $date ): Изменяет дату создания заказа, значение можно передать либо в UNIX-формате, либо ISO 8601.
set_date_completed( $date ): Изменяет дату, когда заказ был выполнен, значение можно передать либо в UNIX-формате, либо ISO 8601.
set_date_modified( $date ): Изменяет дату последнего изменения заказа, значение можно передать либо в UNIX-формате, либо ISO 8601.
set_date_paid( $date ): Изменяет дату оплаты заказа, значение можно передать либо в UNIX-формате, либо ISO 8601.

// изменяем дату оплаты на "вчера в это же время"
$order = wc_get_order( 100 );
$order->set_date_paid( time() - DAY_IN_SECONDS ); // текущее время минус 86400
$order->save();

Про константу DAY_IN_SECONDS и про другие константы времени можете почитать здесь.

delete( $force_delete ): Помещает заказ в корзину. При указании параметра метода в значение true полностью удаляет заказ минуя корзину. Не нуждается в сохранении методом save().
set_status( $status ): Устанавливает статус заказа.
update_status( $status ): Устанавливает и сохраняет статус заказа. Пример использования.

Позиции заказа

Итак, позиции заказа – это все товары, которые были добавлены в заказ, доставка и возможно какие-то дополнительные сборы.

Подробный урок по позициям заказов здесь.

get_item( $item_id ): Позволяет получить объект WC_Order_Item определённой позиции заказа по её ID.
get_item_count( $item_type ): Получает количество позиций заказа. В необязательный параметр метода можно передать тип позиции line_item, fee, shipping, coupon, которые нужно посчитать.
get_item_count_refunded( $item_type ): Подсчитывает только те позиции заказа, деньги за которые были возвращены. Также можно отфильтровать по типу при помощи необязательного параметра.
get_items( $types ): Возвращает массив объектов всех позиций заказа. По умолчанию возвращает только товары, но можно передать определённые типы в переменную (в виде строки или массива).
get_fees(): Возвращает массив всех сборов в заказе в виде объектов WC_Order_item_Fee.

add_product( $product, $qty ): Добавляет товар к заказу. В качестве параметров указываются объект товара WC_Product и его количество соответственно.

// добавляем товар с ID=25 к заказу с ID=100 в количестве 5 штук
$order = wc_get_order( 100 );
$order->add_product( wc_get_product( 25 ), 5 );
 
// пересчитываем и сохраняем заказ кстати
$order->calculate_totals();

get_downloadable_items(): Возвращает массив массивов с информацией о всех файлах из всех загружаемых товаров заказа.
has_downloadable_item(): Есть ли среди позиций заказа скачиваемые товары true/false.
has_free_item(): Есть ли среди позиций заказа бесплатные товары true/false.

add_shipping( $rate ): Добавляем доставку к заказу
add_item( $item ): Добавляет позицию в заказ. В качестве параметра передаём объект WC_Order_Item.
add_fee( $fee ): Добавляет сбор к заказу. В качестве параметра метода указываем объект WC_Order_Item_Fee
remove_item( $item_id ): Удаляет позицию заказа по её ID.
remove_order_items( $item_type ): Удаляет все позиции заказа. В необязательный параметр метода можно передать определённый тип позиции line_item, fee, shipping, coupon, которые нужно удалить.

Купоны

get_coupon_codes(): Возвращает массив кодов купонов, применённых к заказу.
get_coupons(): Возвращает массив объектов купонов WC_Order_Item_Coupon, применённых к заказу.
apply_coupon( $coupon ): Добавляем купон к заказу. Сохраняет и пересчитывает заказ. Возвращает true, если купон удалось добавить, WP_Error – если нет.
recalculate_coupons(): Заново применяет все купоны заказа и пересчитывает скидку. Например этот метод был нужен при использовании устаревшего метода add_coupon():

// до версии WooCommerce 3.0
$order->add_coupon( 'blackfriday' );
$order->recalculate_coupons();
 
// сегодня
$order->apply_coupon( 'blackfriday' );

remove_coupon( $code ): Удаляет купон и пересчитывает заказ.

Клиент (покупатель)

get_customer_id(), get_user_id(): Возвращает ID пользователя, совершившего заказ.
get_user(): Возвращает объект пользователя, совершившего заказ, или же false, если заказ был совершён без регистрации.
get_customer_ip_address(): Возвращает IP-адрес пользователя, совершившего заказ.
get_customer_user_agent(): Возвращает инфу о браузере пользователя, совершившего заказ.

set_customer_id(): Устанавливает ID пользователя для заказа.
set_customer_ip_address(): Устанавливает IP-адрес пользователя, совершившего заказ.

// меняем IP клиента, если он соответствует определённому IP
if( $ip_to_replace = $order->get_customer_ip_address() ) {
	$order->set_customer_ip_address( $new_ip );
	$order->save();
}

set_customer_user_agent(): Устаналивает инфу о браузере пользователя.

Адреса

get_address( $address ): Возвращает адрес в виде ассоциативного массива. В качестве параметра можно передать значения billing или shipping, в зависимости от того, хотите вы получить платёжный адрес или адрес доставки.

$order = wc_get_order( 100);
 
print_r( $order->get_address() );
/*
Array
(
    [first_name] => Миша
    [last_name] => Рудрастых
    [company] => Студия Миши Рудрастых
    [address_1] => Большой пр. ПС
    [address_2] => 100
    [city] => Санкт-Петербург
    [state] => Санкт-Петербург
    [postcode] => 191033
    [country] => RU
    [email] => no-reply@misha.agency
    [phone] => 123-123-123
)
*/

Каждый из вышеперечисленных параметров вы можем получить отдельными методами:

get_billing_first_name(): Имя (платёжный адрес)
get_shipping_first_name(): Имя (адрес доставки)
get_billing_last_name(): Фамилия (платёжный адрес)
get_shipping_last_name(): Фамилия (адрес доставки)
get_billing_company(): Компания (платёжный адрес)
get_shipping_company(): Компания (адрес доставки)
get_billing_country(): Код страны, полный список (платёжный адрес)
get_shipping_country(): Код страны (адрес доставки)
get_billing_state(): Регион (платёжный адрес)
get_shipping_state(): Регион (адрес доставки)
get_billing_city(): Город (платёжный адрес)
get_shipping_city(): Город (адрес доставки)
get_billing_address_1(): Адрес, строка 1 (платёжный)
get_shipping_address_1(): Адрес, строка 1 (адрес доставки)
get_billing_address_2(): Адрес, строка 2 (платёжный)
get_shipping_address_2(): Адрес, строка 2 (адрес доставки)
get_billing_postcode(): Почтовый индекс (платёжный адрес)
get_shipping_postcode(): Почтовый индекс (адрес доставки)
get_billing_email(): Email
get_billing_phone(): Телефон (платёжный адрес)
get_shipping_phone(): Телефон (адрес доставки)
get_formatted_billing_address(): Возвращает отформатированный платёжный адрес, в виде HTML.
get_formatted_billing_full_name(): Возвращает полное имя клиента из платёжного адреса.
get_formatted_shipping_address(): Возвращает отформатированный адрес доставки, в виде HTML.
get_formatted_shipping_full_name(): Возвращает полное имя клиента из адреса доставки.
has_billing_address(): Возвращает true, если указан платёжный адрес, false – если нет.
has_shipping_address(): Возвращает true, если указан адрес доставки, false – если нет.

set_address( $address, $type ): Позволяет изменить платёжный адрес или адрес доставки. В качестве параметра можно передать значения billing или shipping, в зависимости от того, какой из них нужно изменить. Значение адреса передаётся в виде ассоциативного массива, например:

$order = wc_get_order( 100 );
 
$order->set_address(
	array(
		'first_name' => 'Миша',
		'last_name' => 'Рудрастых',
		'company' => 'Студия Миши Рудрастых',
		'address_1' => 'Большой пр. ПС',
		'address_2' => '100',
		'city' => 'Санкт-Петербург',
		'state' => 'Санкт-Петербург',
		'postcode' => '191033',
		'country' => 'RU',
		'email' => 'no-reply@misha.agency', // это только для платёжного адреса
		'phone' => '123-123-123',
	),
	'shipping'
);

set_billing_first_name(): Имя (платёжный адрес)
set_shipping_first_name(): Имя (адрес доставки)
set_billing_last_name(): Фамилия (платёжный адрес)
set_shipping_last_name(): Фамилия (адрес доставки)
set_billing_company(): Компания (платёжный адрес)
set_shipping_company(): Компания (адрес доставки)
set_billing_country(): Код страны, полный список (платёжный адрес)
set_shipping_country(): Код страны (адрес доставки)
set_billing_state(): Регион (платёжный адрес)
set_shipping_state(): Регион (адрес доставки)
set_billing_city(): Город (платёжный адрес)
set_shipping_city(): Город (адрес доставки)
set_billing_address_1(): Адрес, строка 1 (платёжный)
set_shipping_address_1(): Адрес, строка 1 (адрес доставки)
set_billing_address_2(): Адрес, строка 2 (платёжный)
set_shipping_address_2(): Адрес, строка 2 (адрес доставки)
set_billing_postcode(): Почтовый индекс (платёжный адрес)
set_shipping_postcode(): Почтовый индекс (адрес доставки)
set_billing_email(): Email
set_billing_phone(): Телефон (платёжный адрес)
set_shipping_phone(): Телефон (адрес доставки)

Доставка

get_shipping_method(): Возвращает название метода доставки
get_shipping_to_display(): Название способа доставки вместе с ценой в виде HTML.
get_shipping_methods(): Возвращает массив объектов доставки WC_Order_Item_Shipping для заказа
has_shipping_method( $shipping_method ): Используется ли определённый способ доставки? true/false

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

if( $order->has_shipping_method( 'flat_rate' ) ) {
	echo 'Используется метод доставки Единая ставка.';
}

Платежи

get_payment_method(): Возвращает ярлык используемого в заказе метода оплаты.
get_payment_method_title(): Возвращает название метода оплаты.
get_payment_tokens(): Возвращает массив платёжных токенов.
get_refunds(): Возвращает массив объектов возврата средств, WC_Order_Refund.
get_transaction_id(): Возвращает ID транзакции
add_payment_token( $token ): Добавляет платёжный токен к заказу. В качестве параметра передаём объект WC_Payment_Token, возвращает ID токена в случае успеха, false – в случае, если добавить не получилось.
payment_complete(): Метод, вызываемый после успешной оплаты заказа? Кем, чем вызываемый? Например при разработке платёжного шлюза мы используем его. Меняет статус заказа на «В обработке» или «Выполнен» (если содержит только виртуальные товары), также уменьшает количество товаров в запасе.

set_payment_method( $method ): Устанавливает метод оплаты, указываем ярлык желаемого метода..
set_payment_method_title( $title ): Устанавливает название метода оплаты.

Суммы заказа

get_line_subtotal( $item ): Возвращает сумму для определённой позиции заказа.
get_formatted_line_subtotal( $item ): Возвращает сумму для определённой позиции заказа. В виде HTML и со знаком валюты.
get_discount_total(): Возвращает общую скидку заказа.
get_discount_to_display(): Возвращает общую скидку заказа отформатированно в виде HTML и со знаком валюты.
get_subtotal(): Возвращает стоимость товаров в заказе.
get_subtotal_to_display(): Возвращает стоимость товаров в заказе отформатированно в виде HTML и со знаком валюты.
get_total(): Возвращает общую сумму заказа.
get_shipping_total(): Возвращает стоимость доставки заказа.
get_formatted_order_total(): Возвращает сумму заказа. В виде HTML и со знаком валюты.
set_shipping_total( $shipping_total ): Устанавливает стоимость доставки заказа.
calculate_shipping(): Пересчитывает сумму доставки у заказа и обновляет её.
calculate_totals(): Пересчитывает общую сумму заказа, обновляет и возвращает её.

Урлы

get_cancel_order_url( $redirect ): Возвращает URL, по которому покупатель может отменить свой неоплченный (pending) заказ. В качестве параметра можете передать URL для редиректа.
get_cancel_order_url_raw( $redirect ): В отличие от get_cancel_order_url() не добавляет параметр с одноразовым числом в URL.
get_checkout_order_received_url(): Возвращает URL страницы «Заказ принят».
get_checkout_payment_url( $on_checkout ): Возвращает ссылку (URL) на оплату заказа. Передайте true в метод, чтобы не давать возможность смены метода оплаты.
get_view_order_url(): Возвращает ссылку на просмотр заказа в личном кабинете.
get_edit_order_url(): Возвращает URL редактирования заказа в админке.

Метаданные заказа

get_meta( $key, $single ): Получает значение метаданных заказа. Метод очень похож на функцию get_post_meta() с тем лишь исключением, что ID заказа нам лишний раз уже указывать не нужно. Описание параметров можете почитать там же.
get_meta_data(): Получает массив всех метаданных заказа.
meta_exists( $key ): Проверяет, действительно ли существуют метаданные с указанным ключом.
add_meta_data( $key, $value, $unique ): Метод очень похож на функцию add_post_meta() с тем лишь исключением, что ID заказа нам лишний раз уже указывать не нужно. Описание параметров можете почитать там же.
delete_meta_data( $key ): Удаляет метаданные по значению их ключа.
delete_meta_data_by_mid( $mid ): Удаляем метаданные заказа по значению их ID.
update_meta_data( $key, $value, $meta_id ): Обновляет метаданные по значению ключа, либо добавляет, если их не существует.
save_meta_data(): Сохраняет изменённые метаданные в базе данных.

Кодекс WordPress: WooCommerce: get_woocommerce_currencies(), get_woocommerce_currency(), get_woocommerce_currency_symbol(), woocommerce_breadcrumb(), is_account_page(), is_add_payment_method_page(), is_cart(), is_checkout(), is_edit_account_page(), is_order_received_page(), is_product(), is_product_category(), is_product_tag(), is_product_taxonomy(), is_shop(), is_view_order_page(), is_wc_endpoint_url(), is_woocommerce(), wc_add_order_item(), wc_add_order_item_meta(), WC_Cart::add_to_cart(), WC_Cart::empty_cart(), wc_delete_order_item(), wc_delete_order_item_meta(), wc_get_cart_url(), wc_get_checkout_url(), wc_get_customer_total_spent(), wc_get_page_id(), wc_get_product_id_by_sku(), wc_get_product_ids_on_sale(), wc_get_product_terms(), WC_Order{}, wc_post_content_has_shortcode(), wc_price(), wc_print_notice(), WC_Product{}, wc_update_order_item(), wc_update_order_item_meta(), woocommerce_form_field(), woocommerce_wp_checkbox(), woocommerce_wp_radio(), woocommerce_wp_text_input(), woocommerce_wp_textarea_input()

Миша

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

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

Методы