2015年7月6日月曜日

Responder Module:フレームワークを分割して考える

作ってきたTuum/Respondが何なのか、良い説明を思いついたので書いてみます。

フレームワークの機能


最初に、フレームワークの機能を次のように分割してみます。

  1. ブートストラップとアプリ構築。
  2. ルーティングとディスパッチ。
  3. モデル/ドメイン実行。
  4. ビューなどのリスポンス構成。

この中で、最も重要と思うのが(3)のドメイン部分。これこそがプロジェクトの本質で、一番時間を使って開発したい部分。

フルスタック・フレームワークとは、(3)以外のほぼすべての機能を使いやすい形にまとめあげておくことで、ドメインの開発に集中するためのものだと考えてます。

一方、俗にいう「マイクロフレームワーク」というのがあります。これは、(1)と(2)の部分を担っていると考えるとスッキリします。返信するのが簡単なJSONであれば、複雑なビューなどを省くことで、コードが簡潔になります。

Responder Module


こんなふうに分割してみると、この(4)だけをターゲットにしたミニフレームワークみたいなものがあってもいいのでは?

と考えて、この(4)の機能の部分を作ってみたのが「Tuum/Respond」というモジュールです。

ついでに、この部分に「Responder Module」と名前をつけてみました。もう名前があるのかもしれないけれど、見つからなかったので、適当に呼んだだけです。

Tuum/Respond


Tuum/Respondの使い方としては、例えばSlim frameworkのようなマイクロフレームワークと一緒に使うとかを想定してます。

レスポンスの種類


想定しているレスポンスの種類です。

  • View:HTMLなどのコンテンツのあるレスポンス。
  • Redirect:別URIへのリダイレクト。
  • Error:エラー。コンテンツがある場合もある。

それぞれHTTPステータスの200番台、300番台、そして400と500番台に対応します。

どのレスポンスを返す場合でも同じAPIが使えます。更には、リダイレクトした次のビューにデータを渡す場合でも、同じAPIになります。つまり、こんなコード。

$app = new App(); // some micro-framework app. 

// redirects to /jumped.
$app->get('/jumper', function($request, $response) {
    return Respond::redirect($request, $response)
        ->withMessage('bad input!') // <- set up info.
        ->withInputData(['some' => 'value'])
        ->withInputErrors(['some' => 'bad value'])
        ->toPath('/jumped');
    });

// ...and this is jumped.
$app->get('/jumped', function($request, $response) {
    return Respond::view($request, $response)
        ->asView('template'); // with the 'welcome!' message.
});

どこかで見たコードですね。

必要なサービスとインターフェース


Tuum/Respondの全ての機能を使うには、外部サービスが必要です。全てのサービスにはインターフェースが定義されています。

  • ViewStreamInterface:
    ビュー(テンプレート展開)用API。PSR7のStreamInterfaceを継承していて、内部でテンプレートを展開。
  • SessionStorageInterface
    セッションおよびフラッシュ用API。ほぼAura.Sessionのsegmentと一致してます。
  • ErrorViewInterface
    エラー表示用API。

これらのサービスを実装して適宜設定することになります。

もう少し細かい説明は前にブログに書いてあるので、そちらも参考にしてみてください。

2015年7月1日水曜日

汎用ページネーション(PSR7も使えます)

汎用ページネーションのパッケージを作ってみた。
一応、PSR7のServerRequestInterfaceも使えます。

セッションを使って、ページ番号やフォーム入力を覚えるのが特徴。簡単に最後と同じページを作成できます。

何故作ったのか?


仕事でDoctrine2を採用してみたのだが、いい感じのページネーションがなかったので作ってみた。ただし仕事には間に合わなかったので、実サイトでの実績はないです。

こういうページネーションに、どのぐらい需要があるのかわからないけど、この際なのでパッケージとして作ってみた。

ライセンス:MIT
PSR準拠 :Psr-1、Psr-2、Psr-4

使い方


インストール


composerで。

$ composer require "wscore/pagination"


Pagerオブジェクト


Pagerオブジェクトを最初に作ります。

use WScore\Pagination\Inputs;
use WScore\Pagination\Pager;

// construction
$pager = new Pager(['_limit' => 15]);

// set up pager using Psr-7 ServerRequestInterface.
$pager = $pager->withRequest($request);
// or from global data. 
$pager = $pager->withQuery($_GET, '/find');

次に、データベースへのクエリなどを実行します。callメソッドにクロージャーを渡してください。引数はInputsというクラスのオブジェクトです。

$inputs = $pager->call(
    function(Inputs $inputs) use($pdo) {
        // query the PDO!
        $found = $pdo->prepare("SELECT * FROM tbl WHERE type=? and num>? OFFSET ? LIMIT ?")
            ->execute([
                $inputs->get('type'),
                $inputs->get('num'),
                $inputs->getOffset(),
                $inputs->getLimit(),
            ])
            ->fetchAll();
        $inputs->setList($found);
    });
$found = $inputs->getList();
$type  = $inputs->get('type');

後は、クロージャー内で必要な処理を書き込みます。
Inputsオブジェクトから、オフセットとリミットや、フォームの入力を読み取れます。

HTML出力


最後に、HTMLへの出力は、Paginateというオブジェクトを使います。

use WScore\Pagination\Html\Paginate;

$inputs->paginate(new Paginate());
echo $inputs->__toString();


すると、こんなページネーションが表示されます。


リクエストの仕方

ここが、このパッケージの肝になります。
「_page」を使いこなします。

1.検索条件フォーム


ページネーションを行う場合は、検索条件をフォームで選ぶ場合が多いと思います。その場合は、普通にフォームを作ってください。

<form>
<input type="text" name="type" />
<input type="integer" name="num" />
<input type="submit" />
</form>

注意:_pageは使わないで下さい。
フォームの内容は自動でセッションに登録されます。セッションは事前に走らせておいて下さい。

2.ページの指定


指定するページを表示するには_pageにページ番号を指定します。

GET /find?_page=2

検索に使う条件はセッションに保持されているので、同じ条件でオフセットを替えてクエリを実行できます。

3.最後の検索画面


検索画面を表示する際、_pageにページ番号をなしでGetしてみてください。

GET /find?_page

すると、セッションから最後のページ番号と検索条件を読みだします。

To Do


動くはずですが、実際に使ったことがないのでAPIなど変わるかもしれません。なのでアルファリリースです。

2015年6月12日金曜日

PSR7用のヘルパーとレスポンダー

コツコツとフレームワークを作っていて。
ふと、自分が欲しかったのは、もっと簡単なことじゃないか?と思い直して作ったのがTuum/Http」というパッケージ。

【修正:2015/06/26】
Tuum/Responder」に名前を変更しました。

そもそものスタートとして、SlimやStackPHPの簡潔な構造に憧れたところから始まっている。が、実際に使うとなると、API作るには便利だけれど、普通のウェブサイトを構築するには作業が面倒そうだなぁと。

面倒だと思った部分は、レスポンスを返す部分。たとえば前のページに戻ったり、ついでにメッセージやエラー情報を付加したりという部分。同じような処理が多い割には、細かな設定が必要な気がする。

そこで、この部分だけをパッケージにしてみた。


何をするパッケージなのか



大きくヘルパーとレスポンダーからできている。
大事なのはレスポンダーの方。

ヘルパー

Psr7に足りなさそうな機能をスタティックなメソッドとして提供している。見れば一発、簡単なものばかり。例えば、

$bool = ResponseHelper::isRedirect($response);

はリダイレクトレスポンスかどうかをチェックできる。RequestHelperとResponseHelperの2つがある。

レスポンダー

レスポンスを構築するためのヘルパー。
例えば、別パスにリダイレクトしたり、その際にメッセージを付加できる(単にセッション・フラッシュに登録してるだけだが)。

Redirect::forge($request, $response)->withMessage('welcome!')->toPath('jump/to');

// ...now in the subsequent request to a server...
Respond::forge($request, $response)->asView('template'); // with the 'welcome!' message.

次のリクエストの際に、前のメッセージが自動でビューに入ってくる。メソッド名がどこかで見たことのあるのは愛嬌。使いやすいと思ったので。

レスポンダーとしては、RespondRedirect、そしてErrorがある。それぞれ、ビューを返す、リダイレクトを返す、エラーページを返す。

使うのに必要なこと:サービス


レスポンダーの機能を実現するために、ビューやセッションなどのサービスを使っている。これを作っておいて、レスポンダーに渡す必要がある。

セッション用インターフェース

セッションのフラッシュを使ってリクエスト間のデータを受け渡している。そのためのセッションとしてSessionStorageInterfaceという形で定義した。

と行っても、実際はAura.SessionのSegmentと同一のAPI。これを使うのが前提みたいになっている。

use Aura\Session\SessionFactory;

$factory = new SessionFactory();
$session = $factory->newInstance($_COOKIES);
$segment = $session->getSegment('some-name');

ここで作った$segmentがSessionStorageInterfaceと同じオブジェクトになる。

これを$requestに設定する。
use Tuum\Http\RequestHelper;
$request = RequestHelper::withSessionMgr($request, $segment);

あるいは、後で書くようにコンテナに設定しておく方法もある。

ビュー用インターフェース

HTMLを返すにはテンプレートを使ったビューを使いたい。そのために、ビューを展開するViewStreamInterfaceを定義してみた。

テンプレートを展開できるStreamとして扱う。

ViewDataクラス

これは実際のクラス。
ビューやリクエスト間でデータをやりとりするためのデータ転送用オブジェクト。

ビュー用のクラスはViewDataを理解して、実際のレンダラーに渡す必要がある。


コンテナー用インターフェース

サービスを管理するコンテナ。Container-Interopで定義したインターフェースを使った。これに必要なサービスを登録しておいて、$requestに設定する。

次はセッションを設定する方法。

$app = new Container(); // must implement ContainerInterface
$app->set->(SessionStorageInterface::class, $segment);RequestHelper::withApp($request, $app);




2015年5月24日日曜日

PHPの__invokeメソッドの使いドコロは?

PHPにはクロージャー(無名関数)と、クラスを無名関数のように使えるようになるマジックメソッド、__invoke、というのがある。これに関する雑感。

クロージャーと言うのは便利なもので、プログラムをデータとして扱える。

$hello = function($world) {
  return 'hello ' . $
world;
};
便利なケースを思いつかなかったので、適当に書いたコード。


一方で、__invokeメソッドの使いドコロは何だろう。

自分が思いつくのは、
1.流行りのファンクショナルな言語のように書ける。
2.メソッド名を考えなくても使える。
3.クロージャーの代わりにオブジェクトを使いたい場合に必要。

最初の1.と2.は冗談なので、実際は3.の場合かなと思える。つまり何かの関数の引数としてクロージャーを想定している場合でも、オブジェクトが使える。

でも3.の理由は、クラス自体でのメリットというより、必要だからという感じがする。

あとPHPの問題として、意外なところでコードのパースが悪いところがある。せっかくコンパクトに書けるはずのクロージャーなのに、かえってコードが複雑になってしまう。

class Hello {
  private $hello;
  function __construct($hello) {
    $this->hello = $hello;
  }
  function hello($world) {
    return $this->hello($world); // 動かない!
  }
}

なんで、こんなことを書いてるかって?

いや、1.と2.の理由で__invoke使って見たら、意外と面倒で。一方で感じたメリットは3.しかなかったので。それで__invokeメソッドを使うメリットは他に何があるか?そんなことを思ったのでブログに書いてみた。

自作フレームワークでのミドルウェア設計

自作中のウェブアプリケーションフレームワークではミドルウェアベースで動きます。基本は「StackPHPとミドルウェア」に書いたとおりですが、実際のインターフェースに落とすまでの過程についてまとめてみます。

と、Blogspotでコードを書くのが面倒なのを思い出したので、gistに書いた。

フレームワークの文章としては、もっと簡潔に必要な箇所だけにまとめる必要があるだろうな。

2015年4月3日金曜日

ミドルウェアベースでPSR7を使った自作フレームワーク

相変わらずフレームワークを自作している。勉強になるし、万が一、いいものができたら実際に使ってみたいと思いながら作っている。今までは、勉強がメインだったが、今回は本当に使えそうな感じになってきた。

名前は「TuumPHP」。

作り始めたきっかけ

StackPHPとLaravel


2014年の夏頃、Laravel4.2で開発をしていて、これは楽に開発できるフレームワークだなぁと関心した。ただ自分の仕事だとアップデートについて行くのは難しいと感じていた。一旦作ったら、作り変えない程度の機能追加がたまにある程度で、数年は運用する必要がある。まぁなんとかなると思うけど。

そんな時、ミドルウェアとStackPHPについて調べてみて、これは素晴らしいと。単純な構造を組み合わせることで複雑なアプリを構築することができて、PHPの方向はこれだと思った。こんなエントリをQiitaにアップしている

StackPHPとミドルウェアについて調べてみた

つまり、

  • StackPHPのような簡潔な構造で、
  • Laravelのように開発しやすいくて、
  • データの流れが自然(ファサードとか使わない)、
  • できればバージョンアップもパッケージ別に対応可、

そんなフレームワークがほしいと思った。

ちょいと探したけれど、いいのが見つからず。じゃ、自分で作ってみるか、というのが始まり。

Psr-7の導入


作ってからしばらくして、標準のHTTPリクエストやレスポンスの規格がもうそろそろ完成するという話が流れてきた。Psr-7という規格。しかも不変オブジェクトが使われている、ときいて早速導入して見た。

その時の経験からQiitaに書いたのが、

Psr7を使ってみた(というか不変オブジェクトを初めて使った感想)


TuumPHPの特徴

余り思いつかないので、徒然と書いてみる。

マイクロフレームワーク+ビュー。
つまりSlimやSilexより少し機能が豊富なフレームワーク。モデル側(DB)などは持ってない。

マジックな機能


つまりLaravelから拝借した機能、ということですね。

  • フォームの入力エラーで、フォームにリダイレクトで戻るときに、入力値(withInputs)やバリデーションエラー(withErrors)などを一緒に返せる。
  • フォームに値を表示するときに、リダイレクトの戻り値(withInputs)を簡単に利用できる。
  • APIやメソッド名を参考に。

意外と少なかった。

ミドルウェア


なんでもミドルウェア。

ルーティングもミドルウェアなので、いくつでも追加できる。ルーティングの前のプリ・ルーティングも、ルーティング後のコントローラ内のポスト・ルーティングもできる。

ルーティングの後のディスパッチャーもミドルウェア。これも交換可能。

もちろんコントローラーもミドルウェアの一つ、ので、単純な継承でコントローラークラスを作れる。というか継承する必要は無いはず。

コントローラ内で簡易ルーティングができる。貧者のアノテーション・ルーティングですね。

状態


まだアルファ。
APIも含めて色々と変わる可能性は高い。

独立したコンポーネントを作っていて、こちらはドキュメントとテストはそこそこあるが、フレームワークとしてはドキュメントもテストもほぼ未着手。

その代わり、こんな文章を書いている。フレームワークの使い方ではなくて、どうしてこうなった?の理由を書いたほうが勉強になるかなと思ったから。


今後


すでにZend FrameworkもSlim Framework も次のバージョンでPsr-7でミドルウェアに対応すると表明している。。Laravel 5もすでにミドルウェアベースになっているし、次にはPsr-7を使ってくるのでは無いかと思う。

注目したいのは、今後のPHPで


よく使われるミドルウェアAPI


はどれか、という点。APIが同じなら互換性が高いため、コードやオブジェクトを共通して使える。例えばOAuthとかのクラスを使いまわせるかどうか、というのが大事。

もしフレームワークを自作するなら、APIの目安がついてからのほうがいいと思う。