PHPackages                             zewail/think-api - 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. [Authentication & Authorization](/categories/authentication)
4. /
5. zewail/think-api

ActiveLibrary[Authentication & Authorization](/categories/authentication)

zewail/think-api
================

v1.1.3(6y ago)3042.0k67[9 issues](https://github.com/czewail/thinp-api/issues)MITPHPPHP >=5.6

Since Sep 23Pushed 5y ago17 watchersCompare

[ Source](https://github.com/czewail/thinp-api)[ Packagist](https://packagist.org/packages/zewail/think-api)[ RSS](/packages/zewail-think-api/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (7)DependenciesVersions (20)Used By (0)

[![Latest Stable Version](https://camo.githubusercontent.com/7c81936f74c5ee347ebbe6060ce2b00e863b5d4f0f427d5b2cef8a0bf61abc3b/68747470733a2f2f706f7365722e707567782e6f72672f7a657761696c2f7468696e6b2d6170692f762f737461626c65)](https://packagist.org/packages/zewail/think-api)[![Total Downloads](https://camo.githubusercontent.com/acc70ed1f6f4e159ca1d00ea705270c3d7d37ca3dd1e4cb5fa939f8aa3297350/68747470733a2f2f706f7365722e707567782e6f72672f7a657761696c2f7468696e6b2d6170692f646f776e6c6f616473)](https://packagist.org/packages/zewail/think-api)[![Latest Unstable Version](https://camo.githubusercontent.com/c04485e873f519444cf5939a70ffe95acb5493f53213302a8a66b7187be43c87/68747470733a2f2f706f7365722e707567782e6f72672f7a657761696c2f7468696e6b2d6170692f762f756e737461626c65)](https://packagist.org/packages/zewail/think-api)[![License](https://camo.githubusercontent.com/8af99ce388fbfca8858af648589708cf5b88c27a2cb2855d2dd4256649bd1c7c/68747470733a2f2f706f7365722e707567782e6f72672f7a657761696c2f7468696e6b2d6170692f6c6963656e7365)](https://packagist.org/packages/zewail/think-api)

think-api 是给开发者提供的一套针对thinkphp的API扩展工具，帮助开发者方便快捷的建造自己的API应用。

**该包是针对thinkphp5.1以上版本**

简介
--

[](#简介)

这个包提供了以下等工具：

- API版本管理
- 响应生成器
- 数据过滤器
- JWT(Json Web Token)的支持

`thinp-api` 是给开发者提供的一套API工具，帮助你方便快捷的建造你自己的API，有什么使用问题和反馈建议请在[issue](https://github.com/czewail/thinp-api/issues)中提出

另外，欢迎Star和Fork该项目😄😄😄😄😄

安装
--

[](#安装)

安装该扩展包需要环境支持

- thinkphp 5.1+
- php 5.6+

修改你的 `composer.json` 文件，然后执行 `composer update` 把最后一个版本的包加入你的项目

```
"require": {
    "zewail/think-api": "1.1.*"
}
```

或者你可以在命令行执行 `composer require` 命令

```
composer require zewail/think-api:1.1.x
```

路由
--

[](#路由)

如果你使用了自定义路由，则可以使用路由版本管理

##### 版本组

[](#版本组)

使用`think-api`的版本管理方法来创建版本

```
$api = new \Zewail\Api\Routing\Router;

$api->version('v1', function () {
	// TODO 可以是thinkphp自带的路由
});
```

或者使用门面（Facede）

```
use Zewail\Api\Facades\ApiRoute;

ApiRoute::version('v1', function(){
    // TODO 可以是thinkphp自带的路由
});
```

你想一个分组返回多个版本，只需要传递一个版本数组

```
ApiRoute::version(['v1', 'v2'], function () {
	// TODO 可以是thinkphp自带的路由
});
```

##### 创建路由

[](#创建路由)

```
ApiRoute::version('v1', function(){
    Route::rule('new/:id','index/News/read');
});
```

因为每个版本分组了，你可以为相同 URL 上的同一个路由创建不同响应

```
ApiRoute::version('v1', function () {
	Route::rule('new/:id','app\index\controller\V2\News@read');
  	// 或者
  	Route::rule('new/:id','index/V2.News/read');
});

ApiRoute::version('v2', function () {
    Route::rule('new/:id','app\index\controller\V2\News@read');
});
```

##### 访问特定路由版本

[](#访问特定路由版本)

默认访问配置文件中的默认版本

但是，我们可以在Http的头信息中附带`Api-Version`参数，或者直接在在url或body中附带`version`参数来访问指定版本

```
http://example.com/new/102?version=v2
```

响应
--

[](#响应)

#### 响应生成器

[](#响应生成器)

响应生成器提供了一个流畅的接口去方便的建立一个定制化的响应

要利用响应生成器, 你的控制器需要使用`Zewail\Api\Api` trait, 可以建立一个通用控制器，然后你的所有的 API 控制器都继承它。

```
namespace app\index\controller;

use think\Controller;
use Zewail\Api\Api;

class BaseController extends Controller
{
	use Api;
}
```

然后你的控制器可以直接继承基础控制器。响应生成器可以在控制器里通过 `$response` 属性获取。

当然，也可以使用门面(Facade)来获取

```
namespace app\index\controller;

use Zewail\Api\Facades\Response as ApiResponse;

class IndexController
{
	public function index() {
        return ApiResponse::array([]);
    }
}
```

##### 简单响应

[](#简单响应)

```
// 简单的成功响应, 默认200状态码, 可以在第二个参数改变
// 使用 trait, 其他方法都可以使用该方法，下面都使用 Facade 演示
return $this->response->array($user->toArray());
// 使用 Facade
return ApiResponse::success('Success', 200);
```

##### 响应一个数组

[](#响应一个数组)

```
$user = User::get($id);
return ApiResponse::array($user->toArray());
```

##### 响应一个元素

[](#响应一个元素)

```
$user = User::get($id);
return ApiResponse::item($user);
```

##### 响应一个元素集合

[](#响应一个元素集合)

```
$users = User::all();
return ApiResponse::collection($users);
```

##### 分页响应

[](#分页响应)

```
$users = User::paginate(10);
return ApiResponse::paginator($users);
```

#### 使用别名生成响应

[](#使用别名生成响应)

捕获错误响应需要接管系统的异常处理机制，将系统`config/app.php`中的 `exception_handle`配置为`Zewail\Api\Exceptions\handleException`

```
// 异常处理handle类 留空使用 \think\exception\Handle
'exception_handle'       => 'Zewail\Api\Exceptions\handleException',
```

返回一个错误响应

```
return ApiResponse::BadRequest();
```

当然也可以返回成功的响应

```
return ApiResponse::OK($data);
```

方法名状态码说明Continue100ContinueSwitchingProtocols101Switching ProtocolsProcessing102ProcessingEarlyHints103Early HintsOK200OKCreated201CreatedAccepted202AcceptedNonAuthoritativeInformation203Non-Authoritative InformationNoContent204No ContentResetContent205Reset ContentPartialContent206Partial ContentMultiStatus207Multi-StatusAlreadyReported208Already ReportedIMUsed226IM UsedMultipleChoices300Multiple ChoicesMovedPermanently301Moved PermanentlyFound302FoundSeeOther303See OtherNotModified304Not ModifiedUseProxy305Use ProxyTemporaryRedirect307Temporary RedirectPermanentRedirect308Permanent RedirectBadRequest400Bad RequestUnauthorized401UnauthorizedPaymentRequired402Payment RequiredForbidden403ForbiddenNotFound404Not FoundMethodNotAllowed405Method Not AllowedNotAcceptable406Not AcceptableProxyAuthenticationRequired407Proxy Authentication RequiredRequestTimeou408Request TimeouConflict409ConflictGone410GoneLengthRequired411Length RequiredPreconditionFailed412Precondition FailedPayloadTooLarge413Payload Too LargeURITooLong414URI Too LongUnsupportedMediaType415Unsupported Media TypeRangeNotSatisfiable416Range Not SatisfiableExpectationFailed417Expectation FailedIAmATeapot418I'm a teapotMisdirectedRequest421Misdirected RequestUnprocessableEntity422Unprocessable EntityLocked423LockedFailedDependency424Failed DependencyUnorderedCollection425Unordered CollectionUpgradeRequired426Upgrade RequiredPreconditionRequired428Precondition RequiredTooManyRequests429Too Many RequestsRequestHeaderFieldsTooLarge431Request Header Fields Too LargeUnavailableForLegalReasons451Unavailable For Legal ReasonsInternalServerError500Internal Server ErrorNotImplemented501Not ImplementedBadGateway502Bad GatewayServiceUnavailable503Service UnavailableGatewayTimeout504Gateway TimeoutHTTPVersionNotSupported505HTTP Version Not SupportedVariantAlsoNegotiates506Variant Also NegotiatesInsufficientStorage507Insufficient StorageLoopDetected508Loop DetectedNotExtended510Not ExtendedNetworkAuthenticationRequired511Network Authentication Required#### 添加其他响应数据

[](#添加其他响应数据)

##### 添加 Meta 数据

[](#添加-meta-数据)

```
return ApiResponse::item($user)->addMeta('foo', 'bar');
```

或者直接设置 Meta 数据的数组

```
return ApiResponse::item($user)->setMeta($meta);
```

##### 设置响应状态码

[](#设置响应状态码)

```
return ApiResponse::item($user)->setCode(200);
```

##### 添加额外的头信息

[](#添加额外的头信息)

```
// 提供两种设置方式
return ApiResponse::item($user)->addHeader('X-Foo', 'Bar');
return ApiResponse::item($user)->addHeader(['X-Foo' => 'Bar']);
```

##### 设置 LastModified

[](#设置-lastmodified)

```
return ApiResponse::item($user)->setLastModified($time);
```

##### 设置 ETag

[](#设置-etag)

```
return ApiResponse::item($user)->setETag($eTag);
```

##### 设置 Expires

[](#设置-expires)

```
return ApiResponse::item($user)->setExpires($time);
```

##### 页面缓存控制

[](#页面缓存控制)

```
return ApiResponse::item($user)->setCacheControl($cache);
```

### 响应数据过滤

[](#响应数据过滤)

其中`item` `collection` `paginator`具有两个参数，第一个参数为模型数据，第二个参数为数据过滤列表

```
// 如查询出来的$user具有id, name, age, mobile等属性
// 在设置了第二个参数为['id', 'name', 'age']后，将会过滤其他属性，只返回给接口列出的属性
return ApiResponse::item($user, ['id', 'name', 'age']);
return ApiResponse::collection($users, ['id', 'name', 'age']);
return ApiResponse::paginator($users, ['id', 'name', 'age']);
```

或者通过`only`与`except`方法过滤数据

```
// 只选择模型中的id、name、age属性
return ApiResponse::only(['id', 'name', 'age'])->item($user);
// 排除模型属性age
return ApiResponse::except(['age'])->item($user);
// 还可以一起使用, 选择id、name、age属性后排除age
return ApiResponse::only(['id', 'name', 'age'])->except(['age'])->item($user);
```

##### 集中管理

[](#集中管理)

提供了一个配置文件用于数据过滤或者说是数据资源的集中管理

使用该功能需要在thinkphp中新建一个配置文件`resources.php`

```
return [
  // 用户相关接口
  // 例如设置一些用户的相关接口资源
  'user.age' => ['id', 'name', 'age'],
  'user.mobile' => ['id', 'name', 'mobile'],
];
```

然后在返回接口数据的时候在`item` `collection` `paginator`第二个参数传入该标识即可

```
// 返回{'data': {'id':1, 'name': 'xiaoming', 'age': 20}}
return ApiResponse::item($user, 'user.age');
// 返回{'data': {'id':1, 'name': 'xiaoming', 'mobile': '13777777777'}}
return ApiResponse::item($user, 'user.mobile');
```

或者通过`only`与`except`方法

```
// 返回{'data': {'id':1, 'name': 'xiaoming', 'age': 20}}
return ApiResponse::only('user.age')->item($user);
// 返回{'data': {'id':1, 'name': 'xiaoming', 'mobile': '13777777777'}}
return ApiResponse::only('user.mobile')->item($user);
```

> item、collection、paginator的第二个过滤参数属性，会覆盖only与except方法

#### 设置serializer

[](#设置serializer)

如果默认配置`Array`，想返回`DataArray`格式的数据，可以：

```
// 返回Array格式的数据
return ApiResponse::item($user)->serializer('Array');
// 返回DataArray格式的数据
return ApiResponse::item($user)->serializer('DataArray');
```

JWT
---

[](#jwt)

JWT相关知识大家百度一下吧，网上很多，直接上代码

### 创建Token

[](#创建token)

使用 JWT 门面的 attempt 方法来自动验证

```
namespace app\index\controller;

use app\index\model\User;
use Zewail\Api\Facades\Response;
use Zewail\Api\Facades\JWT;
use Zewail\Api\Exceptions\JWTException;

class Authenticate
{
	public function authenticate()
	{
        // $credentials 可以从请求中获取
        $credentials = ['email'=>'chanzewail@gmail.com', 'password' => '123456'];
        $token = JWT::attempt($credentials);
	}
}
```

这里使用了 email 和 password 来验证用户是否合法，如果你的用户是通过 mobile或其它字段作为标识，那么可以在 app\\index\\model\\User 模型中，添加 jwtSub 字段：

```
namespace app\index\model;

use think\Model;

class User extends Model
{
	public $jwtSub = 'mobile';
}
```

当然，如果你的密码 不是用的 password （绝大多数都用这个，不排除少数奇怪的命名….）,那么你可以添加 jwtPassword 字段：

```
public $jwtPassword = 'strange_password';
```

这里验证psssword默认使用md5加密，绝大多数情况下这是不够安全的，很多都有自定义的加密方式，那么还有验证密码的方法，添加：

```
public function jwtEncrypt($password)
{
 	// 只要返回你加密后的结果，会自动比对数据库字段
  	return md5(sha1($password));
}
```

还可以直接通过用户对象实例创建token

```
$user = User::get(1);
$token = JWT::fromUser($user);
```

还可以自定义 Payload 创建任意数据

```
$customClaims = ['foo' => 'bar', 'baz' => 'bob'];
$payload = JWT::makePayload($customClaims);
$token = JWT::encode($payload);
```

### 用户认证

[](#用户认证)

要通过http发送一个需要认证通过的请求，需要设置Authorization头

```
Authorization: Bearer {token}
```

或者将token信息包含到URL中

```
http://api.example.com/news?token={token}
```

##### 解析token

[](#解析token)

`resolveToken`方法可以将token还原为payload数组

```
$payload = JWT::resolveToken();
// ['foo' => 'bar', 'baz' => 'bob']
```

如果是从user模型创建的token，那么还可以使用authenticate方法，直接验证用户，成功后返回用户模型，失败返回false

```
if ($user = JWT::authenticate()) {
    // todo
}
```

当然还有更加手动的方法

```
// 从请求中获取token
$token = JWT::getToken();

// todo

// 对token进行解码
$payload = JWT::decode($token);
```

配置
--

[](#配置)

该扩展包共有3个配置文件

> 配置文件仅支持全局配置目录使用

- `api.php`：管理接口配置
- `resources.php`：过滤管理器配置
- `jwt.php`：JWT相关配置

配置文件可以在`vendor/zewail/think-api/config`目录下找到，也可以手动创建它们

### api.php

[](#apiphp)

```
retrun [
    //配置项
];
```

##### version

[](#version)

api的默认版本

##### serializer

[](#serializer)

api返回的数据格式,可选：

- `DataArray`：数组带data格式，默认值

    ```
    // item
    {
      'data': [...],
      'meta': [...],
      ...
    }

    // collection
    {
      'data': [
          {...},
          {...},
          {...},
        ],
      'meta': [...],
      ...
    }
    ```
- `Array`：数组格式

    ```
    // item
    {
      'item_field1': '...',
      'item_field2': '...',
      'meta': [...],
      ...
    }

    // collection
    {
      [
      	{...},
        {...},
      ],
      'meta': [...],
      ...
    }
    ```

    ​

### resources.php

[](#resourcesphp)

```
retrun [
  //配置项
  // 用户相关接口
  // 例如设置一些用户的相关接口资源
  'user.age' => ['id', 'name', 'age'],
  'user.mobile' => ['id', 'name', 'mobile'],
];
```

该配置文件用于数据过滤管理，在返回接口数据的时候在`item` `collection` `paginator`第二个参数传入该标识来使用

```
// 返回{'data': {'id':1, 'name': 'xiaoming', 'age': 20}}
return $this->response->item($user, 'user.age');
// 返回{'data': {'id':1, 'name': 'xiaoming', 'mobile': '13777777777'}}
return $this->response->item($user, 'user.mobile');
```

### jwt.php

[](#jwtphp)

```
retrun [
    //配置项
];
```

##### ttl

[](#ttl)

token的过期时间， 默认为120分钟，单位分钟

##### deviation

[](#deviation)

允许误差时间，默认为60秒，单位秒

##### algorithm

[](#algorithm)

加密算法，支持：

- `HS256`: `HMAC 使用 SHA-256 算法加密`
- `HS512`: `HMAC 使用 SHA-512 算法加密`
- `RS256`: `RSA 使用 SHA-256 算法加密`

##### key

[](#key)

如果使用了HMAC加密方式，则需要配置该项，为自定义字符串

##### privateKeyPath

[](#privatekeypath)

如果使用了RSA加密方式，则需要配置该项，为`.pem`结尾的私钥文件路径

##### publicKeyPath

[](#publickeypath)

如果使用了RSA加密方式，则需要配置该项，为`.pem`结尾的公钥文件路径

##### user

[](#user)

如果需要使用用户操作相关方法，则需定义该项，为用户模型所在路径，如

```
'user' => app\index\model\User::class,
```

授权协议
----

[](#授权协议)

[MIT license](LICENSE)

CHANGELOG
---------

[](#changelog)

#### 1.1.0-beta1

[](#110-beta1)

- 修复 php7 以下环境调用`response::array`报错的问题
- 添加全新状态码别名方法调用
- 移除动词方法别名调用生成Http异常（现在统一使用状态码别名）

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance19

Infrequent updates — may be unmaintained

Popularity37

Limited adoption so far

Community22

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 78.6% 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 ~56 days

Recently: every ~150 days

Total

18

Last Release

2198d ago

Major Versions

v0.2.1 → v1.0.0-beta12017-10-08

PHP version history (2 changes)v0.0.1PHP >=5.5.9

v1.0.0-beta2PHP >=5.6

### Community

Maintainers

![](https://www.gravatar.com/avatar/bc9ac0baa4a9380596619d9c5d630cb6601f7d0d1b59b8e010179eaadfb154e7?d=identicon)[zewail](/maintainers/zewail)

---

Top Contributors

[![czewail](https://avatars.githubusercontent.com/u/14213748?v=4)](https://github.com/czewail "czewail (11 commits)")[![Dshufeng](https://avatars.githubusercontent.com/u/22002318?v=4)](https://github.com/Dshufeng "Dshufeng (1 commits)")[![qeq66](https://avatars.githubusercontent.com/u/19647183?v=4)](https://github.com/qeq66 "qeq66 (1 commits)")[![yinggaozhen](https://avatars.githubusercontent.com/u/13899619?v=4)](https://github.com/yinggaozhen "yinggaozhen (1 commits)")

---

Tags

apiapi-thinkphpjwtthink-apithinkphptp5

### Embed Badge

![Health badge](/badges/zewail-think-api/health.svg)

```
[![Health](https://phpackages.com/badges/zewail-think-api/health.svg)](https://phpackages.com/packages/zewail-think-api)
```

###  Alternatives

[namshi/jose

JSON Object Signing and Encryption library for PHP.

1.8k99.6M101](/packages/namshi-jose)[league/oauth1-client

OAuth 1.0 Client Library

99698.8M106](/packages/league-oauth1-client)[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k2.9M88](/packages/bezhansalleh-filament-shield)[gesdinet/jwt-refresh-token-bundle

Implements a refresh token system over Json Web Tokens in Symfony

70516.4M35](/packages/gesdinet-jwt-refresh-token-bundle)[league/oauth2-google

Google OAuth 2.0 Client Provider for The PHP League OAuth2-Client

41721.2M118](/packages/league-oauth2-google)[illuminate/auth

The Illuminate Auth package.

9327.3M1.0k](/packages/illuminate-auth)

PHPackages © 2026

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