Documentation of Advanced Shipping extension for Magento 2 by Owebia

Introduction

Advanced Shipping is an extension for the e-commerce solution Magento.

The syntax using PHP 5.6 allows a great flexibility in setting delivery charges.

Technical Informations

The usage of the PHP syntax (with an Abstract Syntax Tree) has been preferred to the usage of a JSON syntax (with regular expressions and the eval function) as in previous versions of the extension. This is the result of considerations on security and performance.

The PHP code defined in the configuration is not evaluated with the eval function for security reasons. The library PHP-Parser is used to obtain an Abstract Syntax Tree (AST). The AST is browsed and only a limited set of functions and variables is allowed.

As the AST is not version-dependent, you can use the PHP 5.6 syntax even if your server uses a lower version of PHP.

Add-ons

You want to do more with Advanced Shipping?

Discover our add-ons on Owebia Store.

Advanced Shipping Pro

Advanced Shipping with all its add-ons (see the list below)

Unlimited Carriers Add-on

Create as many carrier as you need with Advanced Shipping

Functions Add-on

Use functions to simplify the writing of your configuration
Look at "With Functions Add-on" tabs in examples to see how easy it becomes with this add-on

Universal Setting Add-on

Hide or change price of methods regardless the shipping module

What's new?

Installation

Please note that you can only install the extension using composer.

Quick start

A call to addMethod function adds a shipping method.

addMethod ( string $method_id , array $method_properties ) : object

List of method properties:

More examples

Warning: to avoid conflicts, use only the characters a-z, 0-9 and _ for the method id.
You should also avoid identifiers that already correspond to variable names (quote, request…).

Use Variables and Functions

You can use variables, functions and operators to define a dynamic value (all operators are not supported).

1. Variables

There are global variables and local variables that you can access with array functions and callbacks.

If you activate the debug option, you can see all data available for each object that you use.
Remember that you don't have access to all methods of the original objects because they are not accessed directly.

1.1. Global variables

These variables are global variables and can be accessed everywhere (use the global keyword when you are inside a function).

  • The request object (\Magento\Quote\Model\Quote\Address\RateRequest) given by Magento:
    • $request->all_items: array of items in cart
    • The source address:
      • $request->country_id *
      • $request->region_id
      • $request->city
      • $request->postcode
    • The destination address:
    • The package:

      • $request->package_value: value of the package
      • $request->package_value_with_discount: value of the package with discount
      • $request->package_weight: weight of the package
      • $request->package_qty: number of products in the package
    • Other attributes:
      • $request->free_shipping: free shipping calculated by Magento rules
      • $request->*: property of the request object
  • The quote (\Magento\Quote\Model\Quote): (known issue #2, known issue #3)
    • $quote->subtotal: subtotal (excluding tax)
    • $quote->subtotal_with_discount: subtotal (excluding tax) with discount
    • $quote->grand_total: total (including tax) with discount (known issues #3, you should avoid using this value)
    • $quote->base_subtotal: subtotal (excluding tax) in base currency
    • $quote->base_subtotal_with_discount: subtotal (excluding tax) with discount in base currency
    • $quote->base_grand_total: total (including tax) with discount in base currency (known issues #3, you should avoid using this value)
    • $quote->coupon_code: the coupon code used in cart
    • $quote->*: property of the quote (ex: $quote->subtotal)
  • The customer group (\Magento\Customer\Model\Group):
    • $customer_group->id: alias of $customer_group->customer_group_id
    • $customer_group->code: alias of $customer_group->customer_group_code
    • $customer_group->name: alias of $customer_group->customer_group_code
    • $customer_group->*: property of the customer group (ex: $customer_group->tax_class_id)
  • The customer (\Magento\Customer\Model\Customer):
    • $customer->id: alias of $customer->entity_id
    • $customer->*: attribute of the customer (ex: email, lastname, firstname, group_id…)
    • $customer->getCustomAttribute('my_custom_attribute')->value: custom attribute of the customer (where 'my_custom_attribute' should be replaced by custom attribute's code)
  • Custom variables (\Magento\Variable\Model\Variable):
    • $variable->*: custom variable defined in Magento (ex: $variable->my_var)
  • The store (\Magento\Store\Model\Store):
    • $store->id, $store->code, $store->name, $store->address, $store->phone
  • The app (see \Magento\Framework\App\State):
    • $app->area_code
    • $app->isAdminArea() (area_code == 'adminhtml')
    • $app->isFrontendArea() (area_code == 'webapi_rest')

* Magento apparently uses the ISO 3166-1 alpha-2 codes.
Note that the country code for United Kingdom is GB and not UK.

1.2. Accessing items

You can use $request->all_items with array functions.

  • The item (\Magento\Quote\Model\Quote\Item):
    • $item->qty: quantity of the item
    • $item->weight: weight of the item
    • $item->base_original_price: price excluding tax without discount
    • $item->price_incl_tax: price including tax without discount
    • $item->options->*: option (the available options depend on the product)
  • The product (\Magento\Catalog\Model\Product):
    • $item->product->*
      • sku
      • name
      • weight
      • price (as defined in Magento backoffice)
      • special_price: (as defined in Magento backoffice)
      • tax_class_id: the taxclass id
      • getAttributeText('tax_class_id'): the tax class name
        To get the text value of an attribute of type select, use getAttributeText('attribute_code')
    • Categories of the product: (\Magento\Catalog\Model\Category)
      • $item->product->category->*: attribute of the first category
        • id
        • name
        • is_active
    • All product categories (returns an array, examples):
      • $item->product->category_ids: array of id of the categories
    • The attribute set (\Magento\Eav\Model\Entity\Attribute\Set):
      • $item->product->attribute_set: the attribute set
      • $item->product->attribute_set->*: attribute of the attribute set
        • id
        • attribute_set_name
    • The stock item (\Magento\CatalogInventory\Model\Stock\Item):
      • $item->product->stock_item->*: attribute of the product stock
        • is_in_stock
        • qty

2. Functions

2.1. Native functions allowed

Look at the PHP documentation if you want to know how to use these functions.

2.2. Functions available with Functions Add-On

  • _country ( string $country_id1 [, string $... ] ) : bool:
    Returns true if the destination country matches one of the given country IDs, see examples
  • _postcode ( string $postcode_or_pattern1 [, mixed $... ] ) : bool:
    Returns true if the destination postcode matches one of the given postcodes or regular expression patterns, see examples
  • _customerGroup ( mixed $customer_group_id_or_name1 [, mixed $... ] ) : bool:
    Returns true if the customer group matches one of the given ids or names, see examples
  • _sum ( mixed $value1 [, mixed $... ] ) : mixed:
    Returns the sum of the given values, see examples
  • _min ( mixed $value1 [, mixed $... ] ) : mixed:
    Returns the minimum of the given values, see examples
  • _max ( mixed $value1 [, mixed $... ] ) : mixed:
    Returns the maximum of the given values, see examples
  • _count ( callable $callback ) : int:
    Returns the number of matching items using a callback function, see examples
  • _anyCat ( object $item, int $category_id1 [, int $... ] ) : bool:
    Returns true if the item belongs to one of the given categories, see examples
  • _allCat ( object $item, int $category_id1 [, int $... ] ) : bool:
    Returns true if the item belongs to all given categories, see examples
  • _table ( array $table [, string $attribute_name = 'package_weight' [, bool $include_upper_limit = true ]] ) : mixed:
    Returns true if the item belongs to all given categories, see examples
  • _setStopAtFirstMatch ( bool $stop_at_first_match ) : void:
    Sets option to stop adding methods at first match (must be used at the beginning of the configuration)

2.3. Custom functions

  • __ ( string $string_to_translate ) : string:
    Translates the input string, see example
  • addMethod ( string $method_id , array $method_properties ) : object:
    Adds a new shipping method
  • addError ( string $message ) : object:
    Adds an error, see example
  • getMethods ( [ bool $only_enabled = false ] ) : array:
    Gets an array of defined shipping methods, if $only_enabled is true, only enabled methods will be returned, see example

Examples

Free shipping

Filter on destination

France excluding DOM/TOM

Filter on customer group

You can use the name or ID of the customer groups.

Using formulas

Formulas can be used to calculate the price of the delivery.

Using the configuration of another element

Using special functions

Defining a table

Using an associative table

Using the attributes and options of products

Count items

Get minimum value, get maximum value

Sum

Using categories

Warning: you must notice that in Magento, a product can be in multiple categories.
So be particularly careful how you use this property.

Hints and tips

Using if/elseif/else statements

Access new customer data (ex. VAT ID)

Known issue with Magento CE < 2.1.8

Using custom customer attribute

In the following example, my_custom_attribute is a custom customer attribute created by a custom extension.

Translate a string

You can translate a string by using the __ function (two underscore characters). It will use Magento dictionary to translate the input string.

Display an error when no method is available

Add this at the end of your configuration:

Use method chaining

Display method description in frontend templates

Read Magento DevDocs to understand how to override a template.

Display custom method data in frontend templates

Read Magento DevDocs to understand how to override a template.

Known issues

© 2016-2019 Owebia