Support for fractional product quantity and quantity units in shipping & payment plugins

As of Shop-Script version 9.0.0, the support for fractional product quantity and custom stock quantity units (in addition to standard pieces) are available.

Base quantity units configured in Shop-Script are not used by shipping and payment plugins; therefore, their support does not need be declared.

The support for this functionality is available only with the PREMIUM license and is not available for the PRO license. Read more about Shop-Script licenses.

Declaring support for extended functionality

For a correct integration with PREMIUM license’s extended functionality, shipping and payment plugins must contain a declaration for their support. The support of each of these two Shop-Script options must be defined in configuration file plugin.php as shown below:

'fractional_quantity' => ...,    // fractional quantity
'stock_units' => ...,            // stock quantity units

For each of these parameters, 3 possible values are available:

  • true: the option is supported by a plugin,
  • false: the option is not supported by a plugin,
  • null (or the parameter is not empty or missing in the file): the plugin developer cannot provide definite information, and the decision on whether to use the plugin is up to a user.

Plugin’s integration with Shop-Script

Depending on the values specified for each of the above parameters, Shop-Script will behave differently when interacting with a plugin:

  • true:
    • Shop-Script will let a plugin process all orders.
  • false:
    • If an order contains items requiring the availability of the corresponding extended functionality then Shop-Script does let a plugin process such an order.
    • Otherwise Shop-Script will let a plugin process an order as usual.
  • null:
    • If an order contains items requiring the availability of the corresponding extended functionality then Shop-Script will take the corresponding compatibility setting into account.
    • Otherwise Shop-Script will let a plugin process an order as usual.

Plugins compatibility settings

If a user has shipping and payment plugins installed which have value null set for PREMIUM license’s extended options then they can select on Shop-Script’s compatibility page how the online store must be integrated with such plugins.

Compatibility options for fractional product quantity

  • Do not let a plugin process orders containing items requiring fractional product quantity support.
  • Let a plugin process an order as is.
  • Let a plugin process an order with the quantities of order items converted into integer values when a fractional value is changed to 1 (piece) and the cost of the item’s 1 becomes equal to the item’s total cost.

Compatibility options for product quantity units

  • Do not let a plugin process orders containing items requiring configurable quantity units support (except for standard pieces).
  • Let a plugin process an order as is.

Declaration of Shop-Script PREMIUM license’s extended functionality support

In addition to declaring the support for fractional product quantity and quantity units in a configuration file, a plugin can also contain a special description of the plugin’s support for PREMIUM license’s extended functionality in a text form. This additional information will help users make a more reasonable decision on how exactly a plugin must be integrated with different Shop-Script licenses.

Use of waOrder class

  1. If fractional product quantities are enabled in Shop-Script settings then field ['items'][]['quantity'] of a waOrder class instance can contain fractional values. Otherwise only integer values can be contained in that field.
  2. If the use of different product quantity units is enabled in Shop-Script settings then an instance of the waOrder class will contain field ['items'][]['stock_unit']. If not empty, it contains a human-readable string denoting the order item’s quantity unit; e.g., “lb.” or “sq. ft.”. If the field is empty then the pieces unit is assumed by default.
  3. In the waOrder class are available public methods that can be used to determine whether PREMIUM license’s extended options are available.
    How to use them safely:
    • either specify the first Webasyst framework version, in which these methods became first available, in the configuration file requirements.php,
    • or, if you need to support older framework versions, use the method_exists() function in a plugin’s source code.
    • hasFractionalQuantity(): returns a flag denoting the availability of items in an order with fractional quantity values,
    • repackFractionalQuantity():
      • If an order contains items with fractional quantity values then this method creates and returns a new class instance, in which items with fractional quantities are converted into items with integer quantities when a fractional quantity value is changed to 1 piece and the cost of 1 item piece becomes equal to item’s total cost.
      • Otherwise this method does nothing and simply returns the current class instance.
    • hasStockUnits(): returns a flag denoting the availability of items in an order with custom quantity units (except for default pieces).