Release v6.1.5

.agents/guides/ABILITIES-IMPLEMENTATION-GUIDE.md

@@ -282,6 +282,49 @@ class WC_My_Plugin_Entity implements JsonSerializable
 - Use `minimum`, `minProperties`, `additionalProperties` where appropriate to enforce constraints. Arguments that accept any WP_Query arg should document "VIP" properties and then set `additionalProperties` to `true` to indicate any WP_Query arg can be used.
 - Descriptions should be short, practical, and include format hints (e.g. `"Country code (e.g. \"US\")."`).
 
+### Nested and sub-object serialization
+
+When your primary serializable object references other objects (e.g. an entity has rules, items, or addresses), the first consideration should be making those sub-objects serializable as well. This keeps serialization logic co-located with the class that understands its own structure.
+
+**Avoid** inline serialization of sub-objects:
+
+```php
+public function jsonSerialize()
+{
+    return [
+        'id'    => $this->get_id(),
+        'rules' => array_map(function ($rule) {
+            return [
+                'property' => $rule->get_property(),
+                'operator' => $rule->get_operator(),
+                'values'   => $rule->get_values(),
+            ];
+        }, $this->get_rules()),
+    ];
+}
+```
+
+**Instead**, make the sub-object serializable and delegate to it:
+
+```php
+public function jsonSerialize()
+{
+    return [
+        'id'    => $this->get_id(),
+        'rules' => array_map(function ($rule) {
+            return $rule->jsonSerialize();
+        }, $this->get_rules()),
+    ];
+}
+```
+
+This applies to both Option A and Option B. If the sub-object class has an abstract base class (e.g. a `Rule` base with `CartSubtotal`, `ProductOrCategory` concrete types), implement `JsonSerializable` on the base class with sensible defaults so that:
+
+- **Concrete subclasses** override only when their structure differs from the default (e.g. a rule with min/max values instead of a generic property/operator/values shape).
+- **Third-party subclasses** (from extensions or filters) get working serialization for free without needing to know about the contract.
+
+The same principle applies to `getJsonSchema()` — put defaults on the base class and only override where the subclass has genuinely different behavior.
+
 ---
 
 ## Step 2: Provider

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "skyverge/wc-plugin-framework",
   "description": "The official SkyVerge WooCommerce plugin framework",
-  "version": "6.1.4",
+  "version": "6.1.5",
   "license": "GPL-3.0",
   "minimum-stability": "dev",
   "prefer-stable": true,
@@ -35,12 +35,12 @@
       "woocommerce/class-sv-wp-admin-message-handler.php"
     ],
     "psr-4": {
-      "SkyVerge\\WooCommerce\\PluginFramework\\v6_1_4\\": "woocommerce/"
+      "SkyVerge\\WooCommerce\\PluginFramework\\v6_1_5\\": "woocommerce/"
     }
   },
   "autoload-dev": {
     "psr-4": {
-      "SkyVerge\\WooCommerce\\PluginFramework\\v6_1_4\\Tests\\": "tests/"
+      "SkyVerge\\WooCommerce\\PluginFramework\\v6_1_5\\Tests\\": "tests/"
     }
   },
   "config": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "wc-plugin-framework",
-  "version": "6.1.4",
+  "version": "6.1.5",
   "title": "WooCommerce Plugin Framework",
   "author": "SkyVerge Team",
   "homepage": "https://github.com/skyverge/wc-plugin-framework#readme",

tests/TestCase.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace SkyVerge\WooCommerce\PluginFramework\v6_1_4\Tests;
+namespace SkyVerge\WooCommerce\PluginFramework\v6_1_5\Tests;
 
 use WP_Mock\Tools\TestCase as WpMockTestCase;
 

tests/_support/plugins/gateway-test-plugin/includes/API.php

@@ -2,7 +2,7 @@
 
 namespace SkyVerge\WooCommerce\GatewayTestPlugin;
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
 
 defined( 'ABSPATH' ) or exit;
 

tests/_support/plugins/gateway-test-plugin/includes/Gateway.php

@@ -2,7 +2,7 @@
 
 namespace SkyVerge\WooCommerce\GatewayTestPlugin;
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
 
 defined( 'ABSPATH' ) or exit;
 

tests/_support/plugins/gateway-test-plugin/includes/Plugin.php

@@ -1,7 +1,7 @@
 <?php
 namespace SkyVerge\WooCommerce\GatewayTestPlugin;
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
 
 defined( 'ABSPATH' ) or exit;
 

tests/_support/plugins/test-plugin/includes/API.php

@@ -1,7 +1,7 @@
 <?php
 namespace SkyVerge\WooCommerce\TestPlugin;
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
 
 defined( 'ABSPATH' ) or exit;
 

tests/_support/plugins/test-plugin/includes/Gateway.php

@@ -1,7 +1,7 @@
 <?php
 namespace SkyVerge\WooCommerce\TestPlugin;
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
 
 defined( 'ABSPATH' ) or exit;
 

tests/_support/plugins/test-plugin/includes/Plugin.php

@@ -1,7 +1,7 @@
 <?php
 namespace SkyVerge\WooCommerce\TestPlugin;
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
 
 defined( 'ABSPATH' ) or exit;
 

tests/integration/API/CacheableAPIBaseTest.php

@@ -1,10 +1,10 @@
 <?php
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\API\Abstract_Cacheable_API_Base;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\API\Traits\Cacheable_Request_Trait;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_API_JSON_Request;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_API_Request;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\API\Abstract_Cacheable_API_Base;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\API\Traits\Cacheable_Request_Trait;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_API_JSON_Request;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_API_Request;
 
 if ( ! defined( 'ABSPATH' ) ) {
 	define( 'ABSPATH', true );

tests/integration/DependenciesTest.php

@@ -3,7 +3,7 @@
 /**
  * Tests for the SV_WC_Plugin_Dependencies class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Plugin_Dependencies
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Plugin_Dependencies
  */
 class DependenciesTest extends \Codeception\TestCase\WPTestCase {
 
@@ -31,7 +31,7 @@ protected function _after() {
 
 
 	/**
-	 * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Plugin_Dependencies::get_active_scripts_optimization_plugins()
+	 * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Plugin_Dependencies::get_active_scripts_optimization_plugins()
 	 */
 	public function test_get_active_scripts_optimization_plugins() {
 
@@ -40,7 +40,7 @@ public function test_get_active_scripts_optimization_plugins() {
 
 
 	/**
-	 * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Plugin_Dependencies::is_scripts_optimization_plugin_active()
+	 * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Plugin_Dependencies::is_scripts_optimization_plugin_active()
 	 */
 	public function test_is_scripts_optimization_plugin_active() {
 

tests/integration/HelperTest.php

@@ -1,11 +1,11 @@
 <?php
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
 
 /**
  * Tests for the helper class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Plugin_Compatibility
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Plugin_Compatibility
  */
 class HelperTest extends \Codeception\TestCase\WPTestCase {
 

tests/integration/PluginTest.php

@@ -3,7 +3,7 @@
 /**
  * Tests for the base plugin class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Plugin
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Plugin
  */
 class PluginTest extends \Codeception\TestCase\WPTestCase {
 
@@ -152,7 +152,7 @@ public function test_get_framework_assets_path() {
 	 */
 	public function test_get_dependency_handler() {
 
-		$this->assertInstanceOf( '\SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Plugin_Dependencies', $this->get_plugin()->get_dependency_handler() );
+		$this->assertInstanceOf( '\SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Plugin_Dependencies', $this->get_plugin()->get_dependency_handler() );
 	}
 
 
@@ -161,7 +161,7 @@ public function test_get_dependency_handler() {
 	 */
 	public function test_get_lifecycle_handler() {
 
-		$this->assertInstanceOf( '\SkyVerge\WooCommerce\PluginFramework\v6_1_4\Plugin\Lifecycle', $this->get_plugin()->get_lifecycle_handler() );
+		$this->assertInstanceOf( '\SkyVerge\WooCommerce\PluginFramework\v6_1_5\Plugin\Lifecycle', $this->get_plugin()->get_lifecycle_handler() );
 	}
 
 

tests/integration/REST_API/Controllers/SettingsTest.php

@@ -1,14 +1,14 @@
 <?php
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\REST_API\Controllers\Settings;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\Settings_API\Abstract_Settings;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\Settings_API\Setting;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\Settings_API\Control;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\REST_API\Controllers\Settings;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\Settings_API\Abstract_Settings;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\Settings_API\Setting;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\Settings_API\Control;
 
 /**
  * Tests for the Settings class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\REST_API\Controllers\Settings
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\REST_API\Controllers\Settings
  */
 class SettingsTest extends \Codeception\TestCase\WPTestCase {
 

tests/integration/REST_API/RESTAPITest.php

@@ -1,13 +1,13 @@
 <?php
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\Settings_API\Abstract_Settings;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Helper;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\Settings_API\Abstract_Settings;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Helper;
 
 /**
  * Tests for the REST_API class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\REST_API
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\REST_API
  */
 class RESTAPITest extends \Codeception\TestCase\WPTestCase {
 

tests/integration/SV_WC_Payment_Gateway_Helper_Test.php

@@ -1,11 +1,11 @@
 <?php
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Payment_Gateway_Helper;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Payment_Gateway_Helper;
 
 /**
  * Tests for the Payment Gateway Helper class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Payment_Gateway_Helper
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Payment_Gateway_Helper
  */
 class SV_WC_Payment_Gateway_Helper_Test extends \Codeception\TestCase\WPTestCase {
 

tests/integration/Settings_API/AbstractSettingsTest.php

@@ -1,15 +1,15 @@
 <?php
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\Settings_API\Abstract_Settings;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\Settings_API\Setting;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\Settings_API\Control;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Plugin_Exception;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\Settings_API\Abstract_Settings;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\Settings_API\Setting;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\Settings_API\Control;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Plugin_Exception;
 
 /**
  * Tests for the Abstract_Settings class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\Settings_API\Abstract_Settings
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\Settings_API\Abstract_Settings
  */
 class AbstractSettingsTest extends \Codeception\TestCase\WPTestCase {
 

tests/integration/Settings_API/SettingTest.php

@@ -1,7 +1,7 @@
 <?php
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\Settings_API\Setting;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Plugin_Exception;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\Settings_API\Setting;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Plugin_Exception;
 
 class SettingTest extends \Codeception\TestCase\WPTestCase {
 

tests/integration/payment-gateway/GatewayPluginTest.php

@@ -3,7 +3,7 @@
 /**
  * Tests for the gateway plugin class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Payment_Gateway_Plugin
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Payment_Gateway_Plugin
  */
 class GatewayPluginTest extends \Codeception\TestCase\WPTestCase {
 

tests/integration/payment-gateway/MyPaymentMethodsTest.php

@@ -1,12 +1,12 @@
 <?php
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Payment_Gateway_My_Payment_Methods;
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Payment_Gateway_Plugin;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Payment_Gateway_My_Payment_Methods;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Payment_Gateway_Plugin;
 
 /**
  * Tests for the SV_WC_Payment_Gateway_My_Payment_Methods class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Payment_Gateway_My_Payment_Methods
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Payment_Gateway_My_Payment_Methods
  */
 class MyPaymentMethodsTest extends \Codeception\TestCase\WPTestCase {
 
@@ -116,7 +116,7 @@ public function test_render_js() {
 		$payment_methods->render_js();
 
 		$this->assertStringContainsString( 'function load_gateway_test_plugin_payment_methods_handler', $wc_queued_js );
-		$this->assertStringContainsString( 'window.jQuery( document.body ).on( \'sv_wc_payment_methods_handler_v6_1_4_loaded\', load_gateway_test_plugin_payment_methods_handler );', $wc_queued_js );
+		$this->assertStringContainsString( 'window.jQuery( document.body ).on( \'sv_wc_payment_methods_handler_v6_1_5_loaded\', load_gateway_test_plugin_payment_methods_handler );', $wc_queued_js );
 	}
 
 

tests/integration/payment-gateway/PaymentFormTest.php

@@ -1,11 +1,11 @@
 <?php
 
-use SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Payment_Gateway_Payment_Form;
+use SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Payment_Gateway_Payment_Form;
 
 /**
  * Tests for the SV_WC_Payment_Gateway_Payment_Form class.
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Payment_Gateway_Payment_Form
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Payment_Gateway_Payment_Form
  */
 class PaymentFormTest extends \Codeception\TestCase\WPTestCase {
 
@@ -90,7 +90,7 @@ public function test_render_js() {
 		$this->get_plugin()->get_gateway()->get_payment_form_instance()->render_js();
 
 		$this->assertStringContainsString( 'function load_test_gateway_payment_form_handler', $wc_queued_js );
-		$this->assertStringContainsString( 'window.jQuery( document.body ).on( \'sv_wc_payment_form_handler_v6_1_4_loaded\', load_test_gateway_payment_form_handler );', $wc_queued_js );
+		$this->assertStringContainsString( 'window.jQuery( document.body ).on( \'sv_wc_payment_form_handler_v6_1_5_loaded\', load_test_gateway_payment_form_handler );', $wc_queued_js );
 	}
 
 

tests/integration/payment-gateway/SV_WC_Payment_Gateway_Payment_Token_Test.php

@@ -1,11 +1,11 @@
 <?php
 
-use \SkyVerge\WooCommerce\PluginFramework\v6_1_4 as Framework;
+use \SkyVerge\WooCommerce\PluginFramework\v6_1_5 as Framework;
 
 /**
  * Tests for the payment token object
  *
- * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_4\SV_WC_Payment_Gateway_Payment_Token
+ * @see \SkyVerge\WooCommerce\PluginFramework\v6_1_5\SV_WC_Payment_Gateway_Payment_Token
  */
 class SV_WC_Payment_Gateway_Payment_Token_Test extends \Codeception\TestCase\WPTestCase {