Upgrade to Square PHP SDK v41.0.0

[jeffpaul]

Description

The Square PHP SDK has undergone a full rewrite in its latest version 41.0.0.20250220, introducing simplified classes and method names for improved usability. While previous versions remain functional, migrating to the latest SDK ensures that this extension remains compatible with future Square API updates and can take advantage of new features.

The extension is currently using SDK version 35.1.0.20240320, so an update is required to align with the latest SDK structure.

Why This Is Needed

• Ensures long-term compatibility with Square API updates.
• Simplifies codebase by adopting the new streamlined class and method names.
• Unlocks new features available only in SDK v41+.
• Future-proofing – Square's documentation suggests that new API enhancements will be built on this updated SDK structure.

Migration Steps

1. Upgrade the Square SDK via Composer

• Update composer.json to require the latest SDK version:

  "square/square-php-sdk": "^41.0.0"

• Run:

  composer update square/square-php-sdk

2. Refactor Code to Align with New SDK Structure

• Class Name Changes:
  • Update all instances where previous class names have changed.
  • Example: Square\Models\CreatePaymentRequest → Square\Payments\CreatePaymentRequest.
• Method Name Changes:
  • Adjust method calls to reflect new naming conventions.
• Error Handling Updates:
  • The new SDK introduces improved error-handling patterns—update exception handling accordingly.

3. Test Against WooCommerce Core & PHP Versions

• Ensure the extension functions correctly with:
  • WooCommerce latest versions
  • PHP 7.4, 8.0, 8.1, and 8.2
  • Square sandbox & production environments

4. Review & Validate Migration Using Square's Official Docs

• Follow the Square PHP SDK Migration Guide.
• Ensure that all deprecated methods are replaced with their recommended alternatives.

Next Steps & Considerations

• Confirm all necessary class/method refactors from v35 → v41.
• Run full regression testing on payments, refunds, and order sync flows.
• Ensure compatibility with other WooCommerce extensions, such as Subscriptions and Pre-Orders.
• Update documentation to reflect SDK changes for future maintenance.

[dkotter]

Looks like the latest version of this SDK only supports PHP 8.1+, so we would need to be comfortable bumping the minimum PHP version from 7.4 to 8.1 to support this.

While I love the idea of finally bumping that past 7.4, probably warrants more conversation on if this is worth the potential pain to existing merchants that aren't on 8.1 (and may not have the ability to update that, depending on their host) and if we do decide to do this, how best to handle those cases (the answer there may just be recommending those merchants stay on an older version of the extension)

[jeffpaul]

Assuming this work gets prioritized, or even perhaps as part of that decision, we'll likely want to find data on PHP version usage for both WooCommerce core and the Square extension to see just how large of a merchant base would be impacted by bumping to 8.1.

[yashhhYB]

Fantastic initiative! A good first step towards long-term compatibility and code simplification is upgrading to SDK v41. This update will significantly aid in streamlining future development and unlocking new features once the impact of the PHP version is assessed.

[ebinnion]

Given that WooCommerce publicly supports 7.4, and that there are ~25% of known sites using PHP version <= 7.4, I would suggest that we pause on this for now.

I'd rather not have an extension that has its own PHP version requirements, until we are actively having to choose between not adopting new features or breaking sites. Based on this issue, it doesn't seem like we're quite there yet.

[jeffpaul]

Noting that the Square PHP SDK has subsequently been updated recently to:

• Version 42.1.0.20250416 - 2025-04-16
• Version 42.2.0.20250521 - 2025-05-21
• Version 43.0.0.20250618 - 2025-06-18
• Version 43.0.1.20250716 - 2025-07-16
• Version 43.0.2.20250820 - 2025-08-20
• Version 43.0.3.20250820 - 2025-09-16
• Version 43.1.0.20250924 - 2025-10-07
• Version 43.1.1.20250924 - 2025-10-09
• Version 43.2.0.20251016 - 2025-10-16

[jeffpaul]

@darin perhaps worth identifying which of the newer SDK versions still supports PHP 7.4+ and getting the extension updated to that point such that we're as current as we're able and if a future issue arises that requires a newer SDK version we'll re-invigorate the PHP minimum discussion then?

[dkotter]

So we're currently on version 40.0.0.20250123 which is the last release before 41.0.0.20250220, which is the release that bumped the PHP version to 8.1+. So we are already as far up-to-date as we can be without bumping our minimum PHP version

[blogtutor]

Instead of everyone being "penalized" by PHP-update stragglers, how about using the newer SDK if the site is on 8.1+, and fall back to the current one if <8.1?

(I'm currently troubleshooting an intermittent INVALID_CARD_DATA issue, and I can't help but wonder if the newer SDK would help...)