Migrating to v5

When migrating a plugin that implements this framework from v4.9 or earlier to v5, the biggest change will be handling the new namespaces. Additionally, there are a few backwards-incompatible changes that will need to be handled. The following steps should cover most of the changes required, though it's always important to test a plugin's full range of functionality after the migration.

Composer

1. Delete the plugin's /lib/skyverge directory and commit
2. Add a new composer.json file to the plugin or project root, containing:

{
  "minimum-stability": "dev",
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/skyverge/wc-plugin-framework"
    }
  ],
  "require" : {
    "skyverge/wc-plugin-framework": "5.4.0"
  }
}

1. Change the package version to the desired tagged framework version, or if working off a specific branch, use dev- then the branch name, e.g. "skyverge/wc-plugin-framework": "dev-5.2.0-dev"
2. Commit and run composer install

Loader Class

Plugins will now require a loader class to handle unsupported PHP versions. The loader class must be defined and instantiated in the main plugin file, and is meant to halt any further plugin code from being included if the environment can't support it. To implement the loader class in an existing plugin:

1. Create a new file in the plugin root that will contain the main plugin class and name it according to WordPress standards. For instance, if the plugin class (which should extend SV_WC_Plugin) is WC_Authorize_Net_AIM, then the new file would be /class-wc-authorize-net-aim.php
2. Cut the entire plugin class from the main plugin file into this new class file, also include the main plugin function definition, which usually follows the class. Do not copy the init_ wrapping function if one exists.
3. Search for a usage of the legacy sv_wc_framework_plugins_loaded bootstrap action, usually within the main plugin class constructor, and instead call its callback directly. e.g. add_action( 'sv_wc_framework_plugins_loaded', array( $this, 'includes' ) ); becomes just $this->includes();.
4. From the main plugin file, clear any code after the is_woocommerce_active() check.
5. Replace with the contents of the framework example loader class, and clear all of the TODO items for renaming classes and methods where necessary.

Namespaces

1. On every PHP plugin file except for the main file, add a use statement under the ABSPATH check for the framework's namespaces: use SkyVerge\WooCommerce\PluginFramework\v5_4_0 as Framework;Be sure to replace the version namespace with the framework version you're implementing.
2. Add the Framework\ namespace alias to every use of a framework class. Often you can first search & replace: SV_WC_ > Framework\SV_WC_.
3. Review the changes to ensure you've caught all of the instances, and that the new alias is used correctly in all cases.

Constructor Args

1. Remove display_php_notice
2. Update the dependencies array to match what's expected by SV_WC_Plugin::init_dependencies()

Includes

Some plugins will handle their includes and handler loading differently, so you'll have to handle each on a case-by-case basis. Some general notes:

• We've added the SV_WC_Plugin::init_plugin() & SV_WC_Plugin::init_admin() methods that are fired at plugins_loaded and admin_init respectively, and can be overridden for easy plugin setup. These are not required, but may be helpful.
• There's usually no need to change the way various handlers are instantiated aside from removing sv_wc_framework_plugins_loaded, but be sure to test each one!

Paths

Check if there is plugin code (PHP, static assets like SCSS) referencing directly files or other assets, including framework files, that are expected to be found in the /vendor path or /lib path. These paths may need to be updated after installing the framework and other libraries via composer.

Check for paths matching /lib/skyverge/woocommerce/assets/

Lifecycle

As of v5.2.0, the plugin lifecycle methods have been moved to SkyVerge\WooCommerce\PluginFramework\v5_2_0\Plugin\Lifecycle. If the plugin has existing upgrade or install routines, they will need to be moved to a class that extends this.

1. Create a class that extends SkyVerge\WooCommerce\PluginFramework\v5_4_0\Plugin\Lifecycle
2. Copy the upgrade() && install() methods from the main plugin into this new class and adapt them as needed. The FW class has a get_plugin() method, so instances of $this-> referencing the plugin can be changed to $this->get_plugin()->
3. Add the following function to your plugin class, making sure to replace Your_Plugin_Namespace with the namespace of your plugin

	/**
	 * Initializes the lifecycle handler.
	 *
	 * @since 1.0.0
	 */
	protected function init_lifecycle_handler() {

		require_once( $this->get_plugin_path() . '/includes/Lifecycle.php' );

		$this->lifecycle_handler = new \SkyVerge\WooCommerce\Your_Plugin_Namespace\Lifecycle( $this );
	}

Important -- Be sure to fully test the execution of each upgrade and install path after migration

Integrations

1. Add the following methods to any class that implements Framework\SV_WC_API_Request or extends Framework\SV_WC_API_XML_Request:
   • get_params()
   • get_data()

v5 refines the API classes a bit more to differentiate between API request query params and request body data. So while previously both were treated in the same way, now you need to specifically define what should be sent as query params, and what should be sent in the body of the request. This is done by setting the value of SV_WC_API_Request::$params and SV_WC_API_Request::$data respectively. Because these weren't previously separated, you may need to update where the data is set based on the HTTP request method.

For any class that extends Framework\SV_WC_API_JSON_Request or Framework\SV_WC_API_XML_Request, it's good to check the intended request method, like POST or GET, and make sure that the data variable being set matches that. So if the request is POST, but currently the body is being set by the $params variable, then that would need to be updated to use $data instead, since $data is now used for POST requests. It may be easiest to try the request in master and see how the logged request is formed, then make sure that is the same after migrating to FW v5. Some guidelines:

• POST requests can have both query params and body data
• GET requests can only have query params

Gateways

1. Add the get_payment_type() method to any response class that implements Framework\SV_WC_Payment_Gateway_API_Response, returning the appropriate payment type.
2. If overridden, ensure the gateway's do_credit_card_capture() method matches the new signature, and handles the new return value (array).
3. If overridden, sure the gateway's get_order_for_capture() method matches the new signature.
4. Search for any hardcoded card type strings, such as mc or diners, and switch them to using the gateway helper constants. Be sure to test these changes thoroughly as some gateways can return different card type strings.

That's it! The plugin should now be ready to fully test.

Deprecated Methods

At the time of introducing v5, the following were the methods that were deprecated:

• SV_WC_Plugin::do_install()
• SV_WC_Plugin::install_default_settings() -> Plugin\Lifecycle::install_default_settings()
• SV_WC_Plugin::get_missing_extension_dependencies() -> SV_WC_Plugin_Dependencies::get_missing_php_extensions()
• SV_WC_Plugin::get_missing_function_dependencies() -> SV_WC_Plugin_Dependencies::get_missing_php_functions()
• SV_WC_Plugin::get_incompatible_php_settings() -> SV_WC_Plugin_Dependencies::get_incompatible_php_settings()
• SV_WC_Plugin::get_dependencies()
• SV_WC_Plugin::get_extension_dependencies() -> SV_WC_Plugin_Dependencies::get_php_extensions()
• SV_WC_Plugin::get_function_dependencies() -> SV_WC_Plugin_Dependencies::get_php_functions()
• SV_WC_Plugin::get_php_settings_dependencies() -> SV_WC_Plugin_Dependencies::get_php_settings()
• SV_WC_Plugin::set_dependencies()

However, you should keep track of this list of deprecated methods as well:

• Deprecated Methods