php api restダウンロード - php api restソースコードのダウンロード

PHP-API-REST

アノテーションを使用したphp api restフレームワークと Swagger 2.0 のサポート。

前提条件

PHP >=7.2

オプション (推奨)

ルートのキャッシング

nrk/predis (Redis) - https://github.com/nrk/predis または
Pecl APC - 代替 PHP キャッシュ - https://pecl.php.net/package/apc

Swagger yaml 形式

yaml pecl 拡張機能 https://pecl.php.net/package/yaml

インストール中

Composer を使用して依存関係を管理し、PHP-API-REST をダウンロードします。

composer require diomac/php-api-rest

始めましょう

API 残りの構成

1 - .htaccess ファイルを Rest API (ベース URL) のルートフォルダーに配置し、すべてのルートを API 初期化ファイルにリダイレクトします。

API フォルダーの例:

.htaccess ファイル:

 RewriteEngine On
RewriteCond %{REQUEST_URI} !init.php$
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule .* init.php [L,QSA]

2 - 初期化ファイルを使用してプロジェクトの依存関係をインポートし、...
- DiomacAPIAppConfiguration オブジェクトをインスタンス化します。
- API のベース URL を設定します。
- API のリソースクラス名を追加します (「API 残りのリソースの実装」を参照)。
- 構成オブジェクトを使用して DiomacAPIApp オブジェクトをインスタンス化します。
- 最後にexecメソッドを呼び出します。

init.php ファイル:

 use DiomacAPIApp;
use DiomacAPIAppConfiguration;

/**
 * Initializing API configuration
 */
$config = new AppConfiguration();
$config->setBaseUrl('/php-api-rest/example/v1');

/**
 * Adding resources classes
 */
$config->addResource(examplev1ExampleResource::class);
$config->addResource(examplev1ExampleSwaggerJson::class);

/**
 * Execute API
 */
try{
    $app = new App($config);
    $app->exec();
}catch (Exception $ex){
    ...
}

API REST リソースの実装

3 - リソースクラスに、リソースクラスの継承を入力します。

 namespace example;

use DiomacAPIResource;
use DiomacAPIResponse;
use DiomacAPIUnauthorizedException;

class ExampleResource extends Resource 
{
    ...
}

4 - リソースクラスのメソッドごとに、ルート (@route)、HTTP メソッド (@method) を識別するための PHP アノテーションを入力します。また、ルートを保護するためにガードインターフェイスを実装するクラスが必要な場合は (@guard - トピックでガードの実装方法を参照してください)ガードクラスの実装):

 /**
* @method get
* @route /auth/usr-data/id/{id}
* @guard(
*     className="examplecoresecureExampleGuard",
*     @parameters(operationId="GETUSERDATA")
* )
*/
function getUsrData()
{
  // ... your code
  $this->response->setCode(Response::OK); // set HTTP response code
  $this->response->setBodyJSON($jsonSerializable); // set responde data
  return $this->response; // return response object
}

リソースクラスの継承

5 - ルートが実行されるたびに、ルートを保持するクラスがインスタンス化され、次の属性を継承します。

次のメソッドを備えた DiomacAPIRequest オブジェクト:

 $this->request->getParams() // returns the parameters of the URL and $_GET
$this->request->getData()   // returns an object sent by the front end
$this->request->getRoute()  // returns the executed route
$this->request->getMethod() // returns the executed HTTP method

DiomacAPIResponse オブジェクトとメソッド:

 $this->response->setHeader('name', 'value'); // set HTTP header response
$this->response->setCode(Response::BAD_REQUEST); // set HTTP response code
$this->response->setBody('string'); // set response body
$this->response->setBodyJSON(JsonSerializable object); // set response body to convert in JSON
$this->response->setContentType(''); // set content type response (for setBodyJSON not needed)

そして、DiomacAPIResource クラスからメソッドを継承します。

 $this->getRoute(); // returns the configured route
$this->getParams(); // returns the parameters of the URL and $_GET
$this->getParam('name'); // returns a parameter by name

出力

6 - 出力の場合は、単純に応答オブジェクトを返します。

 return $this->response;

完全なリソースの例

APIの取得メソッド：

 /**
 * @method get
 * @route /example/v1/pet/{petId}
 *
 * @return Response
 * @throws Exception
 */
function getPet(): Response
{
    try {
        $petId = $this->getParam('petId');
        $pet = new Pet($petId);

        /**
         * API Rest best practices - selecting returned fields and aliases
         */
        $fields = $this->getParam('fields');

        if($fields){
            Response::setFields(explode(',', $fields), Pet::class);
        }

        $this->response->setCode(Response::OK);
        $this->response->setBodyJSON($pet);
    } catch (Exception $ex) {
        throw new Exception('Internal Server Error', Response::INTERNAL_SERVER_ERROR);
    }

    return $this->response;
}

衛兵

 /**
* @method get
* @route /auth/usr-data/id/{id}
* @guard(
*     className="examplecoresecureExampleGuard"
* )
* @guard(
*     className="examplecoresecureExampleGuardWithParams",
*     @parameters(operationId="GETUSERDATA", operationName="GETUSERDATA")
* )
*/
function getUsrData()
{
  // ... your code
  $this->response->setCode(Response::OK); // set HTTP response code
  $this->response->setBodyJSON($ this->request->getData()); // set responde data
  return $this->response; // return response object
}

ガードクラスの実装

 namespace apisecure;

use DiomacAPIException;
use DiomacAPIForbiddenException;
use DiomacAPIUnauthorizedException;
use DiomacAPIResponse;
use DiomacAPIGuard;

/**
 * Class AuthGuard
 * @package apisecure
 */
class AuthGuard implements Guard
{
    /**
     * @param object|null $guardParams
     * @return bool
     * @throws Exception
     * @throws ForbiddenException
     * @throws UnauthorizedException
     */
    public function guard(object $guardParams = null) : bool
    {
        $func = $guardParams->func;
        $access = checkAccess($func);
        switch ($access) {
            case Response::OK:
                return true;
                break;
            case Response::UNAUTHORIZED:                
                throw new UnauthorizedException();
                break;
            case Response::FORBIDDEN:                
                throw new ForbiddenException();
                break;
            default:               
                throw new Exception('Server Error!', Response::INTERNAL_SERVER_ERROR);
        }
    }
}

キャッシュ

キャッシュ設定では、マッピングされたルートがリストに保存され、使用すると (true に設定すると)、ルートマッピングの手順がスキップされ、パフォーマンスが向上します。

APC によるキャッシュ - 代替 PHP キャッシュ

 **
 * Setting use cache for caching of annotations mapping
 */
$config->setUseCache(true);

/**
 * Execute API
 */
try{
    $app = new App($config);
    $app->exec();
}catch (Exception $ex){
    ...
}

Redisによるキャッシュ

 /**
 * Set Redis for cache
 */
$redis = new RedisConfig();
$redis->setScheme('tcp');
$redis->setHost('redis');
$redis->setPort(6379);

**
 * Setting use cache for caching of annotations mapping
 */
$config->setUseCache(true, $redis);

Swagger 2.0 のサポート

swagger.json または swagger.yaml

以下の例のようなルートをリソース内に作成します。

PHP クラス:

 use DiomacAPIResource;
use DiomacAPIResponse;
use examplev1docExampleSwaggerDoc;

class ExampleSwaggerJson extends Resource
{
    /**
     * @method get
     * @route /swagger.json
     */
    function swaggerJson()
    {
        $this->response->setCode(Response::OK);
        $swagger = new ExampleSwaggerDoc();

        /**
         * JSON
         */
        $this->response->setBodySwaggerJSON($swagger);
        /**
         * Or YAML
         */
        //$this->response->setBodySwaggerYAML($swagger);
        return $this->response;
    }
}

ルート結果:

 {
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Sample App",
    "description": "This is a sample server Petstore server.",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "name": "API Support",
      "email": "[email protected]",
      "url": "http://swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host": "localhost",
  "basePath": "/php-api-rest/vendor/example/v1",
  "schemes": [
    "http",
    "https"
  ],
  "consumes": [
    "text/plain; charset=utf-8"
  ],
  "produces": [
    "application/json",
    "text/html"
  ],
  "tags": [
    {
      "name": "ExampleAPIDocSwagger",
      "description": "ExampleAPIDocSwagger",
      "externalDocs": {
        "description": "Externaldocsexample",
        "url": "http://example_php_api_rest.com"
      }
    }
  ],
  "paths": {
    ...

スワッガー情報

API の情報 (Swagger Info) を文書化するには、Swagger クラスと SwaggerInfo クラスを使用できます。以下の例のように、Swagger を継承する「ExampleSwaggerDoc」クラスを実装するだけです。

PHP クラス:

 use DiomacAPIswaggerSwagger;
use DiomacAPIswaggerSwaggerInfo;

class ExampleSwaggerDoc extends Swagger
{
    public function info(): SwaggerInfo
    {
        $this->setInfo(new SwaggerInfo());
        $this->info->setVersion('1.0.0');
        $this->info->setTitle('Swagger Sample App');
        $this->info->setDescription('This is a sample server Petstore server.');
        $this->info->setTermsOfService('http://swagger.io/terms/');

        $this->info->getContact()->setName('API Support');
        $this->info->getContact()->setEmail('[email protected]');
        $this->info->getContact()->setUrl('http://swagger.io');

        $this->info->getLicense()->setName('Apache 2.0');
        $this->info->getLicense()->setUrl('http://www.apache.org/licenses/LICENSE-2.0.html');

        return $this->getInfo();
    }
    ...
}

@タグ

PHPDoc クラスで @tag を使用して、Swagger タグオブジェクトでリソースのルートを文書化します。

PHPDoc:

 /**
 * Class ExampleResource
 * @package examplev1
 * @tag(
 *     name="Example API Doc Swagger",
 *     description="Example API Doc Swagger",
 *     @externalDocs(description="External docs example", url="http://example_php_api_rest.com")
 * )
 */
class ExampleResource extends Resource
{
    ...
}

Swagger json の結果:

 ...
"tags": [
    {
      "name": "ExampleAPIDocSwagger",
      "description": "ExampleAPIDocSwagger",
      "externalDocs": {
        "description": "Externaldocsexample",
        "url": "http://example_php_api_rest.com"
      }
    }
  ],
...

@タグ（文字列）

PHPDoc 関数で @tag を使用して、追加のタグでルートを文書化します。

PHPDoc:

    /**
     * @method get
     * @route /example/api/value1/{value1}/value2/{value2}
     * @tag More one tag
     */
    function getUsrData(): Response
    {
        ...
    }

Swagger json の結果:

 ...
"tags": [
          "More one tag",
          "ExampleAPIDocSwagger"
        ],
...

@contentType

PHPDoc 関数で @contentType を使用して、Swagger が [文字列] を生成するルートを文書化します。

PHPDoc:

    /**
     * @method get
     * @route /example/api/value1/{value1}/value2/{value2}
     * @contentType application/json
     * @contentType text/html
     */
    function getUsrData(): Response
    {
        ...
    }

Swagger json の結果:

 ...
"produces": [
    "application/json",
    "text/html"
  ],
...

@まとめ

PHPDoc 関数で @summary を使用して、Swagger 概要文字列を使用してルートを文書化します。

PHPDoc:

    /**
     * @method get
     * @route /example/api/value1/{value1}/value2/{value2}
     * @summary Example api rest php
     */
    function getUsrData(): Response
    {
        ...
    }

Swagger json の結果:

 ...
"get": {
        "summary": "Example api rest php",
...

@説明

PHPDoc 関数で @description を使用して、Swagger の説明文字列でルートを文書化します。

PHPDoc:

    /**
     * @method get
     * @route /example/api/value1/{value1}/value2/{value2}
     * @description A example api rest php
     */
    function getUsrData(): Response
    {
        ...
    }

Swagger json の結果:

 ...
"get": {
        "description": "A example api rest php",
...

@operationId

PHPDoc 関数で @operationId を使用して、Swagger のoperationId 文字列を使用してルートを文書化します。

PHPDoc:

    /**
     * @method get
     * @route /example/api/value1/{value1}/value2/{value2}
     * @operationId GETUSERDATA
     */
    function getUsrData(): Response
    {
        ...
    }

Swagger json の結果:

 ...
"get": {
        "operationId": "GETUSERDATA",
...

@consumeType

PHPDoc 関数で @consumeType を使用して、Swagger が [文字列] を消費するというルートを文書化します。

PHPDoc:

    /**
     * @method get
     * @route /example/api/value1/{value1}/value2/{value2}
     * @consumeType text/plain; charset=utf-8
     */
    function getUsrData(): Response
    {
        ...
    }

Swagger json の結果:

 ...
"post": {
       "consumes": [
                 "text/plain; charset=utf-8"
               ],
...

@応答（...）

PHPDoc 関数で @response(...) を使用して、Swagger 応答オブジェクトでルートを文書化します。

PHPDoc:

    /**
     * @method get
     * @route /example/api/value1/{value1}/value2/{value2}
     * @response(
     *     code=200,
     *     description="Success",
     *     @schema(
     *     type="object",
     *     @items($ref="#/definitions/sucess")
     * )
     * )
     */ 
    function getUsrData(): Response
    {
        ...
    }

Swagger json の結果:

 ...
"responses": {
          "200": {
            "description": "Success",
            "schema": {
              "type": "object",
              "items": {
                "$ref": "#/definitions/sucess"
              }
            }
          },
...

ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください

拡大する

php api rest

PHP-API-REST

前提条件

オプション (推奨)

ルートのキャッシング

Swagger yaml 形式

インストール中

始めましょう

API 残りの構成

API REST リソースの実装

リソースクラスの継承

出力

完全なリソースの例

衛兵

ガードクラスの実装

キャッシュ

APC によるキャッシュ - 代替 PHP キャッシュ

Redisによるキャッシュ

Swagger 2.0 のサポート

swagger.json または swagger.yaml

スワッガー情報

@タグ

PHPDoc クラスで @tag を使用して、Swagger タグ オブジェクトでリソースのルートを文書化します。

@タグ（文字列）

PHPDoc 関数で @tag を使用して、追加のタグでルートを文書化します。

@contentType

PHPDoc 関数で @contentType を使用して、Swagger が [文字列] を生成するルートを文書化します。

@まとめ

PHPDoc 関数で @summary を使用して、Swagger 概要文字列を使用してルートを文書化します。

@説明

PHPDoc 関数で @description を使用して、Swagger の説明文字列でルートを文書化します。

@operationId

PHPDoc 関数で @operationId を使用して、Swagger のoperationId 文字列を使用してルートを文書化します。

@consumeType

PHPDoc 関数で @consumeType を使用して、Swagger が [文字列] を消費するというルートを文書化します。

@応答（...）

PHPDoc 関数で @response(...) を使用して、Swagger 応答オブジェクトでルートを文書化します。

ライセンス

PHPDoc クラスで @tag を使用して、Swagger タグオブジェクトでリソースのルートを文書化します。