Inventory Providers

Inventory Providers are established via the plugin system. These plugins are used as the bundle type for locations and inventory items, with inventory counts synced to the site. This gives a multitude of benefits to the site maintainer and users, since it allows

• multiple providers can be used at once (perhaps there is an in-store instance using Square but a warehouse using Lighthouse)
• providers can react to specific events, like inventory adjustment, inventory location or item updates, etc. – this allows a uniform adjustment process regardless of provider
• providers can easily establish fields on both the location and inventory item to better track custom related data (remote ID is supported by default with an easy method to return autocomplete options on the plugin class)
• basing inventory counts off of synced data allows the site to not miss a sale if there is a poor connection to the provider's API

Inventory Provider

Annotation

The following annotation properties are supported:

• id (string) – this is a unique provider plugin ID
• label (@Translation) - the label of the provider
• description (@Translation) - A brief description of the provider. Shown on the Add Inventory Location provider selection page.
• category (@Translation) – The type of category this provider fits under.
• item_remote_id_required (bool) – True if the Inventory Item requires a remote ID to be provided when adding the Inventory Item.
• location_remote_id_required (bool) – True if the Inventory Location requires a remote ID to be provided when adding the Inventory Location.

/**
 * Provides a default provider using Drupal storage.
 *
 * @CommerceInventoryProvider(
 *   id = "square",
 *   label = @Translation("Square"),
 *   description = @Translation("External inventory management using Square."),
 *   category = @Translation("External"),
 *   item_remote_id_required = true,
 *   location_remote_id_required = true
 * )
 */

(Example taken from the Commerce Inventory: Square module)

Plugin methods

Available extendable methods by entity-type/purpose:

General

/**
 * Adjust the provider-tracked quantity count of an Inventory Item.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryItemInterface $inventory_item
 *  The Inventory Item entity.
 * @param float $quantity
 *  The amount to either increase or decrease the provider-tracked quantity.
 *
 * @return bool
 *  A boolean indicating whether the sync completed successfully.
 */
public function adjustProviderQuantity(InventoryItemInterface $inventory_item, $quantity);

/**
 * Get provider's quantity for the Inventory Item.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryItemInterface $inventory_item
 *  The Inventory Item entity.
 *
 * @return float|null
 *  The Inventory Item's quantity from the provider. Null if check failed.
 */
public function getProviderQuantity(InventoryItemInterface $inventory_item);

/**
 * Sync the local and provider inventory count of an Inventory Item entity.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryItemInterface $inventory_item
 *  The Inventory Item entity.
 * @param bool $update_provider_from_local
 *  Whether the sync should update the provider count from local, or the
 *  local count from the provider.
 *
 * @return bool
 *  A boolean indicating whether the sync completed successfully.
 */
public function syncProviderQuantity(InventoryItemInterface $inventory_item, $update_provider_from_local = TRUE);

/**
 * Return a key-value list of Entity remote-ID options.
 *
 * @param string $q
 *  The search query to limit the results.
 * @param string $entity_type_id
 *  The entity type id to search for relevant remote ids.
 * @param array $contexts
 *  An associative array containing the entity object.
 *
 * @return array
 *  A key-value list of remote-ID options.
 */
public function getRemoteIdOptions($q, $entity_type_id, array $contexts = []);

/**
 * Check whether a remote ID is valid.
 *
 * @param string $value
 *  The remote ID to validate.
 * @param string $entity_type_id
 *  The entity type id to search for relevant remote ids.
 * @param array $contexts
 *  An associative array containing the entity object.
 *
 * @return bool
 *  True if the remote ID is valid. False otherwise.
 */
public function validateRemoteId($value, $entity_type_id, array $contexts = []);

/**
 * Alter the bundle field definitions for the entity.
 *
 * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
 *  The entity type definition. Useful when a single class is used for
 *  multiple, possibly dynamic entity types.
 * @param string $bundle
 *  The bundle.
 * @param \Drupal\Core\Field\FieldDefinitionInterface[] $base_field_definitions
 *  The list of base field definitions.
 *
 * @return \Drupal\Core\Field\FieldDefinitionInterface[]
 *  An array of bundle field definitions, keyed by field name.
 */
public function bundleFieldDefinitionsAlter(EntityTypeInterface $entity_type, $bundle, array $base_field_definitions);

Inventory Adjustment

/**
 * Acts on an adjustment before the presave hook is invoked.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryAdjustmentInterface $adjustment
 *  The Inventory Adjustment to act on.
 */
public function onAdjustmentPreSave(InventoryAdjustmentInterface $adjustment);

/**
 * Acts on an adjustment after the postsave hook is invoked.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryAdjustmentInterface $adjustment
 *  The Inventory Adjustment to act on.
 */
public function onAdjustmentPostSave(InventoryAdjustmentInterface $adjustment);

Inventory Item

/**
 * Whether Inventory Items need additional configuration on creation.
 *
 * @return bool
 *  True if addition configuration is needed. False otherwise.
 */
public function isItemConfigurationRequired();

/**
 * Returns whether an Inventory Item is valid for this type.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryItemInterface $inventory_item
 *  The Inventory Item to validate.
 *
 * @return bool
 *  True of the Inventory item is valid. False otherwise.
 */
public function validateItemConfiguration(InventoryItemInterface $inventory_item);

/**
 * Acts on a created entity before hooks are invoked.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryItemInterface $inventory_item
 *  The Inventory Item to act on.
 */
public function onItemPostCreate(InventoryItemInterface $inventory_item);

/**
 * Acts on an entity before the presave hook is invoked.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryItemInterface $inventory_item
 *  The Inventory Item to act on.
 */
public function onItemPreSave(InventoryItemInterface $inventory_item);

/**
 * Acts on a saved entity before the insert or update hook is invoked.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryItemInterface $inventory_item
 *  The Inventory Item to act on.
 * @param bool $update
 *  Specifies whether the entity is being updated or created.
 */
public function onItemPostSave(InventoryItemInterface $inventory_item, $update = TRUE);

/**
 * Whether Inventory Items are required to have a remote ID .
 *
 * @return bool
 *  True of the Inventory Item remote ID is required. False otherwise.
 */
public function isItemRemoteIdRequired();

/**
 * Gets the current quantity of the Inventory Item's remote object.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryItemInterface $inventory_item
 *  The managed Inventory item.
 *
 * @return float|null
 *  Quantity if found, otherwise NULL.
 */
public function getItemRemoteQuantity(InventoryItemInterface $inventory_item);

Inventory Location

/**
 * Whether Inventory Locations are required to have a remote ID .
 *
 * @return bool
 *  True of the Inventory Location remote ID is required. False otherwise.
 */
public function isLocationRemoteIdRequired();

/**
 * Acts on a created entity before hooks are invoked.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryLocationInterface $inventory_location
 *  The Inventory Location to act on.
 */
public function onLocationPostCreate(InventoryLocationInterface $inventory_location);

/**
 * Acts on an entity before the presave hook is invoked.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryLocationInterface $inventory_location
 *  The Inventory Location to act on.
 */
public function onLocationPreSave(InventoryLocationInterface $inventory_location);

/**
 * Acts on a saved entity before the insert or update hook is invoked.
 *
 * @param \Drupal\commerce_inventory\Entity\InventoryLocationInterface $inventory_location
 *  The Inventory Location to act on.
 * @param bool $update
 *  Specifies whether the entity is being updated or created.
 */
public function onLocationPostSave(InventoryLocationInterface $inventory_location, $update = TRUE);