====== Apricot 配置と構成 ======
 --- //[[http://www.y2sunlight.com|y2sunlight]] 2020-07-29//

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

目次

  * [[apricot:usage:ja:features|Apricot 特徴と概要]]
  * 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:usage:ja:utility|Apricot ユーティリティ]]

----

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

以下にプロジェクトディレクトリーの構成を示します。

{{fa>folder-open-o}} ** /your-project **
<code>
your-project [プロジェクトディレクトリー]
 |
 ├── app
 ├── assets
 ├── config
 ├── core
 ├── public
 ├── var
 └── vendor
</code>

=== app ディレクトリー===
アプリケーションの本体を配置するディレクトリーで以下サブディレクトリーがあります。

  * ''Controllers'' --- URLと結びついたアクション(メソッド)から構成される
  * ''Exceptions'' --- アプリケーション例外クラスと集約例外コントローラ
  * ''Foundation'' --- コントローラ、モデル、エラーバッグなどのベースクラス
  * ''Helpers'' --- ビューヘルパーなどの共通のユーティリティクラス
  * ''Middleware'' --- アクション起動時の前処理(まはた後処理)を行うミドルウェア
  * ''Models'' --- 通常データベースのテーブル単位で作り、アプリケーションのデータモデル
  * ''Services'' --- サービスクラスを配置する(予約)

=== assets ディレクトリー ===
アプリケーションのリソースを配置し以下サブディレクトリーがあります。

  * ''lang'' --- トランスレーションの為の言語別のメッセージテキスト
  * ''sql'' --- データベース構築の為のSQLファイル
  * ''views'' --- ページを作成するHTMLテンプレート(BladeOneで使用)

=== config ディレクトリー ===
アプリケーションの設定を配置し以下サブディレクトリーがあります。

  * ''setting'' --- 機能別の設定ファイル
  * ''setup'' --- アプリケーション起動時のセットアップファイル

=== core ディレクトリー ===
Apricotのコアクラスを配置します。コアクラスはApricotフレームワークライブラリとして提供され、次の３つの主要な目的があります。

  * アプリケーションの構成管理を提供します。
  * ロギング、例外集約、デバックの機能を提供します。
  * リクエストからレスポンスまでのアプリケーションの標準的な処理方法を提供します。

=== public ディレクトリー ===
公開用のディレクトリーです。ここにApricotのフロントコントローラ( ''index.php'' )があります。

=== var ディレクトリー ===
アプリケーションの次のデータを保存するディレクトリーで以下サブディレクトリーがあります。

  * ''cache'' --- キャッシュファイル
  * ''logs'' --- ログファイル
  * ''db'' --- データベースファイル

=== vendor ディレクトリー ===
Composerが使用する外部ライブラリーの保存ディレクトリーです。

\\

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

''public'' ディレクトリーの下には以下に示すようなディレクトリーとファイルが存在します。

<code>
your-project [プロジェクトディレクトリー]
 |
 ├── public [公開フォルダ]
 |    |
 |    ├── css/        [cssファイル用]
 |    ├── img/        [画像ファイル用]
 |    ├── js/         [JavaScriptファイル用]
 |    ├── var/        [ライブラリリソース用(実行時に配置)]
 |    ├── resources/  [ライブラリリソース用(配布時に配置)]
 |    ├── .htaccess   [Apacheの設定]
 |    └── index.php   [フロントコントローラ]
</code>

Apricot自身のフロントエンドアセットは css, img と js ディレクトリーに配置し、外部ライブラリーのアセットは　var または resources ディレクトリーに配置します。実行時にアセットを作成する場合は var に、配布ファイルとしてアセットを含める場合は、resources を使用します。

\\

==== .htcccess ====

Apricotに含まれている ''.htcccess'' を以下に示します。このファイルの目的は、アプリケーションへの全てのリクエストをフロントコントローラ ''index.php'' で受け取るようにするためです。フロントコントローラはこのリクエストをリクエストルーターへ送り、適切なアクションで処理を行います。

{{fa>folder-open-o}} ** /your-project/public **
<code - .htaccess>
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ index.php [L]
</IfModule>
</code>

この設定では、ApacheのRewriteEngineを有効にして、publicフォルダ下に実在しないファイル及びフォルダに対する全てのリクエストをindex.phpに転送します。詳しくはApacheの[[https://httpd.apache.org/docs/2.4/ja/mod/mod_rewrite.html|マニュアル]]を参照して下さい。

\\

===== アプリケーションの配置 =====

フロントコントローラ ''index.php'' は、以下に示すように、起動後直ぐに公開ディレクトリーとプロジェクトディレクトリーを取得してアプリケーションを初期化します。

{{fa>folder-open-o}} ** /your-project/public **
<code php index.php>
<?php
//-------------------------------------------------------------------
// Autoloader registration
//-------------------------------------------------------------------
require dirname(__DIR__).'/vendor/autoload.php';

//-------------------------------------------------------------------
// Sets the project and pulic path
//-------------------------------------------------------------------
$project_path = dirname(__DIR__);
$public_path = __DIR__;

//-------------------------------------------------------------------
// Initializes the application
//-------------------------------------------------------------------
$application = new Apricot\Application($project_path, $public_path);

...
</code>

このように、デフォルトのindex.php の実装では、公開ディレクトリーとプロジェクトディレクトリーの関係は以下のような親子関係を想定しています。

<code>
your-project [プロジェクトディレクトリー]
 |
 ├── app
 ├── assets
 ├── config
 ├── core
 ├── var
 ├── vendor
 |
 └── public [公開ディレクトリー]
</code>

プロジェクトディレクトリーは公開ディレクトリーからの相対パスで設定することがきでるので、例えば、以下で示すように index.php を変更すれば任意の場所にプロジェクトディレクトリーを配置することができます。


=== 兄弟関係(siblings) ===

<code>
 ┌── your-project [プロジェクトディレクトリー]
 |     |
 |     ├── app
 |     ├── assets
 |     ├── config
 |     ├── core
 |     ├── var
 |     └── vendor
 |
 ├── public [公開ディレクトリー]
 |
</code>

<code php index.php>
$project_path = dirname(__DIR__).'/your-project';
$public_path = __DIR__;
</code>

=== 祖父母孫関係(Grandparent-Grandchild) ===

<code>
your-project [プロジェクトディレクトリー]
 |
 ├── app
 ├── assets
 ├── config
 ├── core
 ├── var
 ├── vendor
 |
 ├── html
 |    |
 |    └── public [公開フォルダ]
</code>

<code php index.php>
$project_path = dirname(dirname(__DIR__));
$public_path = __DIR__;
</code>

\\

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

Apricotでは環境設定ライブラリーとして phpdotenv を使用しています。環境変数を設定する ''.env'' ファイルはプロジェクトフォルダ直下に配置します。環境変数の設定に関しての詳細は、[[https://github.com/vlucas/phpdotenv|phpdotenv]] を参照して下さい。

{{fa>folder-open-o}} ** /your-project **
<code ini .env>
# Application
APP_NAME=Apricot
APP_VERSION=1.0.0
#APP_SECRET=Please set a random 32 characters
APP_SECRET=0123456789ABCEDF0123456789ABCEDF
APP_DEBUG=true
APP_TIMEZONE=Asia/Tokyo
APP_LANG=ja

# Loging
LOG_NAME ="apricot"
LOG_LEVEL = "debug"
</code>

^環境変数^設定内容^型^必須^
|APP_NAME|アプリケーション名|string|〇|
|APP_VERSION|アプリケーションバージョン|string|〇|
|APP_SECRET|シークレット文字列\\ 安全の為にランダムな32文字を設定して下さい|string|〇|
|APP_DEBUG|デバッグモード|bool|〇|
|APP_TIMEZON|タイムゾーン|string|〇|
|APP_LANG|デフォルトの言語(省略時は'en')|string|〇|
|LOG_NAME|ログ名 (省略時はAPP_NAMEと同じ)|string| |
|LOG_LEVEL|[[https://github.com/Seldaek/monolog/blob/master/doc/01-usage.md#log-levels|ログレベル]] (省略時はdebug)|string| |

環境変数の取得にはボイラープレートの ''env()'' を使用します。

<code php>
$app_name = env('APP_NAME');
</code>

\\

===== アプリケーション設定 =====

アプリケーションの設定ファイルは、config ディレクトリの下に配置します。

<code>
your-project [プロジェクトディレクトリー]
 |
 ├── config
 |    |
 |    ├── setting/ ----- 機能別の設定ファイル(*.setting.php)を配置します
 |    ├── setup/ ------- 機能別のセットアップファイル(*.setup.php)を配置します
 |    ├── app.php ------ アプリケーション全体の設定を行います
 |    ├── routes.php --- ルーティングの設定を行います
</code>

\\


==== app.phpファイル =====

アプリケーション変数は ''/your-project/config/app.php'' に設定します。アプリケーション変数には、以下のようなアプリケーションの構成やセキュリティーに関係する設定が含まれています。

{{fa>folder-open-o}} ** /your-project/config**
<code php app.php>
<?php
/**
 * This file contains application settings.
 */
return
[
    'setup' => [ /* Some settings */ ],
    'middleware' => [ /* Some settings */ ],
    'csrf' => [ /* Some settings */ ],
    'auth' => [ /* Some settings */ ],
];
</code>

  * ''setup'' --- 主に外部ライブラリの初期化ファイルを指定します。
  * ''middleware'' --- ミドルウェアを指定します。詳しくは「[[apricot:usage:ja:middleware#middlewareの実装]]」を参照して下さい。
  * ''csrf'' --- CSRFトークンの設定を行います。詳しくは「[[apricot:usage:ja:middleware#csrf対策]]」を参照して下さい。
  * ''auth'' --- ユーザ認証(セッション認証)の設定を行います。詳しくは「[TODO]」を参照して下さい。

アプリケーション変数の取得や存在確認を行うには、ボイラープレートを使います。アプリケーション変数は以下のようにドット表記キーによって指定します。

<code php>
/** Checks if the given key is present. */
$present = app_has('auth.expires_sec');

/** Gets the application value specified by the Dot-notation key. */
$value = app('auth.expires_sec', $default);
</code>

上例は、以下のように登録されているアプリケーション変数を検索します。
<code php>
[
    'auth' => [
        'expires_sec'=> 2*7*24*3600,
    ],
];
</code>

\\

==== routes.phpファイル ====

Apricotではリクエストルータに [[https://github.com/nikic/FastRoute|FastRoute]] を使用しています。ルーティングの設定は、
routes.php ファイルで行います。以下はその例です：

{{fa>folder-open-o}} ** /your-project/config**
<code php routes.php>
<?php
//-------------------------------------------------------------------
// Route Definition Callback
//-------------------------------------------------------------------
return function (FastRoute\RouteCollector $r)
{
    $base = Core\Application::getInstance()->getRouteBase();
    $r->addGroup($base, function (FastRoute\RouteCollector $r) use($base)
    {
        // Home
        $r->get('/', function() use($base){
            header("Location: " . $base.'/stub');
        });

        // Stub
        $r->get('/stub[/{no:\d+}]', 'StubController@index');
    });
};
</code>

ルーティングは、フロントコントローラ ''index.php'' が受け取ったURLパスとアクションを対応させます。上のHomeコントローラの例は、URLパス と クロージャを対応付けています。また、Stubコントローラの例では、URLパス と 「コントローラクラス@アクションメソッド」を対応付けています。

以下は、Apricotのアプリ部分として提供されているroutes.php ファイルの完全なコードです。アプリ部分の初期実装では、ログイン認証コントローラ(AuthControllerクラス)とユーザコントローラ(UserControllerクラス)が含まれています。

<code php routes.php>
<?php
/**
 * This file contains callback for route definitions.
 */
return function (FastRoute\RouteCollector $r)
{
    /** @var string $base route base path */
    $base = Apricot\Application::getInstance()->getRouteBase();

    // Creates a route group with a common prefix.
    $r->addGroup($base, function (FastRoute\RouteCollector $r) use($base)
    {
        // Authentication
        $r->get ('/login', 'AuthController@showForm');
        $r->post('/login', 'AuthController@login');
        $r->get ('/logout', 'AuthController@logout');

        // User
        $r->get ('/users', 'UserController@index');
        $r->get ('/user/create', 'UserController@create');
        $r->post('/user/insert', 'UserController@insert');
        $r->get ('/user/{id:\d+}/edit', 'UserController@edit');
        $r->post('/user/{id:\d+}/update', 'UserController@update');
        $r->post('/user/{id:\d+}/delete', 'UserController@delete');

        // Home
        $r->get ('/home', 'HomeController@index');
        $r->get('[/]', function() use($base){
            header("Location: " . $base.'/home');
        });

        // Stub
        $r->get('/stub[/{no:\d+}]', 'StubController@index');
    });
};
</code>

ルーティングのより詳しい説明は「コントローラの[[apricot:usage:ja:controller#ルーティング]]」を参照して下さい。

\\

==== 設定管理 ====

アプリケーション内の様々な設定は、ディレクトリー ''/your-project/config/setting'' 下に以下のネーミング規則で機能毎に保存されます。

<code>
設定ファイル名: {first_key}.setting.php
</code>

設定値へのアクセスには **ドット表記** による「設定キー」によって行われます。設定キーの第1キーが設定ファイル名の{first_key}と一致します。この第1キーは習慣的にライブラリー名や機能によって名前付けされます。

以下に ロギングライブラリである [[https://github.com/Seldaek/monolog|monolog]] の例を示します。

{{fa>folder-open-o}} ** /apricot/config/setting **
<code php monolog.setting.php>
<?php
return
[
    'name' => env('LOG_NAME',env('APP_NAME')),
    'path' => env('LOG_PATH',var_dir('logs')),
    'level'=> env('LOG_LEVEL','debug'),
    'max_files'=> 0,
];
</code>

settingファイルは key => valute の形式で設定を表す連想配列を返す必要があります。

settingファイルの設定値を取得するには「ドット表記」によって行います。例えば「ログの名前」を参照する設定キーは、''monolog.name'' です。ドット表記による階層に制限はなく、monolog.setting.php で返す連想配列の階層が深ければ ''monolog.second_key.third_key.4th_key'' などのように深い階層も可能です。

設定の取得には Configシングルトンを使用します。

<code php>
/** Checks if the given key is present. */
$present = Config::has('monolog.name');

/** Gets the configuration value specified by the Dot-notation key. */
$value = Config::get('monolog.name', $default);
</code>

また、ボイラープレートを使って取得することも出来ます。

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

\\

==== セットアップ管理 ====

アプリケーションを構成しているライブラリーやクラスなどのセットアップファイルは、ディレクトリー ''/your-project/config/setup'' 下に以下のネーミング規則で保存されます。

<code>
セットアップファイル名: {setup_name}.setup.php
</code>

これらのセットアップファイルの構成は、アプリケーション設定ファイル app.php によって行われます。以下に実際の app.php によるセットアップの構成を示します。

{{fa>folder-open-o}} ** /your-project/config**
<code php app.php>
<?php
/**
 * This file contains application settings.
 */
return
[
    'setup' =>[
        config_dir('setup/whoops.setup.php'),    /* Error handler (whoops) */
        config_dir('setup/bladeone.setup.php'),  /* View template (BladeOne) */
        config_dir('setup/aliases.setup.php'),   /* Class aliases for view template and so on */
        config_dir('setup/idiorm.setup.php'),    /* ORM (idiorm) */
        config_dir('setup/validator.setup.php'), /* Valitron\Validator */
    ],
    ...
];
</code>

Apricotのアプリケーションインスタンスは、起動時にセットアップ構成で定義されて順序でに従ってsetupファイルを実行します。ここで使用されている ''config_dir()'' は configディレクトリ内からファイルパスを取得するボイラープレートです。

\\

==== クラスエイリアス ====

Apricotは、アプリケーション起動時のセットアップで、クラスのエイリアスを作成します。これは、よく使用する完全修飾クラス名を短くコーディングする為の配慮で、特にHTMLテンプレートでの使用を想定しています。

以下に示すセットアップファイル(aliases.setup.php)を示します。

{{fa>folder-open-o}} ** /your-project/config/setup **
<code php aliases.setup.php>
<?php
/**
 * Registers the class alias used in the view template
 */
return function():bool
{
    $aliases =
    [
        /* Apricot */
        'Input' => Apricot\Input::class,
        'QueryString' => Apricot\QueryString::class,
        'Session' => Apricot\Session::class,
        'Flash' => Apricot\Flash::class,
        'Cookie' => Apricot\Cookie::class,
        'Config' => Apricot\Config::class,
        'Log' => Apricot\Log::class,
        'Debug' => Apricot\Debug::class,
        'DebugBar' => Apricot\DebugBar::class,
        'ErrorBag' => Apricot\Foundation\ErrorBag::class,

        /* App */
        'ViewHelper' => App\Helpers\ViewHelper::class,
        'ValidatorErrorBag' => App\Foundation\ValidatorErrorBag::class,
        'Container' => App\Foundation\Container::class,
        'AuthUser' => App\Foundation\Security\AuthUser::class,
    ];

    // Creates an alias for a class
    foreach($aliases as $alias_name => $original_class)
    {
        class_alias($original_class, $alias_name);
    }
    return true; // Must return true on success
};
</code>

ここでは、よく使うシングルトンとテンプレート用のヘルパークラスのエイリアスを作っています。

\\