Laravel Xsolla支付集成演示
一个为艾克索拉支付提供商集成准备的完整Laravel 11.x应用程序，运行在Docker中。
特性
- Laravel 11.x与PHP 8.4
- Docker编写设置（PHP-FPM、Nginx、MySQL、Redis）
- Laravel Breeze身份验证
- 完整的支付基础设施（订单、交易、控制者）
- 用于商店、结账和订单管理的前端页面
- 已准备好与艾克索拉集成
技术栈
- 拉瑞维尔：11.x
- PHP：晚上8点4分
- 数据库：MySQL 8.0
- 缓存：Redis
- Web服务器：Nginx
- 前端：带有Tailwind CSS的叶片模板
- 认证：Laravel微风
项目结构
├── app/
│ ├── Http/Controllers/
│ │ ├── OrderController.php # Order management
│ │ └── PaymentController.php # Payment handling & Xsolla integration
│ └── Models/
│ ├── Order.php # Order model
│ └── Transaction.php # Transaction model
├── database/
│ └── migrations/
│ ├── *_create_orders_table.php # Orders schema
│ └── *_create_transactions_table.php # Transactions schema
├── resources/views/
│ ├── shop/
│ │ └── index.blade.php # Products/shop page
│ ├── orders/
│ │ ├── index.blade.php # User orders list
│ │ └── show.blade.php # Order details
│ └── payment/
│ ├── checkout.blade.php # Checkout page (Xsolla widget here)
│ ├── success.blade.php # Payment success
│ └── cancel.blade.php # Payment cancelled
├── routes/
│ └── web.php # All routes including webhook
├── docker/
│ ├── nginx/
│ │ └── nginx.conf # Nginx configuration
│ └── php/
│ └── local.ini # PHP configuration
├── docker-compose.yml # Docker services
└── Dockerfile # PHP container build
入门指南
先决条件
- Docker&Docker编写
- Git
安装
- 克隆存储库 （如果你还没有）：
git clone
cd xsolla_mcp- 启动Docker容器:
docker-compose up -d- 检查集装箱状态:
docker-compose ps所有容器都应“打开”且健康。
- 运行数据库迁移:
docker-compose exec app php artisan migrate- 构建前端资产 （如果尚未建成）：
docker-compose exec app npm install
docker-compose exec app npm run build- 访问应用程序:
- 应用：http://localhost:8000 - MySQL：本地主机：3307 - Redis：本地主机：6380
创建用户
在以下网址注册新用户：http://localhost:8000/register
可用路线
公共路线
/-欢迎页面/register-用户注册/login-用户登录
经过身份验证的路由
/dashboard-用户仪表板/shop-产品/店铺页面/orders-用户订单列表/orders/{order}-订单详情/payment/checkout/{order}-结账页面/payment/success-付款成功回访/payment/cancel-付款取消回拨
API路线
POST /webhook/xsolla-艾克索拉webhook端点（公共，无身份验证）
数据库模式
订单表
id-主键user_id-用户外键order_number-唯一订单标识符total_amount-订单总额currency-货币代码（美元、欧元等）status-订单状态（待定、正在处理、已完成、失败、已取消）description-订单描述items-订单项的JSON数组customer_email-客户电子邮件notes-附加说明completed_at-完成时间戳created_at,updated_at-时间戳
交易记录表
id-主键order_id-订单的外键transaction_id-来自支付提供商的外部交易IDprovider-支付提供商名称（xsolla）amount-交易金额currency-货币代码status-交易状态（待定、正在处理、已完成、失败、已退款、已取消）payment_method-使用的付款方式metadata-来自提供者的JSON元数据error_message-如果失败，则显示错误消息customer_email-客户电子邮件processed_at-处理时间戳created_at,updated_at-时间戳
艾克索拉集成指南
该应用程序已为艾克索拉集成做好准备。按照以下步骤完成集成：
1.在艾克索拉注册
- 注册地址： 艾克索拉发行商帐户
- 创建新项目
- 得到你的 商户编号 和 API密钥
2.将艾克索拉凭据添加到环境中
添加到您的 .env 文件：
XSOLLA_MERCHANT_ID=your_merchant_id
XSOLLA_API_KEY=your_api_key
XSOLLA_PROJECT_ID=your_project_id
XSOLLA_MODE=sandbox # or 'live' for production3.安装艾克索拉SDK（可选）
您可以使用Xsolla的PHP SDK或直接与他们的API集成：
docker-compose exec app composer require xsolla/xsolla-sdk-php4.更新PaymentController
在 app/Http/Controllers/PaymentController.php:
初始化付款 (initiate PaymentController.php中的方法：35）：
- 调用Xsolla API创建支付令牌
- 将令牌返回到前端
- 使用令牌初始化艾克索拉小部件
手柄Webhook (webhook PaymentController.php中的方法：67）：
- 验证艾克索拉签名
- 解析webhook负载
- 更新订单和交易状态
- 返回适当的响应
5.更新结账页面
在 resources/views/payment/checkout.blade.php:
添加艾克索拉JavaScript SDK：
初始化小部件（替换checkout.blade.php:70处的占位符代码）：
function initiatePayment() {
fetch("{{ route('payment.initiate', $order) }}", {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-CSRF-TOKEN': '{{ csrf_token() }}'
}
})
.then(response => response.json())
.then(data => {
// Initialize Xsolla widget with token
XPayStationWidget.init({
access_token: data.access_token,
sandbox: true, // false for production
lightbox: {
spinner: 'round',
spinnerColor: '#cccccc'
}
});
XPayStationWidget.open();
});
}6.配置艾克索拉Webhooks
在您的艾克索拉发行商帐户中：
- 转到项目设置→ 网络钩子
- 设置Webhook URL:
https://yourdomain.com/webhook/xsolla - 启用webhook事件：
- 支付 - 退款 - 用户验证（可选）
7.测试集成
- 使用艾克索拉的沙盒模式进行测试
- 使用测试卡测试支付流程
- 验证webhook接收和处理
- 检查订单和交易状态更新
Docker命令
启动容器
docker-compose up -d停止集装箱
docker-compose down查看日志
docker-compose logs -f app
docker-compose logs -f nginx
docker-compose logs -f mysql在容器中执行命令
# Artisan commands
docker-compose exec app php artisan migrate
docker-compose exec app php artisan tinker
# Composer
docker-compose exec app composer install
docker-compose exec app composer update
# NPM
docker-compose exec app npm install
docker-compose exec app npm run dev
docker-compose exec app npm run build检修容器外壳
docker-compose exec app sh重建容器
docker-compose up -d --build开发工作流程
- 进行代码更改 在本地文件中
- 更改会自动反映出来 由于批量安装
- 查看更改：只需刷新浏览器
- 对于后端更改：如果需要，清除缓存：
docker-compose exec app php artisan cache:clear
docker-compose exec app php artisan config:clear
docker-compose exec app php artisan route:clear- 对于前端资产：重建：
docker-compose exec app npm run build测试应用程序
1.注册/登录
访问http://localhost:8000/register创建帐户
2.浏览店铺
引导到http://localhost:8000/shop查看可用产品
3.创建订单
点击任何产品上的“立即购买”以创建订单
4.查看订单
查看您的订单http://localhost:8000/orders
5.测试检查流程
点击“立即付款”或“继续付款”查看结账页面
环境变量
关键环境变量 .env:
APP_NAME="Xsolla Payment Demo"
APP_URL=http://localhost:8000
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret
REDIS_HOST=redis
REDIS_PORT=6379
CACHE_STORE=redis故障排除
容器未启动
docker-compose down
docker-compose up -d --build数据库连接错误
# Check MySQL is ready
docker-compose exec mysql mysql -ularavel -psecret -e "SELECT 1"
# Wait for MySQL to be fully ready
docker-compose exec app php artisan migrate权限错误
docker-compose exec app chmod -R 777 storage bootstrap/cache前端资产未加载
docker-compose exec app npm install
docker-compose exec app npm run build清除所有缓存
docker-compose exec app php artisan optimize:clear项目亮点
- Docker化：完全容器化，跨环境一致
- 生产就绪结构：订单、交易、适当的关系
- 安全：CSRF保护、身份验证、webhook签名验证就绪
- 可扩展的：Redis缓存，队列支持就绪
- 组织良好MVC模式，明确的关注点分离
后续步骤
- 实施艾克索拉集成：遵循上面的集成指南
- 添加产品管理：为产品创建管理面板
- 加强订单管理：添加订单取消、退款
- 实施电子邮件通知：订单确认、收据
- 添加测试：编写单元和功能测试
- 部署到生产：配置正确的域、SSL等。
支持
对于Laravel文档：https://laravel.com/docs 艾克索拉文档：https://developers.xsolla.com/
许可证
该项目是根据麻省理工学院许可证授权的开源软件。