Magento 2 Checkout Broken? Unpacking the Persistent PHP 8 TypeError in Shipping Rates

As an e-commerce migration expert at Shopping Mover, we frequently guide merchants through the complexities of upgrading their Magento 2 stores. A stable and seamless checkout process is the cornerstone of any successful online business. However, a subtle yet critical bug, particularly prevalent with PHP 8 and later, has been quietly disrupting this vital stage: a TypeError within Magento's shipping rate collection process.

This issue, recently highlighted in a Magento GitHub thread (magento/magento2#41182), exposes a vulnerability in the core Magento\Shipping\Model\Shipping::collectRates() method. If left unaddressed, it can lead to a completely broken checkout experience, frustrating customers and costing merchants valuable sales.

The Silent Killer: A TypeError in collectRates()

The problem arises when a Magento 2 instance has no shipping carriers configured or enabled. In such a scenario, the crucial line of code responsible for fetching carrier configurations:

$carriers = $this->_scopeConfig->getValue(
    'carriers',
    \Magento\Store\Model\ScopeInterface::SCOPE_STORE,
    $storeId
);

foreach ($carriers as $carrierCode => $carrierConfig) {

...encounters a critical flaw. The _scopeConfig->getValue('carriers', ...) call, instead of returning an empty array when no carriers are found, returns null. While older PHP versions might have silently ignored iterating over null or issued a warning, PHP 8 and its stricter type checking immediately throw a TypeError when a foreach loop attempts to iterate over a non-iterable type like null.

This means that if you've disabled all shipping methods (e.g., for a local pickup-only store, or during development/testing), your checkout page will simply crash with an error, preventing customers from completing their purchases.

Why Does This Happen? The Root Cause

The core of the problem lies in how Magento\Config\App\Config\Type\System::getDataByPathParts() behaves. When a requested configuration key (like 'carriers') is absent from the merged scope data, this method returns null. Since ScopeConfigInterface::getValue() is declared to return mixed, callers are expected to implement defensive programming – meaning they should anticipate and handle non-array return types gracefully.

The GitHub issue insightfully points out an asymmetry within the very same collectRates() method: a few lines below, the $limitCarrier branch already correctly normalizes its value with is_array() before iteration. This highlights an oversight where the same defensive check was not applied to the main carrier collection loop.

A Bug's Persistent Legacy: The 'Half-Fixed' Issue

What makes this particular bug even more noteworthy is its history. This isn't an entirely new problem; it's a recurrence, or rather, the remaining half of a defect reported back in 2021. Issue #30830 described an identical failure: disabling all shipping carrier modules led to a blank checkout and an array_keys(): argument #1 must be of type array, null given error.

That issue was supposedly fixed by #30822, which correctly guarded similar getValue('carriers', ...) call sites in Magento\Shipping\Model\Config::getActiveCarriers() and getAllCarriers(). However, the fix inexplicably omitted Shipping::collectRates(), leaving this critical method vulnerable to the same `TypeError` that persists today. This serves as a powerful reminder of the importance of comprehensive testing and thorough bug resolution in complex systems like Magento.

Impact on Merchants and the Customer Journey

• Broken Checkout: The most immediate and severe impact is a non-functional checkout page, leading to abandoned carts and lost sales.
• Poor User Experience: Customers encountering errors during checkout are likely to leave and not return, damaging brand reputation.
• Debugging Headaches: For developers, tracking down a TypeError in a core method can be time-consuming, especially if the root cause (null config value) isn't immediately obvious.
• Migration Risks: Stores upgrading to PHP 8 without this fix are at high risk of encountering this issue post-migration.

The Solution: Defensive Programming

The fix, as proposed in the associated pull request, is straightforward and follows best practices for defensive programming. It involves ensuring that the $carriers variable is an array before attempting to iterate over it. This can be achieved by:

• Checking with is_array(): Explicitly verifying if $carriers is an array before the foreach loop.
• Null Coalescing: Using the null coalescing operator (??) to default $carriers to an empty array if null is returned.

The proposed solution ensures that even if _scopeConfig->getValue() returns null, the foreach loop will safely iterate over an empty array, preventing the TypeError and allowing the rate collection to complete gracefully, returning no rates as expected.

Manual Testing Scenarios to Verify the Fix

To confirm your Magento instance is protected, you can perform these steps:

1. Disable all shipping carriers: Navigate to Stores > Configuration > Sales > Delivery Methods and disable every available shipping method. Alternatively, uninstall carrier modules if applicable.
2. Add a product to the cart: Proceed to the checkout page.
3. Observe the behavior:
   
   • Before the fix: You would likely encounter a TypeError: foreach() argument must be of type array|object, null given.
   • After the fix: Rate collection should complete without error, and the checkout page will display that no shipping methods are available, or proceed as expected if other methods are configured.

Shopping Mover's Take: Why This Matters for Your Magento Migration

At Shopping Mover, we emphasize that a successful Magento migration, especially to newer PHP versions like PHP 8, isn't just about moving data. It's about ensuring your store's core functionality remains robust and compatible with the latest technologies. Bugs like this TypeError underscore the importance of:

• Pre-migration Audits: Identifying potential compatibility issues and known bugs before they impact your live store.
• Thorough Testing: Comprehensive testing across all critical paths, including checkout, with various configurations (e.g., no carriers enabled).
• Proactive Patching: Applying official Magento patches and community-contributed fixes to maintain stability and security.
• Expert Guidance: Leveraging experienced Magento migration partners who understand the nuances of PHP compatibility and core Magento behavior.

This particular fix is crucial for any merchant running Magento 2 on PHP 8 or planning an upgrade. It prevents a silent but deadly error that can cripple your checkout and directly impact your bottom line.

Conclusion

The persistent TypeError in Magento\Shipping\Model\Shipping::collectRates() serves as a stark reminder that even in mature platforms like Magento, vigilance is key. For merchants and developers, understanding such issues and applying timely fixes is paramount to maintaining a healthy, high-performing e-commerce store. By adopting defensive coding practices and staying informed about critical updates, you can safeguard your checkout process and ensure a smooth experience for your customers.

If you're planning a Magento migration or struggling with PHP 8 compatibility issues, don't hesitate to reach out to the experts at Shopping Mover. We're here to help you navigate these challenges and ensure your e-commerce platform is robust, secure, and ready for the future.