3.5.Getting orders (Function)
Querying for WPPizza Orders (WPPizza v3.5+ only)
wppizza_get_orders($args)
if you want to develop you own script/plugin etc based on any wppizza orders, please refer to the documentation below
Note: Result sets will always be sorted by order date in descending order
@ since 3.5
@ param array
@ return array
Note: compared to the now removed get_orders_completed() all dimensions of the returned array are arrays themselves now. no more mix ‘n’ match between arrays and objects
Overview – more examples can be found at the end of this page
The following values will be used when not setting ANY arguments (which is essentially the default before any dropdown options might be selected in WPPizza -> Order History)
$args = array( 'query' => array( 'wp_user_id' => false , 'email' => false , 'order_id' => false , 'hash' => false , 'payment_status' => array('COMPLETED', 'UNCONFIRMED', 'REFUNDED', 'REJECTED') , 'order_status' => false , 'custom_status' => false , 'blogs' => {default depends on options set and if it's a multisite setup. see notes below}, 'summary' => false , ), 'pagination' => array( 'paged' => 0 , 'limit' => {default depends on options set. see notes below}, ), 'format' => true , ) //run query, and get results $orders = wppizza_get_orders($args); //this would be the same as simply using $orders = wppizza_get_orders();
Available Arguments
$args[‘query’]
query the wppizza orders table according set parameters
-
wp_user_id
- @param
int
- default
false
- get orders for a specific registered user id or 0 for guest/unregistered users
- @param
-
email
- @param
str|array
- default
false
- get orders that were made using (a) specific email address(es)
- if querying for one email address only, you can use a simple string value, if more than one use an array of emails
- Note: email addresses used when ordering may not neccessarily equal to the email address of a registered user, even if a user was logged in
- If you have set a WPPIZZA_ENCRYPTION_KEY and copied the email addresses hashed (see WPPizza->Settings->Privacy : Help screen) you should query for wppizza_maybe_encrypt_decrypt(’[email protected]’, true, false, true)
- @param
-
order_id
- @param
int
- default
false
- get an order by it’s specific id in the database
- Note: in a multisite setup this might return more than one order (see “blogs” below). If querying a single blog only the “pagination” parameter can and will be ignored (as it will only ever return one order)
- @param
-
hash
- @param
str
- default
false
- get an order by the generated hash associated with each order
- Note: in a multisite setup this might return more than one order (see “blogs” below). If querying a single blog only the “pagination” parameter can and will be ignored (as it will only ever return one order)
- @param
-
payment_status
- @param
str|array
- default
array('COD', 'COMPLETED', 'UNCONFIRMED', 'REFUNDED', 'REJECTED')
- get orders that have a specific payment status
- permitted values (case insensitive):
'COD', 'COMPLETED', 'UNCONFIRMED', 'CAPTURED', 'REFUNDED', 'REJECTED', 'INPROGRESS', 'INITIALIZED', 'AUTHORIZED', 'CANCELLED', 'PAYMENT_PENDING', 'FAILED'
- if querying for one status only, you can use a simple string value, if more than one use an array of payment statuses
- Note: ‘COD’ was only in use in VERY old wppizza installations instead of ‘COMPLETED’ and can be ignored in most cases
- Unless you are building your own gateway or similar, you typically only have to concern yourself with ‘COMPLETED’, ‘REFUNDED’, ‘REJECTED’, ‘CANCELLED’, ‘FAILED’
- @param
-
order_status
- @param
mixed (false|str|array)
- default
false
- get orders that have a specific order status
- permitted values (case insensitive) :
'NEW','ACKNOWLEDGED','ON_HOLD','PROCESSED','DELIVERED','REJECTED','REFUNDED','OTHER','CUSTOM_1','CUSTOM_2','CUSTOM_3','CUSTOM_4'
- if querying for one status only, you can use a simple string value, if more than one use an array of order statuses
- omit | false to ignore
- Note: ‘NEW’ is the default for all orders. Whether or not any of the others might have been set depends on “WPPizza->Localization->Admin Order History – Order Statuses”. If in doubt, omit this query value / argument
- @param
-
custom_status
- @param
mixed (false|str|array)
- default
not set
- get orders that have a specific custom status as set in “WPPizza->Localization->Admin Order History – Custom Statuses”
- permitted values : as per your custom statuses set set, false to ignore, [not-set] (including brackets) to get unset. CaseSenSiTive
- if querying for one status only, you can use a simple string value, if more than one use an array of custom statuses
- omit | false to ignore
- @param
-
order_date_before
- @param
timestamp (integer)
- default
not set
- get orders before a certain date / time
- permitted values : timestamp (integer)
- date/time queried follows WP timezone set when the order was made (i.e not UTC – unless this is the same as you WP timezone settings of course)
- omit | false to ignore
- @param
-
order_date_after
- @param
timestamp (integer)
- default
none
- get orders after a certain date / time
- permitted values : timestamp (integer)
- date/time queried follows WP timezone set when the order was made (i.e not UTC – unless this is the same as you WP timezone settings of course)
- omit | false to ignore
- @param
-
blogs – (multisite / network setup only, will otherwise be ignored)
- @param
mixed (bool|array)
- default
bool (see notes below)
- get orders from current , all or selected blogs
- permitted values : false to query current blog only, true to query all blogs, array of integers to query one or more specific blogs
- defaults if omitted:
– returns false (i.e current blog only) if NOT queried on main/parent site or – if on parent site – “WPPizza->Settings->Multisite :Orders/Customers (Admin) – all subsites” is not enabled
– returns true (i.e all blogs) only if on parent site AND “WPPizza->Settings->Multisite :Orders/Customers (Admin) – all subsites” IS enabled - Note: In a single site setup, this parameter will be ignored
- @param
-
summary
- @param
bool
- default
false
- only get a summary for the query such as total number of orders , (sum of) total value of orders. No order data will be returned. Ignores any “pagination” and “format” parameters.
- @param
$args[‘meta’] (since v3.8)
query an order for a specific meta key/value
see bottom of this page how to add meta values to an order
-
query
- @param
array of column/value arrays
- default
void
- restrict order results to orders that have a certain meta_key and/or meta_value set
- @param
$args[‘pagination’]
limit results set of the query – ignored if ‘summary’ => true or only querying for a specific ‘order_id’ or ‘hash’ for a single blog only (as it will only ever return one result at most)
-
paged
- @param
int
- default
0
- get results from paged offset onwards
- @param
-
limit
- @param
int
- default
[int]
– as per option set in “WPPizza->Settings->Order History : Max Results” - limit results to value set
- Note: if not set / false / not numeric, pagination will be ignored completely
- @param
$args[‘format ‘]
format the output for each order defaults to true. Set to false for unformatted order results – ignored if $args[‘query’][‘summary’] is set
-
blog_options
- @param
bool
- default
false
- add wppizza options set for each order
- Note: only useful in a multisite setup and when querying different blogs as they may have different wppizza option settings (such as localization variables for example)
- @param
-
class_idents
- @param
bool
- default
false
- add class idents to each formatted order values, in case you want to output the results somewhere and wish to add consistent class names etc
- @param
Examples
Get completed orders for a user with user id 23 (use 0 to query orders from guest/non-registered customers) from the current blog only, limited to first 5 results with output being formatted
Query:
$args = array( 'query'=>array( 'wp_user_id' => 23 ,//user id 'payment_status' => 'COMPLETED',//completed only 'blogs' => false ,//current blog only ), //order values returned for the first 5 orders found (always by descending date) 'pagination' =>array( 'paged' => 0 , 'limit' => 5 , ), //formatting omitted, defaults to true ); $orders = wppizza_get_orders($args);
Results [Array]:
[total_number_of_orders] => 194 // [int] total number of orders found without pagination limit [total_value_of_orders] => 14265.59 //[float] total value of orders found without pagination limit [gateways_idents] => Array // [array] of all gateways used in results set ( [COD] => COD ) [number_orders_on_page] => 5 //[int] total number of orders within pagination limit [value_orders_on_page] => 269.17 //[float] total value of orders within pagination limits /* array of order values for each order returned withing pagination limits the key for each order is always made up of [blog_id]_[order_id] but you can also get the blog id in [site][blog_id][value] and the order id in [ordervars][order_id][value] */ [orders] => Array ( [1_623] => Array ( [site] => Array ( /*.... site data for this order ....*/ ) [ordervars] => Array ( /*.... general ordervars data for this order....*/ ) [customer] => Array ( /*.... customer data for this order....*/ ) [order] => Array ( /*.... cart items ....*/ ) [summary] => Array ( /*.... summary of order ()....*/ ) ) [1_622] => Array ( /* second order results set */ ) /* more order results */ )
Get completed or confirmed orders with an order status of ‘NEW’ and ‘meta_key’ equals ‘mymetakey’ and ‘meta_value’ equals ‘mymetavalue’. ()
Query:
$args = array( 'query'=>array( 'payment_status' => array('CONFIRMED', 'COMPLETED'),//completed only 'order_status' => 'NEW',//get orders with status NEW only ), 'meta'=>array( 'query' => array( //if you do not want to restrict by meta_key, omit array( 'column' => 'meta_key', 'value' => 'mymetakey', ), //if you do not want to restrict by meta_value, omit array( 'column' => 'meta_value', 'value' => 'mymetavalue', ), ), ), ); $orders = wppizza_get_orders($args);
Results set returned will be as above, restricted to all orders that match the meta query as well
Get completed orders of all users (including non-registered/guests) from all blogs, limited to first x results as set in “WPPizza->Settings->Order History : Max Results” with output being formatted and added class idents
Query:
global $wppizza_options; $args = array( 'query'=>array( 'payment_status' => 'COMPLETED', 'blogs' => true,//will be ignored if not in a multisite setup or simply omit entirely ), 'pagination' =>array( 'paged' => 0 , 'limit' => $wppizza_options['settings']['admin_order_history_max_results'] , ), 'format' => array( 'class_idents' => true, ), ); $orders = wppizza_get_orders($args);
Results [Array]:
/* as above example, but with class-indent added to each order parameter you could use in any outputs for consistent class names (perhaps adding a distinct prefix to each class name as well) so the order date would now return somthing like this */ [orders] => Array ( [1_623] => Array ( ............ [ordervars] => Array ( [order_date] => Array ( [label] => Order Date : [value] => 2018-05-15 00:48:08 [value_formatted] => May 15, 2018 12:48 am [class_ident] => order-date //this parameter is now added to each one ) ............ ) ............ ) [1_623] => Array ( /* second order */ ) ///etc )
Simply check if there are any new orders, without returning each orders values
Query:
$args = array( 'query'=>array( 'payment_status' => 'COMPLETED',//get completed orders only 'order_status' => 'NEW',//get orders with status NEW only 'summary' => true,// only return count/totals ), ); $orders = wppizza_get_orders($args);
Results [Array]:
[total_number_of_orders] => 194 // [int] total number of orders found without pagination limit [total_value_of_orders] => 14265.59 //[float] total value of orders found without pagination limit /* no other parameters will get returned */
Pagination
If you are outputting the order results somehow/somewhere you could use the below helper to add pagination
@ param [int] : should be the total number of orders returned by order query before limit @ param [int] : should equal the limit set in the orders query pagination['limit'] parameter @ param [int] (default:false if omitted) : if set to an integer (2 for example) will display a max of 2 pagination links either side of current page, and use '...' where appropriate. false to show all links @ param bool (default:true if omitted) : true to display some pagination info underneath button , false to omit @ param false|int (default:false if omitted): links to current page. set a distinct post id to link to the page with this id (might be required for ajax requests) @ return str $pagination = wppizza_orders_pagination($total_no_of_orders, $limit, $ellipsis, $pagination_info, $post_id); print $pagination;
Adding/Altering Meta Data – since WPPizza 3.8+
Adding Meta Data to an Order
/* adding 'mymetakey' with a value of 'mymetavalue' to an order, *when an order gets submitted* if mymetavalue is not a string/integer it will be serialized */ add_action('wppizza_add_order_meta', 'myprefix_add_order_meta', 10, 2) /*------------------------------------------------------------------------------ # $param order id # $param order values # $returns int (meta_id added) ------------------------------------------------------------------------------*/ function myprefix_add_order_meta($order_id, $order){ $meta_id = wppizza_do_order_meta($order_id, 'mymetakey', 'mymetavalue'); return $meta_id; }
/* adding 'mymetakey' with a value of 'mymetavalue' to an order, *even BEFORE an order gets submitted - i.e as soon as the user arrives on your orderpage * if mymetavalue is not a string/integer it will be serialized Note: if you also use 'wppizza_add_order_meta' with the same metakey, 'wppizza_add_order_meta' will overwrite the value captured with 'wppizza_add_order_meta_init' (as it happens after) */ add_action('wppizza_add_order_meta_init', 'myprefix_add_order_meta_init', 10, 1) /*------------------------------------------------------------------------------ # $param order id # $returns int (meta_id added) ------------------------------------------------------------------------------*/ function myprefix_add_order_meta_init($order_id){ $meta_id = wppizza_do_order_meta($order_id, 'mymetakey', 'mymetavalue'); return $meta_id; }
Updating Meta Data for an Order
/* updating metavalues for a specific meta_key relating to a specific order if it the meta_key for this order does not exist yet, it will be added, else the value will be updated if $meta_value is not a string/integer it will be serialized */ /*------------------------------------------------------------------------------ # $param int - order id we are updating # $param str - meta key we are updating # $param mixed - value to update/insert # $returns int (meta_id added/updated) ------------------------------------------------------------------------------*/ $order_id = 123; $meta_key = 'mymetakey'; $meta_value = array( 'key1'=> 'a', 'key2'=> 'b'} /* or $meta_value = 'new value'; if you want */ $meta_id = wppizza_do_order_meta($order_id, $meta_key, $meta_value);
Deleting a specific metakey of Order
/*------------------------------------------------------------------------------ # $param int - order id # $param str - meta key we are deleting of this order # $returns bool ------------------------------------------------------------------------------*/ $order_id = 123; $meta_key = 'mymetakey'; $meta_id = wppizza_delete_order_meta($order_id, $meta_key');
Get metavalue of an Order for a specific metakey
/*------------------------------------------------------------------------------ # $param int - order id # $param str - meta key we are querying # $param bool - return value only # $returns mixed ------------------------------------------------------------------------------*/ $order_id = 123; $meta_name = 'mymetakey'; $meta_value_only = true; $res = wppizza_get_order_meta($order_id, $meta_name, $meta_value_only );
Deleting Orders – since WPPizza 3.10+
Deleting an order and its associated meta data by id/blogid
/*------------------------------------------------------------------------------ # $param int - order id # $param int - blog id (only relevant in mutisite setups). set blog id to distinctly target order of a specific blog, or false/omit for current blog # return void ------------------------------------------------------------------------------*/ /* multisite setups: */ $order_id = 123; $blog_id = 1; wppizza_delete_order($order_id, $blog_id); /* single site setup, simply do: */ $order_id = 123; wppizza_delete_order($order_id);
This is it for the time being, but if you have a particular query you need like help with and you cannot figure out , let me know and I’ll see what I can do
documentor id 5