Stripe PHP: Thư Viện SDK Thanh Toán Chính Thức
/stripe-php
Stripe PHP là thư viện SDK chính thức của Stripe, phân phối dưới dạng gói Composer để gọi Stripe API từ các ứng dụng PHP, với các class resource tự dựng từ chính dữ liệu phản hồi của API. Thư viện lo sẵn việc tự động thử lại, cấu hình timeout, và TLS. Hãy chọn nó nếu dự án đã dùng Composer và muốn có hỗ trợ chính thức từ Stripe; bỏ qua nếu bạn cần một stack HTTP không dùng cURL, vì mặc định thư viện phụ thuộc vào cURL.
Stripe PHP Là Gì?
Stripe PHP là SDK chính thức mà Stripe phát hành cho API thanh toán của mình dành cho PHP, phân phối dưới dạng gói Composer stripe/stripe-php. Thư viện đi kèm sẵn các class resource cho những đối tượng như customer và charge, tự khởi tạo động từ bất kỳ dữ liệu nào API trả về. Cả kiểu client/service hiện đại lẫn kiểu gọi tĩnh cũ trước phiên bản 7.33.0 đều được hỗ trợ song song.
Cài Đặt Và Yêu Cầu Hệ Thống
Stripe PHP yêu cầu PHP 7.2.0 trở lên, và theo chính sách hỗ trợ phiên bản ngôn ngữ của Stripe thì hỗ trợ cho PHP 7.2 và 7.3 sẽ sớm bị gỡ bỏ, nên nâng cấp runtime trước là việc nên làm. Cách cài đặt chính là qua Composer: chạy `composer require stripe/stripe-php`, sau đó nạp thư viện qua autoloader của Composer bằng `require_once 'vendor/autoload.php';`. Nếu không dùng Composer, có thể tải bản release mới nhất từ GitHub và include trực tiếp file `init.php`. Cần có ba extension PHP để các binding hoạt động đúng: curl (dù bạn có thể thay bằng client HTTP không dùng cURL của riêng mình), json, và mbstring; cài qua Composer thì các extension này được xử lý tự động, còn cài thủ công thì phải tự kiểm tra. Ai còn dùng PHP 5.4 hoặc 5.5 (đều đã hết vòng đời) có thể dùng tạm stripe-php v6.43.1, còn PHP 5.3 (cũng đã hết vòng đời) có thể dùng v5.9.2, dù cả hai bản cũ đều không có các tính năng API mới.
Bắt Đầu Với Stripe PHP
Cách tích hợp tối thiểu là khởi tạo một StripeClient với secret key rồi gọi một phương thức trên resource, ví dụ tạo customer với description, email, và payment_method rồi echo đối tượng trả về. Code mới nên dùng kiểu client/service này; thư viện vẫn hỗ trợ cách gọi tĩnh kiểu cũ trước phiên bản 7.33.0 cho những dự án chưa chuyển đổi, kèm hướng dẫn migrate được dẫn link từ wiki của dự án. Sau lần gọi đầu tiên, `getLastResponse()` trên bất kỳ đối tượng trả về nào sẽ lộ ra response gốc, gồm cả header như Request-Id, hữu ích khi bạn cần debug cùng đội hỗ trợ của Stripe.
Tính Năng Chính Và Cấu Hình Nâng Cao
- ✓Timeout của CurlClient có thể cấu hình: setTimeout() và setConnectTimeout() ghi đè các hằng số DEFAULT_TIMEOUT và DEFAULT_CONNECT_TIMEOUT mặc định của thư viện.
- ✓Tuỳ chỉnh option cURL, kể cả CURLOPT_PROXY, truyền thẳng vào constructor của CurlClient để định tuyến request qua proxy.
- ✓Tự động thử lại qua setMaxNetworkRetries(), kèm idempotency key gắn vào các request được thử lại để tránh tạo trùng một charge sau khi timeout.
- ✓Ghi đè API key và tài khoản Stripe theo từng request, dành cho các nền tảng kiểu Stripe Connect cần đổi thông tin xác thực giữa chừng.
- ✓Hook logger tương thích PSR-3 qua setLogger(), nhờ đó message request và response có thể được đưa tới nơi khác thay vì error_log mặc định của PHP.
- ✓rawRequest() trên StripeClient, có từ phiên bản 16 của SDK, dùng để gọi các endpoint chưa tài liệu hoá hoặc đang private-beta mà các class có sẵn chưa hỗ trợ.
- ✓Các bản package public preview và private preview được gắn hậu tố -beta.X và -alpha.X, cài được bằng cách ghim đúng phiên bản trong composer.json.
- ✓setCABundlePath() để dùng bundle chứng chỉ CA của riêng bạn thay vì bundle mặc định đi kèm thư viện.
Điểm mạnh
- ✓Các class resource tự khởi tạo từ bất kỳ dữ liệu nào API trả về, nên cùng đoạn code client vẫn chạy được khi Stripe API thay đổi.
- ✓Idempotency key được tự động gắn vào các request thử lại khi đã bật setMaxNetworkRetries(), giảm rủi ro tính phí trùng khách hàng sau một lần timeout.
- ✓Cả cách cài qua Composer lẫn cài thủ công đều được tài liệu hoá, cộng thêm phương án dự phòng rõ ràng cho ai còn kẹt ở bản PHP đã hết vòng đời.
- ✓Giấy phép MIT, không vướng ràng buộc copyleft khi nhúng vào sản phẩm PHP thương mại.
- ✓rawRequest() cho một lối thoát tới các endpoint chưa tài liệu hoá hoặc đang preview mà không cần fork thư viện hay chờ bản release mới.
Hỗ Trợ Phiên Bản Và Vấn Đề Đã Biết
- △README hiện nói đóng góp từ người đóng góp lần đầu đang tạm dừng, nên người mới được hướng dẫn mở issue thay vì gửi pull request.
- △Hỗ trợ cho PHP 7.2 và 7.3 sắp bị gỡ bỏ theo chính sách phiên bản ngôn ngữ của Stripe, và README nói các phiên bản major sau này sẽ tiếp tục bỏ các bản PHP cũ, nên việc ghim vào một runtime cũ có hạn sử dụng.
- △Giao thức HTTP mặc định là cURL; về mặt kỹ thuật có hỗ trợ client không dùng cURL nhưng README không trình bày ví dụ cụ thể, nên bạn phải tự lo phần đó.
- △Mặc định thư viện gửi telemetry về độ trễ request và mức dùng tính năng cho Stripe; chỉ cần một dòng setEnableTelemetry(false) để tắt, nhưng dễ bị bỏ sót là nó đang bật sẵn.
- △Các phiên bản package public/private preview (-beta.X, -alpha.X) có thể có breaking change giữa hai bản preview mà không tăng major version, nên cần ghim đúng phiên bản nếu dùng.
- △Ai còn dùng PHP 5.3, 5.4, hoặc 5.5 sẽ bị kẹt ở các bản stripe-php đã cũ nhiều năm (v5.9.2, v6.43.1), không có các tính năng API mới.
Thư Viện Này Dành Cho Ai?
Stripe PHP phù hợp với các đội PHP đã dùng Composer và cần nhận thanh toán, quản lý subscription, hoặc dùng Stripe Connect mà không muốn tự viết client HTTP gọi thẳng Stripe API. Đây là lựa chọn hợp lý cho đội coi trọng hỗ trợ chính thức từ nhà cung cấp và các đối tượng resource định kiểu rõ ràng hơn là tự xây một wrapper mỏng. Nó không hợp nếu bạn còn kẹt ở PHP dưới 7.2, cần môi trường runtime không có cURL, hoặc muốn một lớp trừu tượng thanh toán không gắn chặt với hình dạng API của riêng một nhà cung cấp.
Cân Nhắc Các Lựa Chọn Tích Hợp Thanh Toán Khác
Câu Hỏi Thường Gặp
Stripe PHP library yêu cầu PHP 7.2.0 trở lên. Chính sách hỗ trợ phiên bản ngôn ngữ của Stripe nói hỗ trợ cho PHP 7.2 và 7.3 sẽ sớm bị gỡ bỏ, và các phiên bản khác sẽ tiếp tục bị bỏ ở các bản major sau này, nên cập nhật thường xuyên sẽ tránh mất quyền nhận bản vá.
Cách chuẩn là qua Composer: chạy composer require stripe/stripe-php, rồi nạp qua require_once 'vendor/autoload.php'. Nếu không dùng Composer, hãy tải bản release mới nhất từ GitHub và include trực tiếp file init.php.
Stripe PHP library cần các extension curl, json, và mbstring để hoạt động đúng, dù client HTTP không dùng cURL có thể thay thế cho curl nếu muốn. Cài qua Composer thì các extension này tự động có sẵn; cài thủ công thì cần tự kiểm tra.
Tạo một thực thể Stripe\HttpClient\CurlClient, gọi setTimeout() và setConnectTimeout() để ghi đè giá trị mặc định, hoặc truyền một mảng CURLOPT_* (ví dụ để dùng proxy) vào constructor, rồi đăng ký nó qua Stripe\ApiRequestor::setHttpClient().
Stripe PHP library mặc định gửi telemetry về độ trễ request và mức dùng tính năng cho Stripe, nhưng bạn có thể tắt bằng một lệnh gọi setEnableTelemetry(false).
Stripe PHP library là mã nguồn mở, phát hành theo giấy phép MIT, và được lưu trữ công khai trên GitHub tại stripe/stripe-php.
Vấn đề Stripe PHP giải quyết
Gọi thẳng Stripe API từ PHP nghĩa là phải tự dựng request cURL, tự phân tích response JSON, và tự viết lại logic thử lại cùng idempotency, còn các bản Linux cũ như CentOS hay RHEL khiến việc này rắc rối hơn vì chúng có thể mặc định dùng TLS 1.0/1.1 dù đã cài TLS 1.2, điều mà Stripe API giờ từ chối. Thư viện stripe-php bọc lớp HTTP đó bằng các class resource tự phân tích chính mình, một CurlClient có thể cấu hình với tự động thử lại, và idempotency key được gắn tự động vào các request thử lại, nên nhà phát triển PHP không phải dựng lại cùng một lớp hạ tầng cho từng dự án.
Trường hợp sử dụng tốt nhất
- •Tính phí thẻ và tạo customer từ backend PHP bằng các class resource định kiểu thay vì tự phân tích response API.
- •Vận hành một nền tảng Stripe Connect cần chuyển đổi giữa nhiều tài khoản kết nối và API key theo từng request.
- •Tích hợp Stripe vào plugin WordPress hoặc Laravel, dùng setAppInfo() để định danh plugin với Stripe đúng như README khuyến nghị cho nhà phát triển plugin.
- •Thử sớm một tính năng Stripe đang phát triển bằng cách ghim phiên bản preview -beta.X hoặc -alpha.X.
- •Gọi một endpoint chưa tài liệu hoá hoặc đang private-beta của Stripe qua rawRequest() mà không cần chờ các class SDK định kiểu theo kịp.
Repo liên quan
stripe-php có đáng để bạn bỏ thời gian?
ChatGPT, Claude và Perplexity đều đọc được trang này. Hỏi thử xem họ nghĩ gì về stripe-php.