Products' Options' Stock Manager (POSM)

Version 5.0.0, supporting Zen Cart versions v1.5.8a and later

Copyright © 2014-2024, Vinos de Frutas Tropicales, contact me here. Current Support Thread on github: https://github.com/lat9/options_stock_support; click here to access the plugin's product page.


The majority of the POSM documentation is available on-line.


v5.0.0 and later of POSM is distributed as a Zen Cart encapsulated plugin. Before installing this version (especially if you are updating from a version prior to v5.0.0), make sure you read this online article that identifies core-file changes that might be required and how to upgrade from a non-encapsulated version.


Notes:

  1. This version of POSM, now a Zen Cart encapsulated plugin, has been validated on Zen Cart versions 1.5.8a through 2.0.1 and PHP versions 7.4 through 8.3.
  2. Not supported for stores using templates purchased from either Template Monster or Theme Forest.
  3. The minimum Zen Cart version supported is v1.5.8a.
  4. The minimum PHP version supported is 7.4.
  5. A fresh installation of this plugin will update your database so that all product quantities are greater than or equal to 0.
  6. Products whose individual option-combinations (a.k.a variants) are managed by POSM must have their Product Qty Min/Unit Mixed value set to "No" in their product-edit screen, especially when your store's Configuration :: Stock :: Allow Checkout is set to false. Once the plugin is installed, its admin-level initialization script forces all products that are POSM-managed to this setting.
  7. POSM has been designed to work hand-in-hand with Edit Orders, maintaining your store's option-combinations' stock levels during the editing process. The POSM admin-level installation checks to see if EO is configured and, if so, that the Edit Orders plugin version is at least 4.1.7. If an incompatibility is detected, an admin-level warning will be displayed until the issue is resolved.
  8. A configuration setting is provided to enable POSM to check that any back-in-stock dates you've configured aren't within their expiration "window". If any such dates are found, an admin-level warning is displayed.

Overview

This plugin provides a way for you to assign stock levels for your products based on product-attribute combinations. For example, if you sell T-shirts with sizes of Small, Medium and Large, this plugin enables you to specify that there are 3-Small, 4-Medium and 2-Large currently in stock — and then manages those stock levels for you. That's the easy part, what if you have a product that has three (3) options:

  1. Size: Small, Medium and Large
  2. Color: Black, White, Red, Blue and Pink
  3. Trim-color: Black, White, Red, Blue and Pink

You don't actually stock all 75 option-combinations for this product, just a select subset. The Products' Options' Stock Manager (POSM) allows you to choose which option-combinations you actually stock and want to manage. Each managed option can be configured to have a unique Model/SKU and a customized out-of-stock message. If you choose, managed products with multiple options are handled as dependent attributes!

An admin tool is provided to enable shops that currently use the Zen Cart Stock by Attributes (SBA) plugin to convert their SBA database records into their POSM equivalents. See this online article for more information.

Additional documentation can be found on-line:

  1. Storefront Displays
  2. Configuration Options
  3. Other Admin Tools
  4. DbIo Handlers

Installing, Upgrading or Uninstalling

This section identifies the processes you'll use to initially install POSM, update an existing POSM installation or uninstall POSM entirely. There's also a section that identifies the database changes made by the plugin's installation.

Initial Installation

The plugin's installation makes changes to your database but since it's now an encapsulated plugin, there are no core-file changes; you should always backup your cart's database and files prior to making any changes.

Plugin Installation

Start by copying the POSM distribution's zc_plugins directory (and all its files) to the root of your site's file-system. You should see a zc_plugins/POSM sub-directory when completed and …

  1. Login to your Zen Cart's admin
  2. Navigate to Modules :: Plugin Manager.
  3. Click on the row that displays a Plugin Key of POSM and click the associated Install button.
  4. All finished! You'll now see new configuration settings and tools available in your Zen Cart admin's upper menu.

Optional, Non-Encapsulated Admin Files

If your site makes use of the Database I/O Manager, the POSM distribution includes handlers to enable the import and export of its newly-added database tables.

  1. Copy the files in the POSM distribution's /YOUR_ADMIN/includes sub-directory to your cart's admin's /includes sub-directory:
    1. /YOUR_ADMIN/includes/classes/dbio/DbIoOptionsStockBase.php (added in v2.2.0)
    2. /YOUR_ADMIN/includes/classes/dbio/DbIoOptionsStockFullHandler.php (added in v2.2.0)
    3. /YOUR_ADMIN/includes/classes/dbio/DbIoOptionsStockNamesHandler.php (added in v2.2.0)
    4. /YOUR_ADMIN/includes/classes/dbio/DbIoOptionsStockUpdateHandler.php (added in v2.2.0)
    5. /YOUR_ADMIN/includes/languages/english/dbio/DbIoOptionsStockFullHandler.php (added in v2.2.0)
    6. /YOUR_ADMIN/includes/languages/english/dbio/DbIoOptionsStockNamesHandler.php (added in v2.2.0)
    7. /YOUR_ADMIN/includes/languages/english/dbio/DbIoOptionsStockUpdateHandler.php (added in v2.2.0)

Upgrading

Upgrading From POSM 5.0.0 or Later

Easy, peasy …

  1. Navigate to your Zen Cart admin's Modules :: Plugin Manager.
  2. Click on the row that displays a Plugin Key of POSM and click the associated Update Available button.
  3. From the confirmation form, choose the to-be-used upgrade version and click the Upgrade button. No changes are made to your site's existing POSM configuration settings or database changes.

Upgrading From a POSM Version Prior to 5.0.0

OK, promise broken, but while the upgrade to POSM 5.0.0 is also going to be complicated, now that it's a Zen Cart encapsulated plugin it'll really be much easier in the future!

  1. First, you need to remove all files associated with a non-encapsulated POSM version. Without these steps, you will likely experience PHP errors when running your site's admin.
    1. Copy the plugin's /YOUR_ADMIN/posm_500_update_file_checks.php to the root of your Zen Cart's admin directory, where the file admin_access.php resides.
    2. Navigate to your Zen Cart admin's home page (e.g. https://mysite.com/myadmin), add a parameter to that URL (https://mysite.com/myadmin?cmd=posm_500_update_file_checks) and press the "Enter" key to cause the script to run.
      • If no non-encapsulated POSM files are found, you'll be returned to your admin's home page with a successful message.
      • Otherwise, follow the instructions from the tool to cause those non-encapsulated files to be removed or renamed so that the encapsulated version can be installed without issue.
    3. When all files have been successfully removed or renamed, delete the file you copied in step#1.
  2. If your site runs on Zen Cart 1.5.8a, 2.0.0 or 2.0.1, there are core-file changes required for proper storefront operation. See this support-site wiki article for more information.
  3. Since the non-encapsulated files have now been removed or renamed, follow the Plugin Installation steps to install the encapsulated version of the plugin. No changes are made to your site's existing POSM configuration settings or database changes.

Uninstalling

To uninstall POSM

  1. Navigate to your Zen Cart admin's Modules :: Plugin Manager.
  2. Click on the row that displays a Plugin Key of POSM and click the associated Un-Install button.
  3. From the confirmation form, click that Un-Install button.
  4. If you also want to remove the files associated with the plugin, click the Clean Up button.

Interactions With Other Plugins

The Products' Options' Stock Manager appends each ordered product's in-/out-of-stock messages in the products_name field within your database's orders_products table. This information is used by POSM when you are administrating those orders to ensure that the associated product's option-combination quantities are properly maintained.

If your store chooses to not display these messages (via configuration settings), but you have plugins that also perform order-related tasks … those stock messages might still be displayed by those plugins:

  1. If the plugin makes use of the Zen Cart "order" class, POSM's admin-level observer "watches" for this class' instantiation and automatically removes the stock messages from the order-object's products' names.
  2. If the plugin gathers the order-related information directly from the database, then the stock messages will still be appended to the end of the products' names — unless you make the following code-change! Starting with v2.1.5 of POSM, the admin-level observer provides a function that can be used by any caller to remove those messages. You'll use a PHP statement similar to:

    $products_name = $posObserver->stripStockMessage($products_name);

    wherever that other plugin is dealing with an order's products' names. Don't forget to declare the $posObserver object as global if the plugin's product-name manipulation occurs within a function!

    Note: Updating an ordered product's name in the database and removing POSM's stock message will have unwanted consequences, as any update to the associated order will no longer be able to track the product-variant's stock level.

Change History