Migrating to v6

This guide helps you upgrade your payment gateway plugin from v5.x.x to v6.0.0.

Dynamic Properties Management

Starting with v6.0.0, we've introduced a new way to handle dynamic properties on WooCommerce order objects to address PHP 8.2 deprecation warnings. This change is opt-in, meaning you can choose when to adopt the new approach. It is expected that the old method will be completely removed in a future version, so opting in ASAP is recommended.

Background

In PHP 8.2, setting dynamic properties on objects is deprecated. This affects how we store custom data on WooCommerce order objects. To future-proof our codebase, we've introduced a new Dynamic_Props class that provides a standardized way to handle these properties.

Opting In

By default, the framework continues to use the legacy approach (directly setting properties on order objects). To opt into the new approach add this code somewhere in your plugin:

add_filter( 'sv_wc_plugin_framework_use_dynamic_props_class', '__return_true' );

Required Changes

Once opted in, you'll need to update how you get and set dynamic properties on order objects. Here are the common properties that need updating:

Common Dynamic Properties on WC_Order objects

• customer_id
• payment
• payment_total
• description
• capture
• refund
• unique_transaction_ref

Before (Legacy Approach)

// Setting properties
$order->customer_id = $customer_id;
$order->payment = $payment_object;
$order->payment_total = $total;
$order->custom_prop = $custom_prop;

// Getting properties
$customer_id = $order->customer_id;
$payment = $order->payment;
$total = $order->payment_total;
$custom_prop = $order->custom_prop;

After (New Approach)

use SkyVerge\WooCommerce\PluginFramework\v6_0_0\Helpers\OrderHelper;

// Setting properties using OrderHelper.
OrderHelper::set_customer_id( $order, $customer_id );
OrderHelper::set_payment( $order, $payment_object );
OrderHelper::set_payment_total( $order, $total );
OrderHelper::set_property( $order, 'custom_prop', $custom_prop );

// Getting properties using OrderHelper.
$customer_id = OrderHelper::get_customer_id( $order );
$payment = OrderHelper::get_payment( $order );
$total = OrderHelper::get_payment_total( $order );
$custom_prop = OrderHelper::get_property( $order, 'custom_prop' );

// Alternative: Using Dynamic_Props directly (not recommended when working with order objects)
use SkyVerge\WooCommerce\PluginFramework\v6_0_0\Payment_Gateway\Dynamic_Props;

Dynamic_Props::set( $order, 'customer_id', $customer_id );
Dynamic_Props::get( $order, 'customer_id' );

As noted above: when working with an order object we recommend always using the OrderHelper class, as it provides an additional level of abstraction and will be more forwards-compatible.

Example

Here's a complete example of migrating a payment processing method:

// Before
public function process_payment( $order ) {
    $order->customer_id = $this->get_customer_id();
    $order->payment = new stdClass();
    $order->payment->token = $token;
    $amount = $order->payment_total;
  
    // ...
 }

// After
public function process_payment( $order ) {
    OrderHelper::set_customer_id( $order, $this->get_customer_id() );
    $payment = new stdClass();
    $payment->token = $token;
    OrderHelper::set_payment( $order, $payment );
    $amount = OrderHelper::get_payment_total( $order );
    
    // ...
}

Compatibility Notes

• This change is compatible with PHP 7.4 and above
• For PHP versions below 8.0, the framework automatically falls back to the legacy approach even when opted in
• The legacy approach will continue to work but will generate deprecation notices in PHP 8.2+

Additional Resources

• PR #786 - Full implementation details
• PHP 8.2 Dynamic Properties Documentation