diff --git a/docs/contributing/woocommerce-git-flow.md b/docs/contributing/woocommerce-git-flow.md index 4b5729e64db..7980474725e 100644 --- a/docs/contributing/woocommerce-git-flow.md +++ b/docs/contributing/woocommerce-git-flow.md @@ -27,12 +27,12 @@ Prefixes determine the type of branch, and include: When creating a **fix branch**, use the correct prefix and the issue number. Example: -``` text +```text fix/12345 ``` Alternatively you can summarise the change: -``` text +```text fix/shipping-tax-rate-saving ``` diff --git a/docs/payments/payment-gateway-api.md b/docs/payments/payment-gateway-api.md index 4da1a880d42..ca052c002a1 100644 --- a/docs/payments/payment-gateway-api.md +++ b/docs/payments/payment-gateway-api.md @@ -23,13 +23,13 @@ Form and iFrame based gateways post data offsite, meaning there are less securit Payment gateways should be created as additional plugins that hook into WooCommerce. Inside the plugin, you need to create a class after plugins are loaded. Example: -``` php +```php add_action( 'plugins_loaded', 'init_your_gateway_class' ); ``` It is also important that your gateway class extends the WooCommerce base gateway class, so you have access to important methods and the [settings API](https://woo.com/document/settings-api/ "https://woo.com/document/settings-api/"): -``` php +```php function init_your_gateway_class() { class WC_Gateway_Your_Gateway extends WC_Payment_Gateway {} } @@ -39,14 +39,14 @@ You can view the [WC_Payment_Gateway class in the API Docs](https://woocommerce. As well as defining your class, you need to also tell WooCommerce (WC) that it exists. Do this by filtering _woocommerce_payment_gateways_: -``` php +```php function add_your_gateway_class( $methods ) { $methods\[\] = 'WC_Gateway_Your_Gateway'; return $methods; } ``` -``` php +```php add_filter( 'woocommerce_payment_gateways', 'add_your_gateway_class' ); ``` @@ -66,7 +66,7 @@ Within your constructor, you should define the following variables: Your constructor should also define and load settings fields: -``` php +```php $this->init\_form\_fields(); $this->init_settings(); ``` @@ -75,13 +75,13 @@ We'll cover `init_form_fields()` later, but this basically defines your settings After `init_settings()` is called, you can get the settings and load them into variables, meaning: -``` php +```php $this->title = $this->get_option( 'title' ); ``` Finally, you need to add a save hook for your settings: -``` php +```php add_action( 'woocommerce_update_options_payment_gateways\_' . $this->id, array( $this, 'process_admin_options' ) ); ``` @@ -91,7 +91,7 @@ Use this method to set `$this->form_fields` - these are options you'll show in a A basic set of settings for your gateway would consist of _enabled_, _title_ and _description_: -``` php +```php $this->form_fields = array( 'enabled' => array( 'title' => \_\_( 'Enable/Disable', 'woocommerce' ), @@ -120,7 +120,7 @@ Now for the most important part of the gateway - handling payment and processing Here is an example of a process_payment function from the Cheque gateway: -``` php +```php function process_payment( $order_id ) { global $woocommerce; $order = new WC_Order( $order_id ); @@ -147,7 +147,7 @@ As you can see, its job is to: Cheque gives the order On-Hold status since the payment cannot be verified automatically. If, however, you are building a direct gateway, then you can complete the order here instead. Rather than using update_status when an order is paid, you should use payment_complete: -``` php +```php $order->payment_complete(); ``` @@ -155,7 +155,7 @@ This ensures stock reductions are made, and the status is changed to the correct If payment fails, you should throw an error and return null: -``` php +```php wc_add_notice( \_\_('Payment error:', 'woothemes') . $error_message, 'error' ); return; ``` @@ -168,14 +168,14 @@ Stock levels are updated via actions (`woocommerce_payment_complete` and in tran Updating the order status can be done using functions in the order class. You should only do this if the order status is not processing (in which case you should use payment_complete()). An example of updating to a custom status would be: -``` php +```php $order = new WC\_Order( $order\_id ); $order->update_status('on-hold', \_\_('Awaiting cheque payment', 'woothemes')); ``` The above example updates the status to On-Hold and adds a note informing the owner that it is awaiting a Cheque. You can add notes without updating the order status; this is used for adding a debug message: -``` php +```php $order->add_order_note( \_\_('IPN payment completed', 'woothemes') ); ``` @@ -189,7 +189,7 @@ $order->add_order_note( \_\_('IPN payment completed', 'woothemes') ); If you are creating an advanced, direct gateway (i.e., one that takes payment on the actual checkout page), there are additional steps involved. First, you need to set has_fields to true in the gateway constructor: -``` php +```php $this->has_fields = true; ``` @@ -203,19 +203,19 @@ Finally, you need to add payment code inside your `process_payment( $order_id )` If payment fails, you should output an error and return nothing: -``` php +```php wc_add_notice( \_\_('Payment error:', 'woothemes') . $error_message, 'error' ); return; ``` If payment is successful, you should set the order as paid and return the success array: -``` php +```php // Payment complete $order->payment_complete(); ``` -``` php +```php // Return thank you page redirect return array( 'result' => 'success', @@ -229,13 +229,13 @@ If you are building a gateway that makes a callback to your store to tell you ab The best way to add a callback and callback handler is to use WC-API hooks. An example would be as PayPal Standard does. It sets the callback/IPN URL as: -``` php +```php str_replace( 'https:', 'http:', add_query_arg( 'wc-api', 'WC_Gateway_Paypal', home_url( '/' ) ) ); ``` Then hooks in its handler to the hook: -``` php +```php add_action( 'woocommerce_api_wc_gateway_paypal', array( $this, 'check_ipn_response' ) ); ``` diff --git a/docs/payments/payment-gateway-plugin-base.md b/docs/payments/payment-gateway-plugin-base.md index 1c1b4836e4d..f8391e681d0 100644 --- a/docs/payments/payment-gateway-plugin-base.md +++ b/docs/payments/payment-gateway-plugin-base.md @@ -6,7 +6,7 @@ tags: code-snippet This code can be used as a base to create your own simple custom payment gateway for WooCommerce. If not used in a custom plugin, you need to add this code to your child theme's functions.php file or via a plugin that allows custom functions to be added, such as the [Code snippets](https://wordpress.org/plugins/code-snippets/) plugin. Please don't add custom code directly to your parent theme's functions.php file as this will be wiped entirely when you update the theme. -``` php +```php Gateway diff --git a/docs/payments/payment-token-api.md b/docs/payments/payment-token-api.md index a51d334566d..5e60114e6b6 100644 --- a/docs/payments/payment-token-api.md +++ b/docs/payments/payment-token-api.md @@ -30,7 +30,7 @@ We need to tell WooCommerce our gateway supports tokenization. Like other gatewa Here is the Simplify array: -``` php +```php $this->supports = array( 'subscriptions', 'products', @@ -54,14 +54,14 @@ Since Simplify uses credit cards, we will use the credit card class. We will use various `set_` methods to pass in information about our token. To start with we will pass the token string and the gateway ID so the token can be associated with Simplify. -``` php +```php $token->set_token( $token_string ); $token->set_gateway_id( $this->id ); // `$this->id` references the gateway ID set in `__construct` ``` At this point we can set any other necessary information we want to store with the token. Credit cards require a card type (visa, mastercard, etc), last four digits of the card number, an expiration month, and an expiration year. -``` php +```php $token->set_card_type( 'visa' ); $token->set_last4( '1234' ); $token->set_expiry_month( '12' ); @@ -102,14 +102,14 @@ You can check if an existing token should be used with a conditional like the fo You can then load a token from ta ID (more on the WC_Payment_Tokens class later in this doc): -``` php +```php $token_id = wc_clean( $_POST['wc-simplify_commerce-payment-token'] ); $token = WC_Payment_Tokens::get( $token_id ); ``` This does **not** check if the loaded token belongs to the current user. You can do that with a simple check: -``` php +```php // Token user ID does not match the current user... bail out of payment processing. if ( $token->get_user_id() !== get_current_user_id() ) { // Optionally display a notice with `wc_add_notice` @@ -130,7 +130,7 @@ Start by extending WC_Payment_Token and providing a name for the new type. We'll A barebones token file should look like this: -``` php +```php class WC_Payment_Token_eCheck extends WC_Payment_Token { /** @protected string Token Type String */ @@ -149,7 +149,7 @@ Validate should return `true` if everything looks OK, and false if something doe Always make sure to call `WC_Payment_Token`'s validate method before adding in your own logic. -``` php +```php public function validate() { if ( false === parent::validate() ) { return false; @@ -158,7 +158,7 @@ public function validate() { Now we can add some logic in for the "last 4" digits. -``` php +```php if ( ! $this->get_last4() ) { return false; } @@ -166,7 +166,7 @@ if ( ! $this->get_last4() ) { Finally, return true if we make it to the end of the `validate()` method. -``` php +```php return true; } ``` @@ -177,7 +177,7 @@ You can now add your own methods for each piece of data you would like to expose Provide a `get_` and `set_` method for each piece of data you want to capture. For eChecks, this is "last4" for the last 4 digits of a check. -``` php +```php public function get_last4() { return $this->get_meta( 'last4' ); } @@ -193,7 +193,7 @@ That's it! These meta functions are provided by [WC_Data](https://github.com/woo You can now use your new token type, either directly when building a new token -``` php +```php `$token = new WC_Payment_Token_eCheck();` // set token properties $token->save() @@ -211,7 +211,7 @@ This class provides a set of helpful methods for interacting with payment tokens Returns an array of token objects for the customer specified in `$customer_id`. You can filter by gateway by providing a gateway ID as well. -``` php +```php // Get all tokens for the current user $tokens = WC_Payment_Tokens::get_customer_tokens( get_current_user_id() ); // Get all tokens for user 42 @@ -224,7 +224,7 @@ $tokens = WC_Payment_Tokens::get_customer_tokens( get_current_user_id(), 'simpli Returns a token object for the token that is marked as 'default' (the token that will be automatically selected on checkout). If a user does not have a default token/has no tokens, this function will return null. -``` php +```php // Get default token for the current user $token = WC_Payment_Tokens::get_customer_default_token( get_current_user_id() ); // Get default token for user 520 @@ -235,7 +235,7 @@ $token = WC_Payment_Tokens::get_customer_default_token( 520 ); Orders can have payment tokens associated with them (useful for subscription products and renewing, for example). You can get a list of tokens associated with this function. Alternatively you can use `WC_Order`'s '`get_payment_tokens()` function to get the same result. -``` php +```php // Get tokens associated with order 25 $tokens = WC_Payment_Tokens::get_order_tokens( 25 ); // Get tokens associated with order 25, via WC_Order @@ -247,7 +247,7 @@ $tokens = $order->get_payment_tokens(); Returns a single payment token object for the provided `$token_id`. -``` php +```php // Get payment token 52 $token = WC_Payment_Tokens::get( 52 ); ``` @@ -256,7 +256,7 @@ $token = WC_Payment_Tokens::get( 52 ); Deletes the provided token. -``` php +```php // Delete payment token 52 WC_Payment_Tokens::delete( 52 ); ``` @@ -265,7 +265,7 @@ WC_Payment_Tokens::delete( 52 ); Makes the provided token (`$token_id`) the provided user (`$user_id`)'s default token. It makes sure that whatever token is currently set is default is removed and sets the new one. -``` php +```php // Set user 17's default token to token 82 WC_Payment_Tokens::set_users_default( 17, 82 ); ``` @@ -274,7 +274,7 @@ WC_Payment_Tokens::set_users_default( 17, 82 ); You can use this function If you have a token's ID but you don't know what type of token it is (credit card, eCheck, ...). -``` php +```php // Find out that payment token 23 is a cc/credit card token $type = WC_Payment_Tokens::get_token_type_by_id( 23 ); ``` @@ -287,7 +287,7 @@ $type = WC_Payment_Tokens::get_token_type_by_id( 23 ); Makes sure the credit card token has the last 4 digits stored, an expiration year in the format YYYY, an expiration month with the format MM, the card type, and the actual token. -``` php +```php $token = new WC_Payment_Token_CC(); $token->set_token( 'token here' ); $token->set_last4( '4124' ); @@ -303,7 +303,7 @@ var_dump( $token->validate() ); // bool(true) Get the card type (visa, mastercard, etc). -``` php +```php $token = WC_Payment_Tokens::get( 42 ); echo $token->get_card_type(); ``` @@ -312,7 +312,7 @@ echo $token->get_card_type(); Set the credit card type. This is a freeform text field, but the following values can be used and WooCommerce will show a formatted label New labels can be added with the `wocommerce_credit_card_type_labels` filter. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); $token->set_last4( 'visa' ); echo $token->get_card_type(); // returns visa @@ -320,7 +320,7 @@ echo $token->get_card_type(); // returns visa Supported types/labels: -``` php +```php array( 'mastercard' => __( 'MasterCard', 'woocommerce' ), 'visa' => __( 'Visa', 'woocommerce' ), @@ -335,7 +335,7 @@ array( Get the card's expiration year. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); echo $token->get_expiry_year; ``` @@ -344,7 +344,7 @@ echo $token->get_expiry_year; Set the card's expiration year. YYYY format. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); $token->set_expiry_year( '2018' ); echo $token->get_expiry_year(); // returns 2018 @@ -354,7 +354,7 @@ echo $token->get_expiry_year(); // returns 2018 Get the card's expiration month. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); echo $token->get_expiry_month(); ``` @@ -363,7 +363,7 @@ echo $token->get_expiry_month(); Set the card's expiration month. MM format. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); $token->set_expiry_year( '12' ); echo $token->get_expiry_month(); // returns 12 @@ -373,7 +373,7 @@ echo $token->get_expiry_month(); // returns 12 Get the last 4 digits of the stored credit card number. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); echo $token->get_last4(); ``` @@ -382,7 +382,7 @@ echo $token->get_last4(); Set the last 4 digits of the stored credit card number. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); $token->set_last4( '2929' ); echo $token->get_last4(); // returns 2929 @@ -396,7 +396,7 @@ echo $token->get_last4(); // returns 2929 Makes sure the eCheck token has the last 4 digits stored as well as the actual token. -``` php +```php $token = new WC_Payment_Token_eCheck(); $token->set_token( 'token here' ); var_dump( $token->validate() ); // bool(false) @@ -408,7 +408,7 @@ var_dump( $token->validate() ); // bool(true) Get the last 4 digits of the stored account number. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); echo $token->get_last4(); ``` @@ -417,7 +417,7 @@ echo $token->get_last4(); Set the last 4 digits of the stored credit card number. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); $token->set_last4( '2929' ); echo $token->get_last4(); // returns 2929 @@ -433,7 +433,7 @@ You should not use `WC_Payment_Token` directly. Use one of the bundled token cla Get the token's ID. -``` php +```php // Get the token ID for user ID 26's default token $token = WC_Payment_Tokens::get_customer_default_token( 26 ); echo $token->get_id(); @@ -443,7 +443,7 @@ echo $token->get_id(); Get the actual token string (used to communicate with payment processors). -``` php +```php $token = WC_Payment_Tokens::get( 49 ); echo $token->get_token(); ``` @@ -452,7 +452,7 @@ echo $token->get_token(); Set the token string. -``` php +```php // $api_token comes from an API request to a payment processor. $token = WC_Payment_Tokens::get( 42 ); $token->set_token( $api_token ); @@ -463,7 +463,7 @@ echo $token->get_token(); // returns our token Get the type of token. CC or eCheck. This will also return any new types introduced. -``` php +```php $token = WC_Payment_Tokens::get( 49 ); echo $token->get_type(); ``` @@ -472,7 +472,7 @@ echo $token->get_type(); Get the user ID associated with the token. -``` php +```php $token = WC_Payment_Tokens::get( 49 ); if ( $token->get_user_id() === get_current_user_id() ) { // This token belongs to the current user. @@ -483,7 +483,7 @@ if ( $token->get_user_id() === get_current_user_id() ) { Associate a token with a user. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); $token->set_user_id( '21' ); // This token now belongs to user 21. echo $token->get_last4(); // returns 2929 @@ -493,7 +493,7 @@ echo $token->get_last4(); // returns 2929 Get the gateway associated with the token. -``` php +```php $token = WC_Payment_Tokens::get( 49 ); $token->get_gateway_id(); ``` @@ -502,7 +502,7 @@ $token->get_gateway_id(); Set the gateway associated with the token. This should match the "ID" defined in your gateway. For example, 'simplify_commerce' is the ID for core's implementation of Simplify. -``` php +```php $token->set_gateway_id( 'simplify_commerce' ); echo $token->get_gateway_id(); ``` @@ -511,7 +511,7 @@ echo $token->get_gateway_id(); Returns true if the token is marked as a user's default. Default tokens are auto-selected on checkout. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); // Token 42 is a default token for user 3 var_dump( $token->is_default() ); // returns true $token = WC_Payment_Tokens::get( 43 ); // Token 43 is user 3's token, but not default @@ -522,7 +522,7 @@ var_dump( $token->is_default() ); // returns false Toggle a tokens 'default' flag. Pass true to set it as default, false if its just another token. This **does not** unset any other tokens that may be set as default. You can use `WC_Payment_Tokens::set_users_default()` to handle that instead. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); // Token 42 is a default token for user 3 var_dump( $token->is_default() ); // returns true $token->set_default( false ); @@ -537,7 +537,7 @@ Does a check to make sure both the token and token type (CC, eCheck, ...) are pr Load an existing token object from the database. See `WC_Payment_Tokens::get()` which is an alias of this function. -``` php +```php // Load a credit card toke, ID 55, user ID 5 $token = WC_Payment_Token_CC(); $token->read( 55 ); @@ -549,7 +549,7 @@ echo $token->get_user_id(); // returns 5 Update an existing token. This will take any changed fields (`set_` functions) and actually save them to the database. Returns true or false depending on success. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); // credit card token $token->set_expiry_year( '2020' ); $token->set_expiry_month( '06 '); @@ -560,7 +560,7 @@ $token->update(); This will create a new token in the database. So once you build it, create() will create a new token in the database with the details. Returns true or false depending on success. -``` php +```php $token = new WC_Payment_Token_CC(); // set last4, expiry year, month, and card type $token->create(); // save to database @@ -570,7 +570,7 @@ $token->create(); // save to database `save()` can be used in place of `update()` and `create()`. If you are working with an existing token, `save()` will call `update()`. A new token will call `create()`. Returns true or false depending on success. -``` php +```php // calls update $token = WC_Payment_Tokens::get( 42 ); // credit card token $token->set_expiry_year( '2020' ); @@ -586,7 +586,7 @@ $token->save(); Deletes a token from the database. -``` php +```php $token = WC_Payment_Tokens::get( 42 ); $token->delete(); ``` diff --git a/docs/shipping/shipping-method-api.md b/docs/shipping/shipping-method-api.md index f9e2e092979..06e1f4af658 100644 --- a/docs/shipping/shipping-method-api.md +++ b/docs/shipping/shipping-method-api.md @@ -16,7 +16,7 @@ Create a function to house your class To ensure the classes you need to extend exist, you should wrap your class in a function which is called after all plugins are loaded: -``` php +```php function your_shipping_method_init() { // Your class will go here } @@ -28,7 +28,7 @@ add_action( 'woocommerce_shipping_init', 'your_shipping_method_init' ); Create your class and place it inside the function you just created. Make sure it extends the shipping method class so that you have access to the API. You'll see below we also init our shipping method options. -``` php +```php if ( ! class_exists( 'WC_Your_Shipping_Method' ) ) { class WC_Your_Shipping_Method extends WC_Shipping_Method { /** @@ -82,7 +82,7 @@ You can then define your options using the settings API. In the snippets above y `calculate_shipping()`` is a method which you use to add your rates - WooCommerce will call this when doing shipping calculations. Do your plugin specific calculations here and then add the rates via the API. How do you do that? Like so: -``` php +```php $rate = array( 'label' => "Label for the rate", 'cost' => '10.99', @@ -95,7 +95,7 @@ $this->add_rate( $rate ); Add_rate takes an array of options. The defaults/possible values for the array are as follows: -``` php +```php $defaults = array( 'label' => '', // Label for the rate 'cost' => '0', // Amount for shipping or an array of costs (for per item shipping) @@ -110,7 +110,7 @@ Your shipping method can pass as many rates as you want - just ensure that the i The skeleton shipping method code all put together looks like this: -``` php +```php