Skip to content

Upgrade guides

Jump to bottom Edit New page
Illimar Tambek (GoDaddy) edited this page Jun 3, 2024 · 31 revisions

Upgrading a plugin implementation of the framework

When updating the SkyVerge Plugin Framework in a plugin that has already implemented it, make sure to take the following steps.

1. Bump the composer dependency

Update the plugin's composer.json to use the intended framework version, e.g.:

  "require": {
    "skyverge/wc-plugin-framework": "5.12.4"
  },

2. Bump the framework version in the plugin loader

Plugins use a loader to load the framework and the plugin. This is typically the main WordPress plugin file, see the loader template for reference.

Plugins utilizing this template typically bump the FRAMEWORK_VERSION constant to match the framework version indicated in the composer.json file.

3. Search and replace framework namespaces

To avoid namespace collisions when multiple plugins are loaded and active in a WordPress installation, the SkyVerge Plugin Framework utilizes namespaces to differentiate each version, so that plugins embedding different framework versions can coexist without causing collisions and PHP errors.

When updating the framework from a version to another, search for instances of SkyVerge\WooCommerce\PluginFramework\v<x>_<y>_<x> where x_y_z is the semver version of the framework you're updating from and replace those instances with the version you're updating to.

This normally applies to all files within includes or src, but may apply to other files outside these directories, such as the plugin main class, typically located at the root of the project if the plugin doesn't implement PHP autoloading.

Also, this may apply to scripts in the assets/js directory that declare JavaScript class names intended for use with some framework script handlers.

Any test files located in tests may require updating those namespaces references too.

4. Test!

Before tagging a new version of a plugin that updated its framework, it should be thoroughly tested. Run any automated tests and user tests as necessary to ensure no issues arise from the upgrade.

Be mindful of additional upgrade caveats, deprecated methods, or classes detailed in the sections below.

Upgrading to a specific version

Below are guides to each new version of the framework, detailing any extra steps needed or backwards incompatibilities to be aware of when upgrading a plugin. If no steps are listed, you can check the release's changelog entries for any changes you'll want to test after upgrading.

v5.11.11

The supports_hpos key from v5.11.0 below has been replaced by a supported_features key which will hold an array like so (defaults):

[
  'hpos'    => false
  'blocks'  => [
    'cart'     => false,
    'checkout' => false,
  ]
]

This is to add more compatibility flags for other WC features, such as blocks.

v5.11.0

This release introduced support for HPOS (High Performance Order Storage) that moved the orders from the posts table to a custom table in WooCommerce. For a plugin to declare itself compatible with HPOS it needs to pass a new key to the SV_WC_Plugin constructor arguments 'supports_hpos' => true, otherwise it is assumed false.

v5.10.2

Payment gateways, plugins that use the Setup Wizard or batch/background jobs processing, can update to this version of the framework to address deprecation issues with jQuery related to the framework.

v5.10.1

Payment gateways

  • Ensure any implementations of SV_WC_Payment_Gateway::do_invalid_transaction_response() match the method's signature

Setup wizard

  • If implemented, ensure the plugin's setup wizard functions as intended. The admin_head action was removed from the wrapper page markup.

v5.10.0

Payment Gateways

Apple Pay

  • Due to the refactor done when implementing Google Pay, Apple Pay needs to be thoroughly tested for any payment gateway plugin that supports it

v5.8.0

Payment Tokens

  • Update the build_token() method in subclasses of SV_WC_Payment_Gateway_Payment_Tokens_Handler to accept an instance of \WC_Payment_Token or an array as the second parameter ($data)

  • Update the constructor in subclasses of SV_WC_Payment_Gateway_Payment_Token to accept an instance of \WC_Payment_Token or an array as the second parameter ($data)

  • Make sure that API response classes that implement SV_WC_Payment_Gateway_API_Create_Payment_Token_Response or SV_WC_Payment_Gateway_API_Get_Tokenized_Payment_Methods_Response include a value for each of the following keys in the token data:

    • Credit Card tokens
      • last_four
      • exp_year (four characters)
      • exp_month (two characters)
      • card_type
    • eCheck tokens
      • last_four

    If the API response doesn't include enough information, we may need to update SV_WC_Payment_Gateway_Payment_Tokens_Handler::merge_token_data() or otherwise ensure those values are available before calling save() on the core token.

My Payment Methods table

We removed the framework's table in favor of WooCommerce's table of payment methods. As a result, the following hooks were deprecated:

  • wc_{$plugin_id}_my_payment_methods_table_html
  • wc_{$plugin_id}_my_payment_methods_table_head_html
  • wc_{$plugin_id}_my_payment_methods_table_title (listed in Intuit Payments as a replacement for another hook)
  • wc_{$plugin_id}_my_payment_methods_table_title_html
  • wc_{$plugin_id}_my_payment_methods_table_row_html
  • wc_{$plugin_id}_my_payment_methods_table_body_html
  • wc_{$plugin_id}_my_payment_methods_table_body_row_data (used by Chase Paymentech)
  • wc_{$plugin_id}_my_payment_methods_table_method_expiry_html
  • wc_{$plugin_id}_my_payment_methods_table_actions_html

Make sure to remove usage of those hooks to avoid triggering deprecated notices.

Moving forward, the following core hooks could be used to customize some of the information displayed in the table:

  • Use filter woocommerce_payment_methods_list_item to define custom actions for individual tokens
  • Use filter woocommerce_account_payment_methods_columns to define additional columns for the table
  • Use action woocommerce_account_payment_methods_column_{custom_column_id} to render the content of a coulumn for an individual token

Documentation URL

v5.7.0

JS handling in registered scripts

A new SkyVerge\WooCommerce\PluginFramework\vX_Y_Z\Frontend\Script_Handler abstract class was added. See JavaScript Handling for usage instructions and a description of the internal changes.

Plugins that extend one of the PHP Handler or JavaScript Handler classes may need to update their implementations as follows:

  • Update JavaScript classes that extend:
    • SV_WC_Payment_Form_Handler to extend SV_WC_Payment_Form_Handler_vX_Y_Z
    • SV_WC_Apple_Pay_Handler to extend SV_WC_Apple_Pay_Handler_vX_Y_Z
    • SV_WC_Payment_Methods_Handler to extend SV_WC_Payment_Methods_Handler_vX_Y_Z
  • Subclasses of SV_WC_Payment_Gateway_Payment_Form and SV_WC_Payment_Gateway_My_Payment_Methods that overwrite render_js() should consider overwriting get_js_handler_args() instead or make sure that the subclass version renders the new snippet (See description of the enqueued JavaScript code).
  • Subclasses of SV_WC_Payment_Gateway_Payment_Form and SV_WC_Payment_Gateway_My_Payment_Methods that use a different class name for the JavaScript handler should overwrite get_js_handler_class_name() to return the appropriate name.
  • Subclasses of SV_WC_Payment_Gateway_Apple_Pay_Frontend that overwrite get_js_handler_params() should overwrite get_js_handler_args() instead (no deprecation needed)
  • Subclasses of SV_WC_Payment_Gateway_Apple_Pay_Frontend that overwrite get_js_handler_name() should overwrite get_js_handler_class_name() instead (no deprecation needed)
  • Subclasses of SV_WC_Payment_Gateway that overwrite get_payment_form_instance() should overwrite init_payment_form_instance() instead to avoid creating two instances of the Payment Form class.

v5.5.2

  • For plugins extending SV_WC_API_Base
    • If overriding ::require_tls_1_2(), move the method to the plugin's base class

v5.5.0

See the list of deprecated methods that will throw a notice if used.

More legacy versions coming soon...

Add a custom footer
Clone this wiki locally