チュートリアル

年月日を入力すると曜日を返すWebサービスを作成してみましょう。 まずプロジェクトを作成します。

composer create-project bear/skeleton MyVendor.Weekday

vendor名をMyVendorproject名をWeekdayとして入力します。

最初にインストールされるアプリケーションリソースファイルをsrc/Resource/App/Weekday.phpに作成します。

<?php
namespace MyVendor\Weekday\Resource\App;

use BEAR\Resource\ResourceObject;

class Weekday extends ResourceObject
{
    public function onGet(int $year, int $month, int $day) : ResourceObject
    {
        $date = \DateTime::createFromFormat('Y-m-d', "$year-$month-$day");
        $this['weekday'] = $date->format('D');

        return $this;
    }
}

このMyVendor\Weekday\Resource\App\Weekdayリソースクラスは/weekdayというパスでアクセスすることができます。 GETメソッドのクエリーがonGetメソッドの引数に渡されます。

コンソールでアクセスしてみましょう。まずはエラーを試してみます。

404 Not Found
content-type: application/vnd.error+json

{
    "message": "Not Found",
    "logref": "466fa1ee",
...

400はリクエストに問題があるエラーコードです。 次は引数をつけて正しいリクエストを試します。

php bootstrap/api.php get '/weekday?year=2001&month=1&day=1'

200 OK
Content-Type: application/hal+json

{
    "weekday": "Mon",
    "_links": {
        "self": {
            "href": "/weekday?year=2001&month=1&day=1"
        }
    }
}

application/hal+jsonというメディアタイプで結果が正しく返って来ました。

これをWeb APIサービスにしてみましょう。 Built-inサーバーを立ち上げます。

php -S 127.0.0.1:8080 bootstrap/api.php

curlでHTTPのGETリクエストを行って確かめてみましょう。

curl -i 'http://127.0.0.1:8080/weekday?year=2001&month=1&day=1'
HTTP/1.1 200 OK
Host: 127.0.0.1:8080
Date: Sun, 04 Jun 2017 19:48:09 +0200
Connection: close
X-Powered-By: PHP/7.1.4
content-type: application/hal+json

{
    "weekday": "Mon",
    "_links": {
        "self": {
            "href": "/weekday/2001/1/1"
        }
    }
}

このリソースクラスにはGET以外のメソッドは用意されていないので、他のメソッドを試すと405 Method Not Allowedが返されます。これも試してみましょう。

curl -i -X POST 'http://127.0.0.1:8080/weekday?year=2001&month=1&day=1'
HTTP/1.1 405 Method Not Allowed
...

HTTP OPTIONS メソッドリクエストで利用可能なHTTPメソッドと必要なパラメーターを調べることができます。(RFC7231)

curl -i -X OPTIONS 'http://127.0.0.1:8080/weekday'
HTTP/1.1 200 OK
...
Content-Type: application/json
Allow: GET

{
    "GET": {
        "parameters": {
            "year": {
                "type": "integer"
            },
            "month": {
                "type": "integer"
            },
            "day": {
                "type": "integer"
            }
        },
        "required": [
            "year",
            "month",
            "day"
        ]
    }
}

ルーティング

デフォルトのルーターはURLをディレクトリにマップするWebRouterです。 ここでは動的なパラメーターをパスで受け取るためにAuraルーターを使用します。

最初にcompoerでインストールします。

composer require bear/aura-router-module ~1.0

次にsrc/Module/AppModule.phpAuraRouterModuleを上書き(override)インストールします。

<?php
namespace MyVendor\Weekday\Module;

use BEAR\Package\PackageModule;
use Ray\Di\AbstractModule;
use josegonzalez\Dotenv\Loader as Dotenv;
use BEAR\Package\Provide\Router\AuraRouterModule; // この行を追加

class AppModule extends AbstractModule
{
    protected function configure()
    {
        Dotenv::load([
            'filepath' => dirname(dirname(__DIR__)) . '/.env',
            'toEnv' => true
        ]);
        $this->install(new PackageModule);
        $this->override(new AuraRouterModule); // この行を追加
    }
}

ルータースクリプトファイルをvar/conf/aura.route.phpに設置します。

<?php
/* @var $router \BEAR\Package\Provide\Router\AuraRoute */
/* @var $schemeHost string */

$router->route('/weekday', '/weekday/{year}/{month}/{day}');

試してみましょう。

php bootstrap/api.php get '/weekday/1981/09/08'
200 OK
Content-Type: application/hal+json

{
    "weekday": "Tue",
    "_links": {
        "self": {
            "href": "/weekday/1981/09/08"
        }
    }
}

DI

monolog を使って結果をログする機能を追加してみましょう。 composerで取得します。

composer require monolog/monolog ~1.0

monologログオブジェクトはnewで直接作成しないで、作成されたログオブジェクトを受け取るようにします。 このように必要なもの(依存)を自らが取得するのではなく、外部から代入する仕組みを DI といいます。

依存を提供するMonologLoggerProvidersrc/Module/MonologLoggerProvider.phpに作成します。

<?php
namespace MyVendor\Weekday\Module;

use BEAR\AppMeta\AbstractAppMeta;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use Ray\Di\ProviderInterface;

class MonologLoggerProvider implements ProviderInterface
{
    /**
     * @var AbstractAppMeta
     */
    private $appMeta;

    public function __construct(AbstractAppMeta $appMeta)
    {
        $this->appMeta = $appMeta;
    }

    public function get()
    {
        $log = new Logger('weekday');
        $log->pushHandler(
            new StreamHandler($this->appMeta->logDir . '/weekday.log')
        );

        return $log;
    }
}

ログをファイル記録するために必要なログフォルダのパスの情報は、コンストラクタで受け取ったアプリケーションのメタ情報から取得します。 依存はgetメソッドで提供します。

次にロガーインターフェイスと、この依存を生成するファクトリークラスを結びつけます。 src/Modules/AppModule.phpconfigureメソッドに以下を追加します。

$this->bind(LoggerInterface::class)->toProvider(MonologLoggerProvider::class)->in(Scope::SINGLETON);

classキーワードでクラス名を解決するために以下のuse文も必要です。

use Psr\Log\LoggerInterface;
use Ray\Di\Scope;

どのクラスでもコンストラクタでmonologオブジェクトを受け取ることができるようになりました。 src/Resource/App/Weekday.phpを修正してlogを書きだしてみます。

<?php
namespace MyVendor\Weekday\Resource\App;

use BEAR\Resource\ResourceObject;
use Psr\Log\LoggerInterface;

class Weekday extends ResourceObject
{
    /**
     * @var LoggerInterface
     */
    private $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    public function onGet(int $year, int $month, int $day) : ResourceObject
    {
        $date = \DateTime::createFromFormat('Y-m-d', "$year-$month-$day");
        $this['weekday'] = $date->format('D');
        $this->logger->info("$year-$month-$day {$this['weekday']}");

        return $this;
    }
}

実行してvar/log/cli-hal-api-app/weekday.logに結果が出力されていることを確認しましょう。

php bootstrap/api.php get '/weekday/2011/05/23'
cat var/log/cli-hal-api-app/weekday.log

AOP

メソッドの実行時間を計測するためのベンチマーク処理を考えてみます。

$start = microtime(true);
// メソッド実行
$time = microtime(true) - $start;

ベンチマークを行う度にこのコードを付加して、不要になれば取り除くのは大変です。 アスペクト指向プログラミング(AOP)はこのようなメソッドの前後の特定処理をうまく合成することが出来ます。

まずAOPを実現するためにメソッドの実行を横取り(インターセプト)してベンチマークを行うインターセプターsrc/Interceptor/BenchMarker.phpに作成します。

<?php
namespace MyVendor\Weekday\Interceptor;

use Psr\Log\LoggerInterface;
use Ray\Aop\MethodInterceptor;
use Ray\Aop\MethodInvocation;

class BenchMarker implements MethodInterceptor
{
    /**
     * @var LoggerInterface
     */
    private $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    public function invoke(MethodInvocation $invocation)
    {
        $start = microtime(true);
        $result = $invocation->proceed(); // 元のメソッドの実行
        $time = microtime(true) - $start;
        $msg = sprintf("%s: %s", $invocation->getMethod()->getName(), $time);
        $this->logger->info($msg);

        return $result;
    }
}

元のメソッドを横取りしたインターセプターのinvokeメソッドでは、元メソッドの実行を$invocation->proceed();で行うことができます。 その前後にタイマーのリセット、計測記録の処理を行います。(メソッド実行オブジェクトMethodInvocation $invocationから元メソッドのオブジェクトとメソッドの名前を取得しています。)

次にベンチマークをしたいメソッドに目印をつけるためのアノテーションsrc/Annotation/BenchMark.php に作成します。

<?php
namespace MyVendor\Weekday\Annotation;

/**
 * @Annotation
 */
final class BenchMark
{
}

AppModuleMatcherを使ってインターセプターを適用するメソッドを束縛(バインド)します。

use MyVendor\Weekday\Annotation\BenchMark;
use MyVendor\Weekday\Interceptor\BenchMarker;

// configure()に追加します。
$this->bindInterceptor(
    $this->matcher->any(),                           // どのクラスでも
    $this->matcher->annotatedWith(BenchMark::class), // @BenchMarkとアノテートされているメソッドに
    [BenchMarker::class]                             // BenchMarkerインターセプターを適用
);

ベンチマークを行いたいメソッドに@BenchMarkとアノテートします。

<?php
use MyVendor\Weekday\Annotation\BenchMark;

class Weekday
{
    /**
     * @BenchMark
     */
    public function onGet($year, $month, $day)
    {

これで計測したいメソッドに@BenchMarkとアノテートすればいつでもベンチマークできるようになりました。

アノテーションとインターセプターによる機能追加は柔軟です。対象メソッドやメソッドを呼ぶ側に変更はありません。 アノテーションはそのままでも束縛を外せばベンチマークを行いません。例えば、開発時にのみ束縛を行い特定の秒数を越すと警告を行うこともできます。

実行してvar/log/weekday.logに実行時間のログが出力されることを確認しましょう。

php bootstrap/api.php get '/weekday/2015/05/28'
cat var/log/weekday.log

HTML

次に今のAPIアプリケーションをHTMLアプリケーションにしてみましょう。 今のappリソースに加えて、src/Resource/Page/Index.phppageリソースを追加します。

pageリソースクラスは場所と役割が違うだけでappリソースと基本的に同じクラスです。

<?php
namespace MyVendor\Weekday\Resource\Page;

use BEAR\Resource\Annotation\Embed;
use BEAR\Resource\ResourceObject;

class Index extends ResourceObject
{
    /**
     * @Embed(rel="weekday", src="app://self/weekday{?year,month,day}")
     */
    public function onGet(int $year, int $month, int $day) : ResourceObject
    {
        $this['year'] = $year;
        $this['month'] = $month;
        $this['day'] = $day;

        return $this;
    }
}

@Embedアノテーションでapp://self/weekdayリソースをbodyのweekdayキーに埋め込んでいます。その際にクエリーをRFC6570 URI templateを使って{?year,month,day}として同じものを渡しています。下記の2つのURI templateは同じURIを示しています。

  • app://self/weekday{?year,month,day}
  • app://self/weekday?year={year},month={month},day={day}

<iframe><img>タグで他のリソースを含むページをイメージしてください。これらもHTMLページが画像や他のHTMLなどのリソースを自身に埋め込んでいます。

上記のページクラスは下記のページクラスと同じものです。こちらは@Embedでリソースを埋め込むかわりに use ResourceInject;resourceリソースクライアントをインジェクトしてそのクラインアトでappリソースをセットしています。

 <?php
namespace MyVendor\Weekday\Resource\Page;

use BEAR\Resource\ResourceObject;
use BEAR\Sunday\Inject\ResourceInject;

class Index extends ResourceObject
{
    use ResourceInject;

    public function onGet(int $year, int $month, int $day) : ResourceObject
    {
        $this['year'] = $year;
        $this['month'] = $month;
        $this['day'] = $day;
        $this['weekday'] = $this->resource
            ->get
            ->uri('app://self/weekday')
            ->withQuery(['year' => $year, 'month' => $month, 'day' => $day])
            ->request();

        return $this;
    }
}

最初の@Embedを使った方法は宣言型プログラミング(Declative Programming) 、後者は命令型プログラミング(Imperative Programming)です。@Embedを使った前者は簡潔で可読性が高くリソースの関係を良く表しています。

このリソースがどのような表現になるのか試してみましょう。

php bootstrap/web.php get '/?year=2000&month=1&day=1'
200 OK
content-type: application/hal+json

{
    "year": 2000,
    "month": 1,
    "day": 1,
    "_embedded": {
        "weekday": {
            "weekday": "Sat"
        }
    },
    "_links": {
        "self": {
            "href": "/index?year=2000&month=1&day=1"
        }
    }
}

他のリソースが_embeddedされているのが確認できます。 リソースはapplication/hal+jsonメディアタイプで出力されていますが、これをHTML(text/html)で出力するためにHTMLモジュールをインストールします。HTMLのマニュアル参照。

composerインストール

composer require madapaja/twig-module ^1.0

src/Module/HtmlModule.phpを作成

<?php
namespace MyVendor\Weekday\Module;

use Madapaja\TwigModule\TwigModule;
use Ray\Di\AbstractModule;

class HtmlModule extends AbstractModule
{
    protected function configure()
    {
        $this->install(new TwigModule);
    }
}

bootstrap/web.phpを変更

$context = 'cli-html-app';
require __DIR__ . '/bootstrap.php';

これでtext/htmlメディア出力の準備はできました。最後にsrc/Resource/Page/Index.html.twigにtwigテンプレートを用意します。

<!DOCTYPE html>
<html>
<body>
The weekday of {{ year }}/{{ month }}/{{ day }} is {{ weekday.weekday }}.
</body>
</html>

準備完了です。まずはコンソールでこのようなHTMLが出力されるか確認してみましょう。

php bootstrap/web.php get '/?year=1991&month=8&day=1'
200 OK
content-type: text/html; charset=utf-8

<!DOCTYPE html>
<html>
<body>
The weekday of 1991/8/1 is Thu.
</body>
</html>

もしこの時htmlが表示されなければ、テンプレートエンジンのエラーが発生しています。 その時はログファイル(var/log/app.cli-html-app.log)でエラーを確認しましょう。

次にWebサービスを行うためにpublic/index.phpを変更します。

$context = 'prod-html-app';
require dirname(dirname(__DIR__)) . '/bootstrap/bootstrap.php';

PHPサーバーを立ち上げてwebブラウザでhttp://127.0.0.1:8080/?year=2001&month=1&day=1をアクセスして確認してみましょう。

php -S 127.0.0.1:8080 public/index.php

コンテキストはアプリケーションの実行モードのようなもので、複数指定できます。試してみましょう。

$context = 'app';           // JSONアプリケーション (最小)
$context = 'prod-hal-app';  // プロダクション用HALアプリケーション

コンテキストに応じたインスタンスを生成するPHPコードが生成されます。アプリケーションのvar/tmp/フォルダを確認してみましょう。これらのファイルは普段見る必要はありませんが、オブジェクトがどのように作られているかを確認することができます。diffコマンドでコンテキストによってどのように依存が変更されているかを確認してみましょう。

diff -q var/tmp/app/ var/tmp/prod-hal-app/

データベースを使ったハイパーメディアAPI

sqlite3を使ったアプリケーションリソースを作成してみましょう。 まずはコンソールでvar/db/todo.sqlite3にDBを作成します。

mkdir var/db
sqlite3 var/db/todo.sqlite3

sqlite> create table todo(id integer primary key, todo, created);
sqlite> .exit

データベースはAuraSqlや, Doctrine DbalCakeDBなどから選べますが ここではCakePHP3でも使われているCakeDBをインストールしてみましょう。

composer require ray/cake-database-module ~1.0

src/Module/AppModule::configure()でモジュールのインストールをします。

use Ray\CakeDbModule\CakeDbModule;
// ...

$dbConfig = [
    'driver' => 'Cake\Database\Driver\Sqlite',
    'database' => dirname(dirname(__DIR__)) . '/var/db/todo.sqlite3'
];
$this->install(new CakeDbModule($dbConfig));

セッターメソッドのtrait DatabaseInjectを使うと$this->dbでCakeDBオブジェクトを使えます。

Todoリソースをsrc/Resource/App/Todo.phpに設置します。

<?php
namespace MyVendor\Weekday\Resource\App;

use BEAR\Package\Annotation\ReturnCreatedResource;
use BEAR\RepositoryModule\Annotation\Cacheable;
use BEAR\Resource\ResourceObject;
use Ray\CakeDbModule\Annotation\Transactional;
use Ray\CakeDbModule\DatabaseInject;

/**
 * @Cacheable
 */
class Todo extends ResourceObject
{
    use DatabaseInject;

    public function onGet(int $id) : ResourceObject
    {
        $this->body = $this
            ->db
            ->newQuery()
            ->select('*')
            ->from('todo')
            ->where(['id' => $id])
            ->execute()
            ->fetch('assoc');

        return $this;
    }

    /**
     * @Transactional
     * @ReturnCreatedResource
     */
    public function onPost(string $todo) : ResourceObject
    {
        $statement = $this->db->insert(
            'todo',
            ['todo' => $todo, 'created' => new \DateTime('now')],
            ['created' => 'datetime']
        );
        // hyper link
        $id = $statement->lastInsertId();
        // status code
        $this->code = 201;
        // created resource
        $this->headers['Location'] = '/todo?id=' . $id;

        return $this;
    }

    /**
     * @Transactional
     */
    public function onPut(int $id, string $todo) : ResourceObject
    {
        $this->db->update(
            'todo',
            ['todo' => $todo],
            ['id' => (int) $id]
        );
        $this->headers['Location'] = '/todo/?id=' . $id;
        // status code
        $this->code = 204;

        $this->body = (string) $this->onGet($id);

        return $this;
    }
}

アノテーションに注目してください。クラスに付いている@CacheableはこのリソースのGETメソッドがキャッシュ可能なことを示しています。OnPostonPut@Transactionalはデータベースアクセスのトランザクションを示し、onPost

POSTしてみましょう。

201 Created
Location: /todo?id=1

{
    "id": "1",
    "todo": "shopping",
    "created": "2017-06-04 15:58:03",
    "_links": {
        "self": {
            "href": "/todo?id=1"
        }
    }
}

ステータスコード(201 Created)とLocationヘッダーで新しいリソースが/todo/?id=1に作成された事がわかります。RFC7231 Section-6.3.2 日本語訳

@ReturnCreatedResourceとアノテートされているのでボディに作成されたリソースを返します。

次にこのリソースをGETします。

php bootstrap/api.php get '/todo?id=1'
200 OK
ETag: 2527085682
Last-Modified: Sun, 04 Jun 2017 15:23:39 GMT
content-type: application/hal+json

{
    "id": "1",
    "todo": "shopping",
    "created": "2017-06-04 15:58:03",
    "_links": {
        "self": {
            "href": "/todo?id=1"
        }
    }
}

ハイパーメディアAPIの完成です!

次にAPIサーバーを立ち上げます。

php -S 127.0.0.1:8081 bootstrap/api.php

今度はcurlコマンドでGETしてみましょう。

curl -i 'http://127.0.0.1:8081/todo?id=1'
HTTP/1.1 200 OK
Host: 127.0.0.1:8081
Date: Sun, 04 Jun 2017 18:02:55 +0200
Connection: close
X-Powered-By: PHP/7.1.4
ETag: 2527085682
Last-Modified: Sun, 04 Jun 2017 16:02:55 GMT
content-type: application/hal+json

{
    "id": "1",
    "todo": "shopping",
    "created": "2017-06-04 15:58:03",
    "_links": {
        "self": {
            "href": "/todo?id=1"
        }
    }
}

何回かリクエストしてLast-Modifiedの日付が変わらないことを確認しましょう。この時onGetメソッド内は実行されていません。試しにメソッド内でechoなどを追加して確認してみましょう。

次にPUTメソッドでこのリソースを変更します。

curl -i http://127.0.0.1:8081/todo -X PUT -d "id=1&todo=think"

Content-Type ヘッダーを使ってJSONでも指定することができます。

curl -i http://127.0.0.1:8081/todo -X PUT -H 'Content-Type: application/json' -d '{"id": "1", "todo":"think" }'

再度GETを行うとLast-Modifiedが変わっているのが確認できます。

curl -i 'http://127.0.0.1:8081/todo?id=1'

このLast-Modifiedの日付は@Cacheableで提供されるものです。 アプリケーションが管理したり、データベースのカラムを用意したりする必要はありません。

@Cacheableを使うと、リソースコンテンツは書き込み用のデータベースとは違うリソースの保存専用の「クエリーリポジトリ」で管理され、データの更新やEtagLast-Modifiedのヘッダーの付加が透過的に行われます。

アプリケーションのインポート

BEAR.Sundayで作られたリソースは再利用性に優れています。 他のアプリケーションのリソースを利用してみましょう。

ここではチュートリアルのためにmy-vendorに新規でアプリケーションを作成して手動でオートローダーを設定します。 (通常はアプリケーションをパッケージとして利用します)

mkdir my-vendor
cd my-vendor
composer create-project bear/skeleton Acme.Blog ~1.0@dev

composer.jsonautoloadのセクションにAcme\\Blogを追加します。


"autoload": {
    "psr-4": {
        "MyVendor\\Weekday\\": "src/",
        "Acme\\Blog\\": "my-vendor/Acme.Blog/src/"
    }
},

autoloadをダンプします。

composer dump-autoload

これでAcme\Blogアプリケーションが配置できました。

次にアプリケーションをインポートするためにsrc/Module/AppModule.phpImportAppModuleを上書き(override)インストールします。

use BEAR\Resource\Module\ImportAppModule;
use BEAR\Resource\ImportApp;
use BEAR\Package\Context;

$importConfig = [
    new ImportApp('blog', 'Acme\Blog', 'prod-hal-app') // ホスト, 名前, コンテキスト
];
$this->override(new ImportAppModule($importConfig , Context::class));

これはAcme\Blogアプリケーションをprod-hal-appコンテキストで作成したリソースをblogというホストで使用することができます。

src/Resource/App/Import.phpにImportリソースを作成して確かめてみましょう。

<?php
namespace MyVendor\Weekday\Resource\App;

use BEAR\Resource\ResourceObject;
use BEAR\Sunday\Inject\ResourceInject;

class Import extends ResourceObject
{
    use ResourceInject;

    public function onGet()
    {
        $this['blog'] = $this->resource->uri('page://blog/index')['greeting'];

        return $this;
    }
}

($this->resource->uri('page://blog/index')['greeting'];$this->resource->get->uri('page://blog/index')->eager->request()->body['greeting']と同じです。)

page://blog/indexリソースがblogに代入されているはずです。@Embedも同様に使えます。

php bootstrap/api.php get /import
200 OK
content-type: application/hal+json

{
    "blog": "Hello BEAR.Sunday",
    "_links": {
        "self": {
            "href": "/import"
        }
    }
}

他のアプリケーションのリソースを利用することができました!データ取得をHTTP越しにする必要もありません。

合成されたアプリケーションも他からみたら1つのアプリケーションの1つのレイヤーです。 レイヤードシステムはRESTの特徴の1つです。

次にBEAR.Sundayでは無いシステムからこのリソースを利用してみましょう。 bin/test.phpを作成します。

<?php
use BEAR\Package\Bootstrap;

require __DIR__ . '/autoload.php';

$app = (new Bootstrap)->getApp('MyVendor\Weekday', 'prod-hal-app');
echo $app->resource->uri('app://self/import')['blog'] . PHP_EOL;

試してみます。

php bint/test.php
Hello BEAR.Sunday

このようにBEAR.Sundayで作られたリソースは他のCMSやフレームワークからも簡単に再利用することができます。

Because everything is a resource

情報の識別子URI、統一されたインターフェイス、ステートテレスなアクセス、強力なキャッシュシステム、ハイパーリンク、レイヤードシステム、自己記述性。 BEAR.SundayアプリケーションのリソースはこれらのRESTの特徴を備えたもので、再利用性に優れています。

異なるアプリケーションの情報もハイパーリンクで接続することができ、他のCMSやフレームワークからの利用やAPIサイトにすることも容易です。 リソースの値と表現は分離されていて、Webページですら他のアプリケーションのAPIになることができます。