OpenCart对接QuickBooks Desktop扩展报错：类QuickBooks_WebConnector_Handlers未找到

我购买了一款用于OpenCart的扩展，可将店铺与QuickBooks Desktop账户对接，该扩展通过搭建SOAP服务器实现与桌面端的通信及订单同步，但目前无法正常运行。

错误日志 #

[28-Feb-2023 17:19:24 America/Chicago] PHP Fatal error:  Uncaught Error: Class 'QuickBooks_WebConnector_Handlers' not found in /home/somesite/public_html/system/library/qbdt.php:48
Stack trace:
#0 /home/somesite/public_html/catalog/controller/account/qbdtwc.php(6): Qbdt->qbwc()
#1 /home/somesite/storage/modification/system/engine/action.php(79): ControllerAccountQbdtwc->index()
#2 /home/somesite/public_html/catalog/controller/startup/router.php(25): Action->execute(Object(Registry))
#3 /home/somesite/storage/modification/system/engine/action.php(79): ControllerStartupRouter->index()
#4 /home/somesite/storage/modification/system/engine/router.php(134): Action->execute(Object(Registry))
#5 /home/somesite/storage/modification/system/engine/router.php(123): Router->execute(Object(Action))
#6 /home/somesite/public_html/system/framework.php(169): Router->dispatch(Object(Action), Object(Action))
#7 /home/somesite/public_html/system/startup.php(104): require_once('/home/somesit...')
#8 /home/somesite/public_html/index.php(19): start('catalog')
#9 {main}
  thrown in /home/somesite/public_html/system/library/qbdt.php on line 48

qbdt.php前50行代码 #

<?php
class Qbdt {

    public function __construct($registry) {
        $this->db = $registry->get('db');
        $this->config = $registry->get('config');
        $this->log = $registry->get('log');
    }

    /**
    * SOAP endpoint for the Web Connector to connect to
    */
    public function qbwc() {
        require_once DIR_SYSTEM . '../QBDT/QuickBooks.php';

        $user = $this->config->get('module_opc_qbdt_app_user_name');

        $pass = $this->config->get('module_opc_qbdt_app_password');

        if (function_exists('date_default_timezone_set'))   {
            date_default_timezone_set($this->config->get('module_opc_qbdt_time_zone'));
        } else {
            date_default_timezone_set('America/New_York');
        }

        // Map QuickBooks actions to handler functions
        $map = array(
            QUICKBOOKS_ADD_DISCOUNTITEM => array( array( $this, '_addDiscountRequest' ), array( $this, '_addDiscountResponse' ) ),
            QUICKBOOKS_ADD_OTHERCHARGEITEM => array( array( $this, '_addOtherChargeRequest' ), array( $this, '_addOtherChargeResponse' ) ),
            QUICKBOOKS_ADD_ACCOUNT => array( array( $this, '_addAccountRequest' ), array( $this, '_addAccountResponse' ) ),
            QUICKBOOKS_ADD_CUSTOMER => array( array( $this, '_addCustomerRequest' ), array( $this, '_addCustomerResponse' ) ),
            QUICKBOOKS_MOD_CUSTOMER => array( array( $this, '_addCustomerRequest' ), array( $this, '_addCustomerResponse' ) ),
            QUICKBOOKS_DEL_LIST => array( array( $this, '_deleteListRequest' ), array( $this, '_deleteListResponse' ) ),
            QUICKBOOKS_ADD_INVENTORYITEM => array( array( $this, '_addProductRequest' ), array( $this, '_addProductResponse' ) ),
            QUICKBOOKS_MOD_INVENTORYITEM => array( array( $this, '_addProductRequest' ), array( $this, '_addProductResponse' ) ),
            QUICKBOOKS_ADD_SALESRECEIPT => array( array( $this, '_addSalesReceiptRequest' ), array( $this, '_addSalesReceiptResponse' ) ),
            QUICKBOOKS_IMPORT_CUSTOMER => array( array( $this, '_importCustomerRequest' ), array( $this, '_importCustomerResponse' ) ),
            QUICKBOOKS_IMPORT_ITEM => array( array( $this, '_importProductRequest' ), array( $this, '_importProductResponse' ) ),
        );

        // Catch all errors that QuickBooks throws with this function
        $errmap = array(
            '*' => array( $this, '_catchallErrors' ),
        );

        // Call this method whenever the Web Connector connects
        $hooks = array(
            QuickBooks_WebConnector_Handlers::HOOK_LOGINSUCCESS => array( array( $this, '_loginSuccess' ) ),    // Run this function whenever a successful login occurs
        );

排查方向及解决方案 #

• 检查QuickBooks SDK完整性：确认/home/somesite/public_html/QBDT/目录下存在完整的QuickBooks PHP SDK文件，特别是QuickBooks/WebConnector/Handlers.php（QuickBooks_WebConnector_Handlers类的定义文件）是否存在。仅引入QuickBooks.php可能不足以加载所有依赖类，部分SDK需要自动加载机制或手动引入子文件。
• 验证文件路径：确认require_once DIR_SYSTEM . '../QBDT/QuickBooks.php';的路径是否正确。DIR_SYSTEM对应OpenCart的system目录，../QBDT指向public_html根目录下的QBDT文件夹，需确认该路径存在且文件可被PHP读取。
• 补充手动引入：如果SDK未配置自动加载，可在require_once QuickBooks.php后添加一行代码，手动引入Handlers类文件：require_once DIR_SYSTEM . '../QBDT/QuickBooks/WebConnector/Handlers.php';
• 文件权限检查：确保QBDT目录权限为755，目录下文件权限为644，避免PHP因权限不足无法读取文件。
• 版本兼容性验证：检查扩展使用的QuickBooks SDK版本与服务器PHP版本是否兼容，PHP 7+可能对旧版SDK的语法存在兼容性问题，导致类加载失败。

内容的提问来源于stack exchange，提问作者Orange Rocket