— y2sunlight 2020-07-29

Apricot ドキュメント に戻る

目次

• Apricot 特徴と概要
• Apricot 配置と構成
• Apricot ログとエラー処理
• Apricot リクエストとレスポンス
• Apricot フロントエンド
• Apricot データベース
• Apricot モデルとサービス
• Apricot ミドルウェア
• Apricot コントローラ
• Apricot バリデーション
• Apricot サービスプロバイダー
• Apricot ユーザ認証
• Apricot ユーティリティ

ロギングは、monologをラップした Apricot\Log シングルトンが担当します。機能的には monolog と同じですが、PSR-3に従って使います。

使用法: Log::{メソッド}

使用例:

use Apricot\Log;
Log::exception('error',$e);

ロギングには以下の設定ファイルが存在します。

/your-project/config/setting

monolog.setting.php

<?php
/**
 * This file contains Monolog settings.
 */
return
[
    'name' => env('LOG_NAME',env('APP_NAME')),
    'path' => env('LOG_PATH',var_dir('logs')),
    'level'=> env('LOG_LEVEL','debug'),
    'max_files'=> 0,
];

• name — ログの名前 (初期設定は、環境変数APP_NAME（無ければAPP_NAME）の値)
• path — ログの出力パス (初期設定は、var/logs/)
• level — ログの出力レベル (初期設定は、'debug')
• max_files — ログファイルの最大保存数 (初期設定は、0(無制限))

Apricotではオンサイトでのデバッグ出力機能を実現するために、php-debugbarを採用しています。そして、Apricotのコアでは、php-debugbarが提供している \DebugBar\StandardDebugBar クラスをカスタマイズした Apricot\Derivations\StandardDebugBar を作り、この機能をアプリケーションに提供しています。

DebugBar クラスはカスタマイズされたStandardDebugBarをラップしたシングルトンで、アプリケーションにデバック出力機能を提供しています。

使用法: DebugBar::{メソッド}

こららのメソッドの内、renderHead() と render() はHTMLテンプレートで使用され、ブラウザ上にデバッグ出力をレンダリングします。また、getCollector() は以下で示す Debugクラスの生成で使用されます。

Debug クラスは、実際にデバッグ出力を行うクラスです。機能的にはDebugBarのコレクター( DataCollectorInterface )と同じですが、ロギングと同様にPSR-3に従って以下のように使います。以下の関数は基本的に var_dump() と同じように変数の内容をダンプします (これらの関数の違いは単に出力レベルが付いているだけです)。Debug::debug($this) とすれば自分のメンバ変数が全てダンプされます。

使用法: Debug::{メソッド}

使用例:

use Apricot\Debug;
Debug::debug($this);

デバッグ出力には以下の設定ファイルが存在します。

/your-project/config/setting

debugbar.setting.php

<?php
/**
 * This file contains DebugBer settings.
 */
return
[
    'debug' => env('APP_DEBUG',false),
    'renderer' => [
        'auto_assets'=>true,
        'base_url' => url('resources/debugbar'),
        'base_path' => public_dir('resources/debugbar'),
        'initialize' => true,
        'stacked_data' => true,
    ],
];

debug はデバッグ出力の有効性を指定するブール値です。この値が真の場合、デバッグ出力が有効になります。初期設定は環境変数 APP_DEBUG と同じ値です。

renderer 要素には以下の子要素があります。

• auto_assets — 公開用リソースファイルの自動作成を指定します。
• base_url — DebugBarの公開用リソースのURLを指定します。
• base_path — DebugBarの公開用リソースのサーバ内ディレクトリを指定します。
• initialize — TODO: 初期化コードをレンダリングするか否かを指定します。(初期設定はtrue)
• stacked_data — TODO: スタックデータをレンダリングするか否かを指定します。(初期設定はtrue)

TODO:

auto_assets が true の場合、アプリケーションの初期化時に auto_assets が falseの場合、・・・

TODO:

Apricotでは例外ハンドラーとしてWhoopsを使います。コントローラで捕捉されなかった例外は、最終的にこの例外ハンドラーで捕捉するので、これは集約例外ハンドラーと呼ばれます。

集約例外ハンドラーの動作にはデバッグモードと本番モードがあります。

• デバッグモード — ログ出力して、例外内容とスタックトレースを表示する
• 本番モード — ログ出力して、利用者向けのエラーページを表示する

これらの動作をカスタマイズするには、以下のWhoopsのセットアップファイルを変更して下さい。

セットアップファイル：

/your-project/config/setup/whoops.setup.php

例外ハンドラーには以下の設定ファイルが存在します。

/your-project/config/setting

whoops.setting.php

<?php
/**
 * This file contains Whoops settings.
 */
return
[
    'debug' => env('APP_DEBUG',false),
    'controller' => \App\Exceptions\UncaughtExceptionHandler::class,
    'action' => 'render',
];

• debug — デバッグモードの場合 true (初期設定は、環境変数APP_DEBUGの値。無ければfalse)
• controller — 集約例外コントローラクラスを指定する (次項参照)
• action — 集約例外コントローラのアクションメソッド名を指定する (次項参照)

本番モードで集約例外ハンドラーから呼び出されるコントローラを集約例外コントローラと呼びます。上述の whoops.setting.php での設定に従い、例外発生時に UncaughtExceptionHandler クラスの render() メソッドが実行されてエラーページを表示します。

初期実装されている集約例外コントローラでは、例外の種類に応じてHTTPステータスコードを以下のように設定します。

• CSRFエラーなどの TokenMismatchException( トークンエラー )は419( Page Expired )に設定
• HttpException( ボイラープレート abort() などよるHTTP例外 )はそのステータスコードを使用
• その他の例外は 500( Internal Server Error )に設定

集約例外コントローラは以下に配置されています。必要に応じてカスタマイズできます。

/your-project/app/Exceptions/UncaughtExceptionHandler.php

Exceptionを継承した２つの例外クラスがあります。

• Apricot\Exceptions\HttpException
  HTTP例外(HTTPステータスコード400番台,500番台)
• Apricot\Exceptions\TokenMismatchException
  トークンミスマッチ例外(CSRFトークンなどの不一致)

abort() 関数は HttpException をスローするボイラープレートです。通常はこの例外が発生すると集約例外コントローラが補足してエラーページを表示します。以下のように使います。

abort(400);

abort() は以下のように実装されています。

/**
 * Throws an HTTP exception.
 *
 * @param int $code
 * @param string $message
 * @throws \Apricot\Exceptions\HttpException
 */
function abort(int $code, string $message=null)
{
    throw new Apricot\Exceptions\HttpException($code, $message);
}

App\Exceptions\ApplicationException はアプリで発生する例外クラスのベースクラスで、Exceptionクラス から派生しています。そして、ApplicationExceptionから派生した以下のクラスがあります。

• App\Exceptions\OptimissticLockException　
  楽観的ロック例外

エラーバッグ( Apricot\Foundation\ErrorBag )は、入力エラーなどの業務的なエラー(例外でないエラー)の為のクラスです。

ErrorBag には名前を付けることができます( self::DEFAULT_NAME='error' )。バッグ内のエラーはキー付きの連想配列で保存されています。ErrorBagには以下のメソッドがあります。

エラーバッグはIteratorAggregateインターフェースを実装してるのでforeach()などのIteratorを使用した構文が使用できます。但し、Countable インターフェイス は実装していないので、count関数ではなくErrorBag@countメソッドを使用して下さい。

バリデーションエラー用の ValidatorErrorBag クラスは、ErrorBag から派生したクラスで、'validator' という名前がついています。バリデーションエラーと他のエラーを区別するには、この名前を使用して下さい。