PHPackages                             royfee/xshop - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. royfee/xshop

ActiveLibrary[API Development](/categories/api)

royfee/xshop
============

Multi-platform e-commerce SDK with unified API interface

3.0.0(1mo ago)04MITPHPPHP ^7.4|^8.0

Since May 30Pushed 1mo agoCompare

[ Source](https://github.com/royfee/Xshop)[ Packagist](https://packagist.org/packages/royfee/xshop)[ RSS](/packages/royfee-xshop/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (9)Versions (5)Used By (0)

Royfee XShop
============

[](#royfee-xshop)

多平台电商 SDK 统一封装库，支持拼多多、淘宝、京东等平台，提供统一的 API 接口和数据格式。

安装
--

[](#安装)

```
composer require royfee/xshop
```

快速开始
----

[](#快速开始)

```
use Royfee\XShop\XShop;

// 初始化
$xshop = new XShop(__DIR__ . '/config/xshop.php');

// 获取拼多多平台
$pdd = $xshop->pdd();

// 获取订单列表
$orders = $pdd->order()->getList(['page' => 1, 'page_size' => 20]);

// 获取商品列表
$goods = $pdd->goods()->getList(['page' => 1, 'page_size' => 10]);
```

核心特性
----

[](#核心特性)

- **统一接口**：所有平台订单/商品映射为 `XOrder`/`XGoods` 统一格式
- **集中配置**：单文件 `config/xshop.php` 管理所有平台配置
- **自定义 Logger**：支持 Monolog 或自定义日志适配器 (PSR-3)
- **自定义 Cache**：支持文件缓存或自定义缓存适配器 (PSR-16)
- **Token 缓存**：OAuth token 自动缓存，支持自动刷新
- **HTTP 独立**：封装 GuzzleHttp，支持自定义 HTTP 客户端
- **容器化**：惰性加载，按需实例化

目录结构
----

[](#目录结构)

```
src/
├── Contracts/     # 接口定义 (PSR-3, PSR-16, 自定义接口)
├── Data/          # 统一数据格式 (XOrder, XGoods)
├── Mapper/        # 映射基类
├── Http/          # HTTP 客户端
├── Cache/         # 缓存管理 (FileCache + 扩展指南)
├── Logger/        # 日志管理 (Monolog)
├── Container.php  # 服务容器
├── XShop.php      # 核心工厂类
└── Platforms/     # 各平台实现
    └── Pdd/       # 拼多多平台

```

自定义缓存适配器
--------

[](#自定义缓存适配器)

本包内置 `FileCache` 作为默认缓存。生产环境建议自定义缓存适配器。

### 要求

[](#要求)

自定义缓存必须实现 **PSR-16** `Psr\SimpleCache\CacheInterface` 接口。

### ThinkPHP 示例

[](#thinkphp-示例)

```
// 1. 创建适配器
namespace app\common\cache;

use Psr\SimpleCache\CacheInterface;
use think\facade\Cache as ThinkCache;

class ThinkCacheAdapter implements CacheInterface
{
    protected $prefix = 'xshop_';

    public function get($key, $default = null) {
        return ThinkCache::get($this->prefix . $key, $default);
    }

    public function set($key, $value, $ttl = null) {
        return ThinkCache::set($this->prefix . $key, $value, $ttl);
    }

    // ... 其他 PSR-16 方法
}

// 2. 使用
use app\common\cache\ThinkCacheAdapter;

$xshop = new XShop([
    'cache' => [
        'handler' => new ThinkCacheAdapter(),  // 传入实例
    ],
    // ... 其他配置
]);
```

### Laravel 示例

[](#laravel-示例)

```
namespace App\Services;

use Psr\SimpleCache\CacheInterface;
use Illuminate\Support\Facades\Cache;

class XShopCacheAdapter implements CacheInterface
{
    protected $prefix = 'xshop_';

    public function get($key, $default = null) {
        return Cache::get($this->prefix . $key, $default);
    }

    public function set($key, $value, $ttl = null) {
        return Cache::put($this->prefix . $key, $value, $ttl);
    }

    // ... 其他 PSR-16 方法
}
```

### 数据库缓存示例 (与店铺表关联)

[](#数据库缓存示例-与店铺表关联)

```
class DbCacheAdapter implements CacheInterface
{
    protected $pdo;
    protected $prefix = 'xshop_';

    public function __construct(PDO $pdo) {
        $this->pdo = $pdo;
    }

    public function get($key, $default = null) {
        $row = $this->pdo->prepare("SELECT cache_value FROM xshop_tokens
            WHERE cache_key = ? AND expire_at > ?")
            ->execute([$this->prefix . $key, time()])
            ->fetchColumn();
        return $row ? unserialize($row) : $default;
    }

    public function set($key, $value, $ttl = null) {
        // 保存 token，同步更新店铺表
        // ...
    }

    // ... 其他 PSR-16 方法
}
```

多店铺支持
-----

[](#多店铺支持)

单个应用可授权多个拼多多店铺，通过 `mall_id` 区分：

```
// 授权 (mall_id 从响应中获取)
$pdd = $xshop->pdd();
$token = $pdd->auth()->getToken('code_here');
$mallId = $token['owner_id'];  // "4567890"

// 后续调用指定店铺
$shopA = $xshop->pdd(['mall_id' => '4567890']);
$shopB = $xshop->pdd(['mall_id' => '7890123']);

$ordersA = $shopA->order()->getList(['page' => 1]);
$ordersB = $shopB->order()->getList(['page' => 1]);
```

扩展新平台
-----

[](#扩展新平台)

1. 实现 `PlatformInterface`
2. 实现 `AuthInterface`、`OrderInterface`、`GoodsInterface`
3. 创建 Mapper 继承 `AbstractMapper`
4. 注册平台：`XShop::registerPlatform('new_platform', NewPlatform::class)`

License
-------

[](#license)

MIT

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance94

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Total

4

Last Release

32d ago

Major Versions

1.0.0 → 2.0.02026-06-18

2.1.0 → 3.0.02026-06-22

### Community

Maintainers

![](https://www.gravatar.com/avatar/307712905420580e4db4c492c8ca3b3c464346a375e1fbd280f5e6368149f5c0?d=identicon)[royfee](/maintainers/royfee)

---

Top Contributors

[![royfee](https://avatars.githubusercontent.com/u/49356467?v=4)](https://github.com/royfee "royfee (5 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/royfee-xshop/health.svg)

```
[![Health](https://phpackages.com/badges/royfee-xshop/health.svg)](https://phpackages.com/packages/royfee-xshop)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.8k543.8M20.5k](/packages/laravel-framework)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k16](/packages/tempest-framework)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k46](/packages/civicrm-civicrm-core)[oro/platform

Business Application Platform (BAP)

645143.5k116](/packages/oro-platform)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M600](/packages/shopware-core)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k38.9k](/packages/matomo-matomo)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)