magneticengine-sdk-php

🚀 磁力引擎开放平台 PHP SDK - 为 PHP 开发者提供完整的磁力引擎 API 集成解决方案

📖 概述

在技术蓬勃发展的当下，磁力引擎开放平台的 Marketing API SDK，本应是普惠所有开发者的得力工具，涵盖磁力引擎、磁力金牛、磁力聚星、短剧相关功能，从 Token 获取到请求封装、响应解释，每个环节都暗藏助力高效开发的玄机。

其本地化设计，理应为开发者开辟便捷通道，无论经验如何，都能借它在 API 调用之路上畅行无阻。可现实却令人咋舌，面对 PHP 这片高手云集、活力满满的领域，官方竟然缺失 PHP 版本的 SDK！

这简直荒谬至极。PHP 开发者们为互联网立下汗马功劳，如今却像被抛弃的孩子。看着其他语言开发者仗着官方 SDK 大步快跑，自己只能徒手在荆棘中挣扎，太不公平！好比马拉松赛场，别人装备精良、补给充足，自己却赤脚前行、无水可饮。

幸有补救性 SDK，让 PHP 开发者不至于掉队，能凭本事搭起投放管理系统，但背后是他们付出的诸多额外心血。官方这种"偏心"做法，实在该反省，给 PHP 开发者们一个交代！

✨ 特性

🎯 完整覆盖：支持磁力引擎、磁力金牛、磁力聚星、短剧等全平台 API
⚡ 高性能：基于 GuzzleHttp，支持连接复用和智能重试
🧠 运行时自适配：自动识别 FPM/CLI/Swoole 运行环境并调整连接复用策略
🔧 易配置：支持环境变量、配置文件等多种配置方式
🛡️ 强健性：内置错误处理、重试机制、频控处理
📚 文档完善：提供接口对照文档、测试目录说明和示例代码
🔄 现代化：支持 PHP 8.0+，使用现代 PHP 特性

🚀 快速开始

环境要求

PHP >= 8.0
GuzzleHttp 7.0+（自动安装）
推荐使用 Composer 安装依赖

安装

composer require westng/magneticengine-sdk-php

基础使用

<?php

use Core\Exception\MagneticEngineException;
use MagneticEngineSDK\MagneticEngineClient;

$client = new MagneticEngineClient('your_access_token');

$client->setRetryConfig(
    maxRetries: 3,
    retryDelay: 1000,
    enableRetry: true
);

$client->setVerify(true);

try {
    $response = $client->MagneticEngine()
        ->Advertiser
        ->V1AdvertiserInfo()
        ->setParams([
            'advertiser_id' => 123456789,
        ])
        ->send();

    $data = json_decode($response->getBody(), true);
    print_r($data);
} catch (MagneticEngineException $e) {
    echo "错误类型: {$e->getErrorType()}\n";
    echo "错误码: {$e->getErrorCode()}\n";
    echo "错误信息: {$e->getErrorMessage()}\n";
}

📋 使用条件

运行环境自适配

默认 auto：自动识别 fpm、cli、swoole
在 Swoole 协程环境下默认关闭全局 Client 池复用，降低长驻进程下的跨请求复用风险
可通过 Core\Http\HttpRequest::setRuntimeMode('fpm|cli|swoole|auto') 手动覆盖
也可通过环境变量 MAGNETICENGINE_RUNTIME_MODE 指定运行模式

开发者条件

使用 SDK 需要首先注册成为磁力引擎开发者，请参考开发者平台
使用 SDK 需要先拥有 API 的访问权限，所有 SDK 的使用与应用拥有的权限组相关联

📁 项目结构

magneticengine-sdk-php/
├── 📚 docs/                                    # 接口对照文档
│   ├── magnetic-engine.md                      # 磁力引擎接口对照
│   ├── magnetic-jinniu.md                      # 磁力金牛接口对照
│   ├── magnetic-juxing.md                      # 磁力聚星接口对照
│   └── magnetic-shortdrama.md                  # 短剧接口对照
├── 🔧 src/                                     # 源代码
│   ├── Oauth/                                  # OAuth 认证
│   │   ├── GetAccessToken.php                  # 获取 token
│   │   └── RefreshToken.php                    # 刷新 token
│   ├── Core/                                   # 核心包
│   │   ├── Autoloader/                         # 自动加载器
│   │   ├── Exception/                          # 异常处理
│   │   ├── Helper/                             # 助手函数
│   │   ├── Http/                               # HTTP 请求
│   │   └── Profile/                            # 客户端、鉴权、请求基座
│   └── Api/                                    # API 模块
│       ├── MagneticEngine/                     # 磁力引擎
│       ├── MagneticJinniu/                     # 磁力金牛
│       ├── MagneticJuxing/                     # 磁力聚星
│       └── MagneticShortDrama/                 # 短剧
├── 🧪 tests/                                   # 测试文件
│   ├── Unit/                                   # 单元测试
│   ├── Integration/                            # 业务接口测试
│   ├── Mock/                                   # mock 资源
│   ├── TestCase.php                            # 测试基座
│   ├── bootstrap.php                           # 测试启动文件
│   └── README.md                               # 测试目录说明
├── 📄 .env.example                             # 环境变量示例
├── 📄 composer.json                            # Composer 配置
├── 📄 LICENSE                                  # 开源协议
├── 📄 phpunit.xml.dist                         # PHPUnit 配置
├── 📄 README.md                                # 项目说明
└── 📄 index.php                                # SDK 入口

📚 详细使用指南

1. 用户授权（获取 Access Token）

获取授权 URL

参数	说明	默认值	示例值
`cb_url`	回调链接	-	`https://xxx.xxx.xxx/callback`
`scope`	授权范围	-	`account_service,report_service`
`state`	自定义参数	`your_custom_params`	`auth_state`
`oauth_type`	授权类型	空字符串	`authorized`

<?php

use MagneticEngineSDK\MagneticEngineAuth;

$auth = new MagneticEngineAuth(APP_ID, APP_SECRET);
$url = $auth->getAuthCodeUrl(
    CALLBACK_URL,
    ['account_service', 'report_service'],
    'auth_state',
    'authorized'
);

echo "授权链接: {$url}";

获取 Access Token

<?php

use MagneticEngineSDK\MagneticEngineAuth;

$auth = new MagneticEngineAuth(APP_ID, APP_SECRET);

$tokenData = $auth->getAccessToken($authCode);
$newTokenData = $auth->refreshToken($refreshToken);

2. API 调用

配置重试机制

参数	说明	默认值	示例值
`maxRetries`	最大重试次数	`3`	`5`
`retryDelay`	重试延迟（毫秒）	`1000`	`2000`
`retryableStatusCodes`	可重试 HTTP 状态码	`[408, 429, 500, 502, 503, 504]`	`[408, 429, 500]`
`enableRetry`	是否启用重试	`true`	`false`
`retryableBusinessCodes`	可重试业务错误码	`[40100, 40110, 50000]`	`[40100, 50000]`

<?php

use MagneticEngineSDK\MagneticEngineClient;

$client = new MagneticEngineClient(TOKEN);

$client->setRetryConfig(
    maxRetries: 3,
    retryDelay: 1000,
    retryableStatusCodes: [408, 429, 500, 502, 503, 504],
    enableRetry: true,
    retryableBusinessCodes: [40100, 40110, 50000]
);

$client->setRetryEnabled(true);
$client->setRetryEnabled(false);

说明：重试与超时配置只作用于当前 MagneticEngineClient 实例，多实例并发互不影响。

配置 TLS 证书校验

方法参数	说明	示例
`enabled`	是否启用证书校验	`true` / `false`
`caPath`	CA 证书路径（仅 `enabled=true` 时生效）	`/etc/ssl/custom-ca.pem`

<?php

use MagneticEngineSDK\MagneticEngineClient;

$client = new MagneticEngineClient(TOKEN);

$client->setVerify(false);
$client->setVerify(true);
$client->setVerify(true, '/etc/ssl/custom-ca.pem');

说明：

当前默认值为 true，默认使用系统 CA 进行证书校验
仅在明确需要兼容历史环境时再关闭证书校验，避免中间人攻击风险

获取广告主信息

<?php

use Core\Exception\MagneticEngineException;
use MagneticEngineSDK\MagneticEngineClient;

try {
    $client = new MagneticEngineClient(TOKEN);

    $response = $client->MagneticEngine()
        ->Advertiser
        ->V1AdvertiserInfo()
        ->setParams([
            'advertiser_id' => 123456789,
        ])
        ->send();

    $data = json_decode($response->getBody(), true);
    print_r($data);
} catch (MagneticEngineException $e) {
    echo "错误类型: {$e->getErrorType()}\n";
    echo "错误码: {$e->getErrorCode()}\n";
    echo "错误信息: {$e->getErrorMessage()}\n";
}

🔧 配置说明

环境变量配置

创建 .env 文件：

# 应用配置
APP_ID=your_app_id
APP_SECRET=your_app_secret
ACCESS_TOKEN=your_access_token
REFRESH_TOKEN=your_refresh_token
AUTH_CODE=your_auth_code

# OAuth 配置
CALLBACK_URL=http://127.0.0.1:8000/callback
OAUTH_SCOPE=account_service,report_service,ad_query
OAUTH_STATE=integration_auth_state
OAUTH_TYPE=authorized

# 业务测试参数
ADVERTISER_ID=1000012345
START_DATE=2026-04-01
END_DATE=2026-04-11

# 接口地址
OPENAPI_BASE_URL=https://ad.e.kuaishou.com/rest/openapi
OPENAPI_AUTH_URL=https://developers.e.kuaishou.com/tools/authorize

# HTTP 配置
MAGNETICENGINE_RUNTIME_MODE=cli
HTTP_CONNECT_TIMEOUT=20
HTTP_READ_TIMEOUT=30
HTTP_MAX_RETRIES=3
HTTP_RETRY_DELAY=1000
HTTP_ENABLE_RETRY=true
HTTP_RETRYABLE_BUSINESS_CODES=40100,40110,50000

配置优先级

系统环境变量（最高优先级）
.env 文件
默认配置（最低优先级）

🚨 错误处理

SDK 提供了统一的错误处理机制：

<?php

use Core\Exception\MagneticEngineException;

try {
    $response = $client->MagneticEngine()
        ->Advertiser
        ->V1AdvertiserInfo()
        ->setParams([
            'advertiser_id' => 123456789,
        ])
        ->send();
} catch (MagneticEngineException $e) {
    echo "错误类型: {$e->getErrorType()}\n";
    echo "错误码: {$e->getErrorCode()}\n";
    echo "错误信息: {$e->getErrorMessage()}\n";
    echo "HTTP状态码: " . ($e->getHttpStatus() ?? 0) . "\n";
}

📊 开发进度

模块	链式调用	状态	文档
磁力引擎	`$client->MagneticEngine()`	✅ 已完成	查看文档
磁力金牛	`$client->MagneticJinniu()`	✅ 已完成	查看文档
磁力聚星	`$client->MagneticJuxing()`	✅ 已完成	查看文档
短剧	`$client->MagneticShortDrama()`	✅ 已完成	查看文档

⚠️ 上述进度仅供参考，实际以源码为准。
🧠 欢迎查看源码深入探索，接口比文档更诚实！

📚 相关文档

🤝 贡献指南

欢迎提交 Issue 和 Pull Request，建议遵循以下规范。

1 分支规范

基于最新 main 分支开发
分支命名建议：feat/xxx、fix/xxx、refactor/xxx、docs/xxx

2 提交信息规范（Conventional Commits）

提交格式：

type(scope): subject

常用 type：

feat：新增功能
fix：缺陷修复
refactor：重构（不改行为）
docs：文档更新
test：测试补充或调整
perf：性能优化
chore：工程维护（依赖、脚本、配置等）

示例：

feat(magnetic-engine): add advertiser query api
fix(http): avoid stale pooled connections in long-lived workers
docs(readme): align usage guide with project structure
test(integration): add magnetic jinniu report api coverage

3 提交前检查

本地执行：composer test
格式检查：vendor/bin/php-cs-fixer fix --dry-run --config=.php-cs-fixer.php
若涉及行为变更，请同步更新 README.md 或 docs/*

4 Pull Request 要求

标题清晰说明“做了什么、为什么做”
描述中包含影响范围（模块/接口）与验证方式
若是破坏性变更，请明确标注 BREAKING CHANGE

📄 开源协议

本项目采用 MIT 协议 - 查看 LICENSE 文件了解详情。

📞 问题反馈

如在使用过程中遇到问题、建议或灵感……请无视（开玩笑的）。

📨 实在憋不住可以提 Issue 或 PR ～

如果这个项目对您有帮助，请给个 ⭐️ 支持一下！

Made with ❤️ by westng

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github		.github
docs		docs
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.php-cs-fixer.php		.php-cs-fixer.php
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
composer.lock		composer.lock
index.php		index.php
phpunit.xml.dist		phpunit.xml.dist

Folders and files

Latest commit

History

Repository files navigation

magneticengine-sdk-php

📖 概述

✨ 特性

🚀 快速开始

环境要求

安装

基础使用

📋 使用条件

运行环境自适配

开发者条件

📁 项目结构

📚 详细使用指南

1. 用户授权（获取 Access Token）

获取授权 URL

获取 Access Token

2. API 调用

配置重试机制

配置 TLS 证书校验

获取广告主信息

🔧 配置说明

环境变量配置

配置优先级

🚨 错误处理

📊 开发进度

📚 相关文档

🤝 贡献指南

1 分支规范

2 提交信息规范（Conventional Commits）

3 提交前检查

4 Pull Request 要求

📄 开源协议

📞 问题反馈

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages