====== 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:usage:ja:http|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 ユーティリティ

----

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

ボイラープレートは良く使うフレームワークのコードパターンを関数として使用できるようにしたヘルパー関数です。

==== 環境と設定 ====

{{tablelayout?colwidth="250px"}}
^関数^概要^
|env($key, $default = null)|環境変数を返します。|
|app($dot = null, $default=null)|ドット表記キーで指定されたアプリケーション設定の値を返します。|
|app_has($dot = null)|アプリケーション設定キーが存在するかどうかを確認します。|
|config($key, $default = null)|ドット表記キーで指定された構成変数の値を返します。|

''env()'' は、環境変数を取得する関数です。第１引数にはキーを指定して下さい。第２引数はオプションでデフォルト値を指定することができます。環境変数は ''/your-project/.env'' ファイルの中に ''key=value'' の形式で保存されています。詳細は [[apricot:usage:ja:config#環境設定]] を参照して下さい。

<code php>
$value = env('APP_NAME', $default);
</code>

''app()'' は、アプリケーション変数を取得する関数です。第１引数にはドット表記キーを指定します。。第２引数はオプションでデフォルト値を指定することができます。アプリケーション変数は ''/your-project/app.php'' ファイルの中に連想配列で保存されています。詳細は [[apricot:usage:ja:config#appphpファイル|app.phpファイル]] を参照して下さい。

<code php>
$value = app('auth.expires_sec', $default);
</code>

''config()'' は、構成変数を取得する関数です。第１引数にはドット表記キーを指定します。第２引数はオプションでデフォルト値を指定することができます。この設定ファイルは ''/your-project/config/setting'' の下に機能毎に保存されます。構成変数の設定については [[apricot:usage:ja:config#設定管理]] を参照して下さい。

<code php>
$value = config('monolog.level', $default);
</code>

\\

==== 例外 ====

{{tablelayout?colwidth="300px"}}
^関数^概要^
|abort(int $code, string $message=null)|HTTP例外(400,500番台)をスローします|

''abort()'' は、''HttpException'' をスローする関数です。通常はこの例外が発生すると[[apricot:usage:ja:errors-logging#集約例外ハンドラー]]が補足してエラーページを表示します。この関数については「[[apricot:usage:ja:errors-logging#コアの例外クラス]]」を参照して下さい。

<code php>
abort(400);
</code>

\\

==== ディレクトリー ====

{{tablelayout?colwidth="250px"}}
^関数^概要^
|project_dir($path = null):string|プロジェクトディレクトリーまたはその子ディレクトリーの完全パス名を返します。|
|config_dir($path = null):string|configディレクトリーまたはその子ディレクトリーの完全パス名を返します。|
|assets_dir($path = null):string|アセットディレクトリーまたはその子ディレクトリーの完全パス名を返します。|
|var_dir($path = null):string|varディレクトリーまたはその子ディレクトリーの完全パス名を返します。|
|public_dir($path = null):string|パブリックディレクトリーまたはその子ディレクトリーの完全パス名を返します。|

''project_dir()'' は、第１引数が省略された場合、プロジェクトディレクトリーの完全パス名を返します。第１引数にその子ディレクトリーを指定すると、子ディレクトリーまでを含めた完全パス名を返します。

<code php>
$dir = project_dir();       // '/your-project' を返します。
$dir = project_dir('temp'); // '/your-project/temp' を返します。
</code>

他の関数も同様に、Apricotの特定のディレクトリーを、またはその子ディレクトリーの完全パス名を返します。各ディレクトリーに関しては
「[[apricot:usage:ja:config#ディレクトリー構成]]」を参照して下さい。

\\

==== URLとパス ====

{{tablelayout?colwidth="250px"}}
^関数^概要^
|url($path = null):string|アプリケーションのURLまたはその子のURLを返します。|
|url_ver(string $filename)|アプリケーションのバージョンを含むファイルURLを返します。|
|route($path = null):string|ルーティングパスを返します。|

''url()'' は、第１引数が省略された場合、アプリケーションのURLを返します。第１引数にパスを指定すると、パスまでを含めたURLを返します。アプリケーションのURLは、環境変数 ''APP_URL'' から取得されますが、それを設定していない場合は、[[apricot:usage:ja:config#publicディレクトリー]]のURLのパス部分になります。

<code php>
$url = url();     // アプリケーションのURL({your-app-url})を返します。
$url = url('js'); // '{your-app-url}/js' を返します。
$url = url('js/jquery-3.3.1.min.js'); // '{your-app-url}/js/jquery-3.3.1.min.js' を返します。
</code>

''url_ver()'' は、アプリケーションのバージョンを含むファイルURLを返します。URLの末尾にアプリケーションのバージョン番号を付加する点を除いて ''url()'' と同じです。バージョン番号は、環境変数 ''APP_VERSION'' から取得します。この関数は、アセットファイル用のURLを取得する場合に使用して下さい。

<code php>
$url = url('js/main.js'); // '{your-app-url}/js/main.js?v=1.0.0' を返します。
</code>

''route()'' は、第１引数が省略された場合、ルーティングパスのルートを返します。第１引数にサブパスを指定すると、サブパスまでを含めたルーティングパスを返します。ルーティングパスのルートは、[[apricot:usage:ja:config#publicディレクトリー]]のURLのパス部分と同じです。

<code php>
$path = route(); // ルートパス({your-app-path})を返します。
$path = route('User/{$id}/edit'); // '{your-app-path}/User/1/edit' を返します。
</code>

\\

==== アクション ====

{{tablelayout?colwidth="250px"}}
^関数^概要^
|controllerName():string|現在のコントローラー名を返します。|
|actionName():string|現在のアクション名を返します。|

''controllerName()'' と ''actionName()'' は、それぞれ現在のコントローラー名とアクション名を返します。例えば、ユーザコントローラーのindexアクションがインボークされている場合は、以下のような結果になります。

<code php>
$controller = controllerName(); // 'UserController' を返します。
$action = actionName();         // 'index' を返します。
</code>

\\

==== トランスレーション ====

{{tablelayout?colwidth="350px"}}
^関数^概要^
|<nowiki>__</nowiki>($key, $params = [])|翻訳されたメッセージを返します。|
|inputLabels (string $message_key):array|入力変数のラベル配列を返します。|

''<nowiki>__</nowiki>()'' は、各言語用のメッセージを取得する関数です。第１引数にはドット表記キーを指定します。パラメータ付きのメッセージの場合は、第２引数に ''[':param'<nowiki>=></nowiki>'value']'' の形式の連想配列を指定します。詳しくは「[[apricot:usage:ja:frontend#多言語化]]」を参照して下さい。

<code php>
$message = __('messages.home.msg');

// パラメータ付きメッセージの取得
$message = __('messages.home.hello', [':name'=>'Scott']);
</code>

''inputLabels()'' は、入力変数のラベル配列を返します。第１引数には言語メッセージのドット表記キーを指定します。この関数は、バリデーション失敗時のメッセージを作成することを手助けします。詳しくは、「バリデーションの使用例の[[apricot:usage:ja:validation#入力変数のラベリング]]」を参照して下さい。

<code php>
$labels = inputLabels('messages.user.create');
</code>

\\

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

{{tablelayout?colwidth="300px"}}
^関数^機能^
|input (string $key, $default=null)|フォームデータを取得。''Input::get()'' と同じ。|
|queryString (string $key, $default=null)|クエリ文字列を取得取得。''QueryString::get()'' と同じ。|
|session (string $key, $default=null)|セッション変数を取得取得。''Session::get()'' と同じ。|
|flash (string $key, $default=null)|フラッシュ変数を取得取得。''Flash::get()'' と同じ。|
|cookie (string $key, $default=null)|クッキー変数を取得取得。''Cookie::get()'' と同じ。|

''input()'' は、フォームの送信データ(入力変数)を取得する関数です。第１引数には変数のキーを指定します。第２引数はオプションでデフォルト値を指定することができます。

<code php>
$account = input('account');
</code>

他の関数も同様に、第１引数には変数のキーを、第２引数はオプションでデフォルト値を指定することができます。リクエスト変数に関しては 「[[apricot:usage:ja:http#リクエスト]]」を参照して下さい。

\\

==== 前回値 ====

{{tablelayout?colwidth="300px"}}
^関数^概要^
|old(string $key, $default = null):string|キーを指定して前回の入力値を取得します|
|back():string|前回のURIを取得します|
|errors():Apricot\Foundation\ErrorBag|前回のエラーバッグを取得します|

''old()'' は、フラッシュで渡された前回の入力値を取得する関数です。第１引数は入力変数と同じキーを、第２引数はオプションでデフォルト値を指定します。以下はHTMLテンプレート内での ''old()'' の例です。このように、データ編集ページの場合、通常は第２引数にはモデルから取得したテンプレート変数を渡します。

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

''back()'' は、前回のURIを取得する関数です。通常は以下のように ''redirect()'' 関数と共に使用し送信元のページに戻ります。

<code php>
return redirect(back());
</code>

''errors()'' は、前ページからフラッシュで渡された[[apricot:usage:ja:errors-logging#エラーバッグ]]を取得する関数です。以下はHTMLテンプレート内での ''errors()'' の例です。エラーバッグのcount()メソッドでエラーの数を取得し、エラーがあれば、その内容を出力しています。

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

\\

==== レスポンス ====

{{tablelayout?colwidth="400px"}}
^関数^概要^
|render(string $view=null, array $variables=[])\\ :Apricot\Foundation\Response\RenderResponse|RenderResponseを返します。|
|redirect(string $url)\\ :Apricot\Foundation\Response\RedirectResponse|RedirectResponseを返します。|

''render()'' は、テンプレート名(string)とテンプレート変数(array)を指定してHTMLをレンダリングして''RenderResponse''オブジェクトを返す関数です。

<code php>
return render("user.index", ["users"=>$users]);
</code>

''redirect()'' は、リダイレクト先URIを指定して ''RedirectResponse'' オブジェクトを返す関数です。

<code php>
return redirect(route("user/{$id}/edit"));
</code>

これらの関数の詳細は「[[apricot:usage:ja:http#ボイラープレート1|レスポンスのボイラープレート]]」を参照して下さい。

\\