====== Apricot リクエストとレスポンス ======
 --- //[[http://www.y2sunlight.com|y2sunlight]] 2020-07-29//

[[apricot:usage:ja|Apricot ドキュメント に戻る]]

目次

  * [[apricot:usage:ja:features|Apricot 特徴と概要]]
  * [[apricot:usage:ja:config|Apricot 配置と構成]]
  * [[apricot:usage:ja:errors-logging|Apricot ログとエラー処理]]
  * Apricot リクエストとレスポンス
  * [[apricot:usage:ja:frontend|Apricot フロントエンド]]
  * [[apricot:usage:ja:database|Apricot データベース]]
  * [[apricot:usage:ja:model|Apricot モデルとサービス]]
  * [[apricot:usage:ja:middleware|Apricot ミドルウェア]]
  * [[apricot:usage:ja:controller|Apricot コントローラ]]
  * [[apricot:usage:ja:validation|Apricot バリデーション]]
  * [[apricot:usage:ja:provider|Apricot サービスプロバイダー]]
  * [[apricot:usage:ja:authentication|Apricot ユーザ認証]]
  * [[apricot:usage:ja:utility|Apricot ユーティリティ]]

----

===== リクエスト =====

Apricotのリクエストクラスは、PHPのスーパーグローバル変数を個別にカプセル化したシングルトンです。リクエスト取得用に以下のシングルトンがあります：

  * Input --- フォーム送信データ(GET変数またはPOST変数：methodに依存)
  * QueryString --- クエリ文字列(GET変数)
  * Session --- SESSION変数
  * Flash --- １回限り有効なSESSION変数
  * Cookie --- COOKIE変数

これらはシングルトンなので、アプリケーションのどこからでもリクエストを取得することができます。

\\

==== Inputクラス ====

Inputクラスはフォームの送信データを取得するシングルトンで、methodに従って、$_GETまたは$_POSTから生成されます。Inputクラスは後述のQueryStringクラスは同じく ''Apricot\Foundation\SimpleInput'' クラスをシングルトンにしたものです。

使用法: ** Input::{メソッド} **

^メソッド^機能^
|bool has(string $key)|キー指定よる入力データの存在確認|
|string get(string $key, string $default = null)|キー指定よる入力データの取得|
|array all()|全ての入力データの取得|
|array only(array<nowiki>|</nowiki>mixed $keys)|必要入力データのみの取得|
|array except(array<nowiki>|</nowiki>mixed $keys)|不要なものを除く入力データの取得|
|set(string $key, string $vale)|入力データの設定|
|remove(string $key)|入力データの削除|

''all()''は、フォームからの全ての入力値を取得するメソッドです。

<code php>
$inputs = Input::all();
$account = $inputs['account'];
$password = $inputs['password'];
</code>

以下は、上の例と同じ結果になります。''get()'' は第２引数にデフォルト値を指定できます。

<code php>
$account = Input::get('account',null);
$password = Input::get('password',null);
</code>

''only()'' は、指定したキーだけの入力値を取得する場合に使用します。

<code php>
$inputs = Input::only('account','password');
</code>

''except()'' は指定したキー以外の入力値を取得する場合に使用します。

<code php>
$inputs = Input::except('password_confirmation');
</code>

バリデーションなどの後で不要になった入力値は、''remove()'' で削除して次の処理に進みます。

<code php>
Input::remove('password_confirmation');
</code>

\\

==== QueryStringクラス ====

QueryStringクラスはクエリ文字列を取得する為のシングルトンです。このクラスは''Apricot\Foundation\SimpleInput'' クラスをシングルトンにしたもので、$_GETから生成します。

使用法: ** QueryString::{メソッド} **

^メソッド^機能^
|bool has(string $key)|キー指定よる入力データの存在確認|
|string get(string $key, string $default = null)|キー指定よる入力データの取得|
|array all()|全ての入力データの取得|
|array only(array<nowiki>|</nowiki>mixed $keys)|必要入力データのみの取得|
|array except(array<nowiki>|</nowiki>mixed $keys)|不要なものを除く入力データの取得|
|set(string $key, string $vale)|入力データの設定|
|remove(string $key)|入力データの削除|

使用例は上のInputシングルトンを同じです。

\\

==== Sessionクラス ====

Sessionクラスはセッション変数を設定及び取得をするシングルトンです。このクラスは ''Apricot\Foundation\SimpleSession'' クラスをシングルトンにしたもので、$_SESSIONから生成します。Sessionシングルトン後述するフラッシュデータを包含しています。

使用法: ** Session::{メソッド} **

^メソッド^機能^
|start()|セッションの開始|
|isStarted():bool|セッションが開始されているか否かの判定|
|has(string $key):bool|セッション変数の存在確認|
|get(string $key, $default = null)|セッション変数の取得|
|set(string $key, $value)|セッション変数の設定|
|remove(string $key)|セッション変数の削除|
|clear()|セッション変数のクリア|
|destroy()|セッションの破棄|
|flash():SimpleFlash|フラッシュデータの取得|

使用例：
<code php>
// 指定したデータがセッションに存在するかを調べる。
if (Session::has('key')) {
    // 存在する
}

// 指定したデータをセッションから取得する。第２引数はデフォルト値です。
$value = Session::get('key', 'default');

// セッションへデータを保存する。
Session::set('key', 'value');

// 指定したデータをセッションから削除する
Session::remove('key');
</code>

''start()'' メソッドはフレームワークによってアプリケーション初期化時に呼び出されます。

''clear()'' メソッドは $_SESSIONだけをクリアします。''destroy()'' メソッドは 内部的にclear() メソッドとPHPのsession_destroy()を呼び出して、現在のセッションに関連づけられたすべてのデータを完全に破棄し、さらに、現在のセッションIDもクッキーから削除します。通常、destroy() メソッドは フレームワークによってログオフ時に呼びされます。

''flash()'' メソッドは後述のFlashシングルトンで使用されます。通常、フラッシュデータの操作にはFlashシングルトンを使用します。

\\

=== 設定ファイル ===

セッションには以下の設定ファイルが存在します。

{{fa>folder-open-o}} ** /your-project/config/setting **
<code php session.setting.php>
<?php
/**
 * This file contains session settings.
 */
return
[
    'name' => 'SID'.substr(md5(env('APP_SECRET', env('APP_NAME'))),0,16),
    'ini' =>[
        'gc_maxlifetime' => null,   /* default: 1440[sec] */
        'gc_probability' => null,   /* default: 1         */
        'gc_divisor' => null,       /* default: 100       */
        'cookie_lifetime' => null,  /* default: 0[sec]    */
    ],
];
</code>

  * name --- セッション名(初期設定値は環境変数APP_SECRETを使って設定します)
  * ini.gc_maxlifetime --- サーバに保存されるセッション変数の有効期間(デフォルト値は1440[秒])
  * ini.gc_probability --- [[https://www.php.net/manual/ja/session.configuration.php#ini.session.gc-probability|PHPのマニュアル]]を参照して下さい(既定値は1)
  * ini.gc_divisor ---  [[https://www.php.net/manual/ja/session.configuration.php#ini.session.gc-divisor|PHPのマニュアル]]を参照して下さい(デフォルト値は100)
  * ini.cookie_lifetime --- セッションクッキーの有効期間(デフォルト0ではブラウザを閉じたらセッションは破棄されます)

\\

==== Flashクラス ====

フラッシュとは、セッション内で一回限りだけ有効な[[#Session|セッション]]変数（次の画面の遷移のときまで保存される変数）のことです。Flashクラスはフラッシュ変数の設定及び取得を行うシングルトンで、''Apricot\Foundation\SimpleFlash'' クラスから作ります。

使用法: ** Flash::{メソッド} **

^メソッド^機能^
|has(string $key):bool|フラッシュ変数の存在確認|
|get(string $key, $default = null)|フラッシュ変数の取得|
|set(string $key, $value)|フラッシュ変数の設定|
|remove(string $key)|フラッシュ変数の削除|
|clear()|フラッシュ変数のクリア|

使用例：
<code php>
// 指定したデータがフラッシュに存在するかを調べる。
if (Flash::has('key')) {
    // 存在する
}

// 指定したデータをフラッシュから取得する。第２引数はデフォルト値です。
$value = Flash::get('key', 'default');

// フラッシュへデータを保存する。
Flash::set('key', 'value');

// 指定したデータをフラッシュから削除する
Flash::remove('key');

// フラッシュをクリアする
Flash::clear();
</code>

=== フレームワークが使用するFlashデータ ===

以下のフラッシュ・キーはフレームワークで使用しています。

^キー^型^内容^
|_old_inputs|array|前回の入力データ|
|_old_path|string|前回のURIパス|
|errors|ErrorBag|エラーバッグ|

\\

==== Cookieクラス ====

Cookieクラスはクッキーの設定及び取得を行うシングルトンで、''Apricot\Foundation\SimpleCookie'' クラスを使って実装します。

使用法: ** Cookie::{メソッド} **

^メソッド^機能^
|has(string $key):bool|クッキーの存在確認|
|get(string $key, $default = null)|クッキーの取得|
|set(string $key, string $value, int $expires_sec=0):bool|クッキーの設定(有効期間付き)|
|forever(string $key, string $value):bool|クッキーの設定(永続的)|
|remove(string $key)|クッキーの削除|

使用例：
<code php>
// 指定したデータがクッキーに存在するかを調べる。
if (Cookie::has('key')) {
    // 存在する
}

// 指定したデータをクッキーから取得する。第２引数はデフォルト値です。
$value = Cookie::get('key', 'default');

// クッキーへデータを１日間だけ保存する。第３引数は有効期間[秒]です。
Cookie::set('key', 'value', 24*60*60);

// クッキーへデータを永続的に保存する。
Cookie::forever('key', 'value');

// 指定したデータをクッキーから削除する。
Cookie::remove('key');
</code>

''set()'' メソッドの第３引数を省略した場合は、デフォルト値の0が設定されます。この場合はセッションクッキーとなり、セッションが終了すると保存したデータは消えます。''forever()'' メソッドは永続的にクッキーを保存しますが、その期間は設定ファイル( cookie.setting.php )の ''forever'' によって決まります。

\\

=== 設定ファイル ===

クッキーには以下の設定ファイルが存在します。

{{fa>folder-open-o}} ** /your-project/config/setting **
<code php cookie.setting.php>
<?php
/**
 * This file contains cookie settings.
 */
return
[
    'path' => '',
    'domain' => '',
    'secure' => FALSE,
    'httponly' => FALSE,
    'forever' => 365*24*60*60,
];
</code>

  * path --- ドメイン上のクッキーが有効なパス(デフォルト値はカレントパス:即ち公開パスpublic)
  * domain --- クッキーが有効なドメイン(デフォルト値はカレントURLのドメイン)
  * secure --- TRUEを設定すると、セキュアな接続が存在する場合にのみクッキーを設定します
  * httponly --- TRUEを設定すると、HTTPを通してのみクッキーを設定します
  * forever --- 永続的クッキーの実際の保存期間を設定します(デフォルト値は365日)

> path から httponly までの設定値の詳細は、PHPマニュアルの[[https://www.php.net/manual/ja/function.setcookie.php|setcookie]]を参照して下さい。

\\

==== ボイラープレート ====

リクエスト取得用のボイラープレートには以下の関数があります。input()からcookie()までは、それぞれのリクエスト変数を取得する関数で、HTMLテンプレートでよく使われるます。inputLabels()はInputクラスからバリデーションの項目名を取得するのに便利な関数です。

^ヘルパー関数^機能^
|input\\ (string $key, $default=null):string|フォームデータを取得|
|queryString\\ (string $key, $default=null):string|クエリ文字列を取得|
|session\\ (string $key, $default=null):mixed|セッション変数を取得|
|flash\\ (string $key, $default=null):mixed|フラッシュ変数を取得|
|cookie\\ (string $key, $default=null):string|クッキー変数を取得|
|inputLabels\\ (string $message_key):array|フォームデータのラベル配列を取得します|


\\

===== レスポンス =====
==== Responseクラス ====

Responseクラスはレスポンスのベースクラスで、その目的はHTMLヘッダーとフラッシュデータの管理です。後述の RenderResponse(レンダリング用) と RedirectResponse(リダイレクト用) はResponseクラスから派生します。Responseクラスは以下のメソッドを持ちます。

^メソッド^機能^
|addHeader($headers):Response|HTMLヘッダーの追加|
|hasFlash(string $key):bool|フラッシュデータの存在確認|
|addFlash(string $key, $value):Response|フラッシュデータの追加|
|commit(int $response_code=null)|レスポンスの確定|

\\

==== RenderResponseクラス ====

RenderResponseクラスはResponseクラスから派生します。HTMLレンダリングを行うレスポンス用のクラスで、以下のメソッドを持ちます。addHeader()などのResponseクラスのメソッドも使用できます。

^メソッド^機能^
|<nowiki>__</nowiki>construct(string $html=null)|RenderResponseの生成|
|setHtml(string $html=null):RenderResponse|HTMLテキストの設定|
|commit(int $response_code=null)|レスポンスの確定|

アプリケーションでは、直接RenderResponseクラスを使うのではなく、後述する render() 関数を使用します。

\\

==== RedirectResponseクラス ====

RedirectResponseクラスはResponseクラスから派生したリダイレクト用のクラスです。リダイレクトではフラッシュデータを使ってリダイレクト先のページにデータを送ることが多いので、フラッシュ用のメソッドが追加されています。RedirectResponseクラスは以下のメソッドを持ちます。addHeader()などのResponseクラスのメソッドも使用できます。

^メソッド^機能^
|<nowiki>__</nowiki>construct(string $url)|RedirectResponseの生成|
|with(string $key, $value):RedirectResponse|フラッシュデータの追加|
|withInputs():RedirectResponse|入力データをフラッシュに追加する|
|withErrors(ErrorBag $errorBag):RedirectResponse|エラーバッグをフラッシュに追加する|
|withOldErrors():RedirectResponse|前回のエラーバッグを次のフラッシュに転送する|

以下は、RedirectResponseクラスで使用するフラッシュデータです。_old_inputs は withInputs()で、errorsは withErrors() と withOldErrors()で使用されます。

^キー^型^内容^
|_old_inputs|array|前回の入力データ|
|_old_path|string|前回のURIパス|
|errors|ErrorBag|エラーバッグ|

アプリケーションでは、直接RedirectResponseクラスを使うのではなく、後述する redirect() 関数を使用します。

\\

==== ボイラープレート ====

レスポンス処理用のボイラープレートには以下の関数があります。render()とredirect()はコントローラアクションで、その他はHTMLテンプレートでよく使われる関数です。

{{tablelayout?colwidth="350px"}}
^ヘルパー関数^機能^
|render(string $view=null, array $variables=[])\\ :RenderResponse|RenderResponseの生成 \\ テンプレート名とテンプレート変数を指定します|
|redirect(string $url):RedirectResponse|RedirectResponseの生成\\ リダイレクトURLを指定します|
|old(string $key, $default = null):string|キーを指定して前回の入力値を取得します|
|back():string|前回のURIを取得します|
|errors():ErrorBag|前回のエラーバッグを取得します|

''render()'' は、テンプレート名(string)とテンプレート変数(array)を指定してHTMLをレンダリングしてRenderResponseオブジェクトを返す関数です。テンプレートについては、[[apricot:usage:ja:frontend#HTMLテンプレート]]を参照して下さい。以下の例では、ユーザモデルで全件検索した結果をテンプレート変数としてユーザ一覧を表示しています。

<code php>
/** index action */
public function index()
{
    $users = $this->user->findAll();
    return render("user.index", ["users"=>$users]);
}
</code>

以下は ''redirect()'' と ''back()'' の典型的な使用例です。フォーム送信を受け取るアクションでは、通常、バリデーションに失敗した場合は、前回の入力値とエラー内容と共に送信元のページに戻ります。以下の例では、redirect() の引数に back() で取得した前回のURIを指定し、RedirectResponse オブジェクトを得た後に、withInputs() と withErrors() メソッドを使って前回の入力値とエラー内容をフラッシュを使用してリダイレクト先に渡しています。

<code php>
/** update action */
public function update()
{
    // バリデーション結果に応じてリダイレクトする
    if ($errorBag)
    {
        // 失敗した時
        return redirect(back())->withInputs()->withErrors($errorBag);
    }

    // 成功した時
    return redirect(route("user/{$id}/edit"));
}
</code>

''old()'' と''errors()'' はBladeテンプレートで良く使用される関数です。old() はフラッシュで渡された前回の入力値を取得する関数で、第２引数はデフォルト値です。以下はユーザ名の入力フィールドの例です。このように、データ編集ページの場合、通常は第２引数にはモデルから取得したテンプレート変数を渡します。

<code php>
<input type="text" name="account" id="account" value="{{old('account',$user->account)}}">
</code>

''errors()'' は、前ページからフラッシュで渡された[[apricot:usage:ja:errors-logging#エラーバッグ]]を取得する関数です。以下の例では、エラーバッグのcount()メソッドでエラーの数を取得し、エラーがあれば、その内容を出力しています。エラーバッグは[[https://www.php.net/manual/ja/class.iteratoraggregate.php|IteratorAggregateインターフェース]]を実装してるのでforeach()などのIteratorを使用した構文が使用できます。

<code php>
@if($errors->count())
    @foreach($errors as $key=>$value)
        <div class="alert">{{$value}}</div>
    @endforeach
@endif
</code>

\\