PHP GoCardless Pro Uncaught Error Class GoCardlessPro\Client Not Found 해결 가이드

GoCardless Pro PHP 클라이언트 오류 이해하기

GoCardless는 글로벌 결제 시스템으로, 특히 자동 이체(direct debit)를 간편하게 구현할 수 있게 도와주는 강력한 API를 제공합니다. 그러나 많은 개발자들이 PHP에서 GoCardless Pro를 연동할 때 아래와 같은 치명적인 오류에 맞닥뜨리곤 합니다.

Uncaught Error: Class 'GoCardlessPro\Client' not found

이 오류는 PHP 프로젝트에서 GoCardlessPro\Client 클래스를 찾을 수 없을 때 발생합니다. 주로 컴포저(Composer) 설정, 오토로딩(autoloading), 네임스페이스(namespace) 문제, 또는 라이브러리 설치 누락 등으로 발생합니다.

Composer를 통한 GoCardless Pro 설치 점검

1. Composer 설치 여부 확인

GoCardless Pro PHP 라이브러리는 Composer 기반으로 관리됩니다. 먼저 Composer가 설치되어 있는지 확인해야 합니다.

composer --version

만약 설치되지 않았다면, Composer 공식 사이트에서 설치 후 재시도하세요.

2. GoCardless Pro 라이브러리 설치

GoCardless Pro는 Packagist에서 제공됩니다. 프로젝트 루트에서 아래 명령어를 실행해 설치하세요.

composer require gocardless/gocardless-pro

이 명령어는 vendor 디렉토리와 vendor/autoload.php 파일을 생성하며, GoCardlessPro\Client 클래스를 자동으로 로드할 수 있게 만듭니다.

반응형

Autoload 설정 및 네임스페이스 문제 해결

1. autoload.php 파일 불러오기

PHP 스크립트 상단에 반드시 아래와 같은 코드를 추가해야 Composer 오토로더가 작동합니다.

require_once __DIR__ . '/vendor/autoload.php';

만약 이 라인이 누락되면 아무리 라이브러리를 설치해도 PHP는 GoCardlessPro\Client 클래스를 인식하지 못합니다.

2. 네임스페이스 정확히 쓰기

GoCardless Pro의 Client 클래스를 사용할 때는 정확한 네임스페이스로 호출해야 합니다.

$client = new \GoCardlessPro\Client([
    'access_token' => 'your_access_token',
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);

주의: use 문 없이 바로 new GoCardlessPro\Client()처럼 작성하면 오동작할 수 있으니 네임스페이스를 반드시 명시하거나, use 구문을 추가하세요.

use GoCardlessPro\Client;

$client = new Client([
    'access_token' => 'your_access_token',
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);

반응형

PHP 환경과 버전 호환성 점검

GoCardless Pro PHP SDK는 최소 PHP 7.1 이상을 요구합니다. 프로젝트 서버의 PHP 버전을 점검하세요.

php -v

7.1 이하라면 PHP 업그레이드 또는 최신 LTS 버전 설치를 권장합니다.

실제 코드 예제 및 오류 방지 팁

예제 1: 올바른 클라이언트 생성

require_once __DIR__ . '/vendor/autoload.php';

use GoCardlessPro\Client;

$client = new Client([
    'access_token' => 'your_access_token',
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);

$customers = $client->customers()->list();
foreach ($customers->records as $customer) {
    echo $customer->given_name . "\n";
}

예제 2: try-catch로 에러 핸들링

try {
    $client = new \GoCardlessPro\Client([
        'access_token' => 'your_access_token',
        'environment' => \GoCardlessPro\Environment::LIVE
    ]);
    $payments = $client->payments()->list();
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

핵심 포인트: 항상 예외 처리를 통해 예상치 못한 오류를 잡아내고, 사용자에게 친절한 메시지를 제공하세요.

반응형

서버 배포 및 Composer Autoload 주의사항

1. vendor 폴더 배포 포함 여부

배포 서버에 vendor 폴더가 포함되지 않으면 런타임에서 클래스를 찾지 못합니다. 반드시 배포 파일에 vendor 폴더와 composer.lock 파일이 포함되었는지 확인하세요.

2. composer install 실행

만약 배포 서버에 vendor 폴더를 복사하지 않았다면, 배포 후 서버에서 아래 명령어로 설치를 진행하세요.

composer install --no-dev

php.ini와 확장 모듈 점검

PHP의 일부 확장 모듈(curl, mbstring, json 등)이 비활성화되어 있다면 GoCardless SDK가 일부 기능에서 작동하지 않을 수 있습니다. 아래 명령으로 현재 활성화된 모듈을 점검하세요.

php -m

필요한 모듈이 없으면 php.ini에서 활성화 후 Apache/Nginx를 재시작하세요.

반응형

 

마무리

이 오류는 단순히 라이브러리 설치 누락 또는 오토로딩 문제로 발생하는 경우가 많습니다. Composer를 제대로 설정하고 autoload.php를 불러오기만 해도 대부분의 문제는 해결됩니다.

핵심은 다음 세 가지입니다:

• Composer로 라이브러리 설치
• vendor/autoload.php 정확히 불러오기
• 네임스페이스 및 PHP 버전 호환성 체크

이 가이드를 따르면 더 이상 같은 오류로 시간을 허비하지 않고, GoCardless Pro API를 효율적으로 연동할 수 있을 것입니다.