— 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 — 初期化コードをレンダリングするか否かを指定します。(デフォルト値はtrue)
• stacked_data — スタックデータをレンダリングするか否かを指定します。(デフォルト値はtrue)

auto_assets が true の場合、アプリケーションの初期化時に使用するリソースファイルを自動的に公開用ディレクトリーに作成します。auto_assets が falseの場合は、手動でリソースファイルを作成して下さい。base_url と base_path は手動の場合に指定します。

initializeとstacked_dataは、デバッグ出力が有効( 'debug' => true )の場合に効果があり、通常は、true のままで使用して下さい。

設定値の auto_assets がtureの場合は、アプリケーションの初期化時に自動で以下のディレクトリにのアセットファイルが作成されます。

/your-app-path/var/debugbar

auto_assets がfalseの場合は、手動で以下に場所にアセットファイルを配置するように初期設定されています。

/your-app-path/resources/debugbar

デバッグ出力で使用するアセットファイルは、以下のディレクトリーに保存されているので、この下の全てのファイルとディレクリーを上記の場所にコピーして下さい。

/your-project/vender/maximebf/debugbar/src/DebugBar/Resources/

結果的に手動の場合のアセットファイルの配置は以下のようになります：

/your-app-path/resources/debugbar

vendor/
widgets/
debugbar.css
debugbar.js
openhandler.css
openhandler.js
widgets.css
widgets.js

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' という名前がついています。バリデーションエラーと他のエラーを区別するには、この名前を使用して下さい。