— y2sunlight 2020-07-29

Apricot ドキュメント に戻る

目次

• Apricot 特徴と概要
• Apricot 配置と構成
• Apricot ログとエラー処理
• Apricot リクエストとレスポンス
• Apricot フロントエンド
• Apricot データベースとモデル
• Apricot ミドルウェア
• Apricot コントローラ
• Apricot ユーティリティ

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

/your-project

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

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

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

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

• views — 画面を作成するHTMLテンプレート(BladeOneで使用)
• lang — トランスレーションの為の言語別のテキスト
• sql — データベース構築の為のSQLファイル

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

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

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

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

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

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

• logs — ログファイル
• cache — キャッシュファイル
• db — データベースファイルなど

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

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

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

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

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

your-project/public

.htaccess

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ index.php [L]
</IfModule>

この設定では、ApacheのRewriteEngineを有効にして、publicフォルダ下に実在しないファイル及びフォルダに対する全てのリクエストをindex.phpに転送します。詳しくはApacheのマニュアルを参照して下さい。

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

your-project/public

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);
 
...

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

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

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

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

index.php

$project_path = dirname(__DIR__).'/your-project';
$public_path = __DIR__;

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

index.php

$project_path = dirname(dirname(__DIR__));
$public_path = __DIR__;

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

/your-project

.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"

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

$app_name = env('APP_NAME');

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

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

app.php はアプリケーション全体の設定を行いますが、デフォルトでは以下のような設定が含まれています。

/your-project/config

app.php

<?php
/**
 * This file contains application settings.
 */
return
[
    'setup' => [ /* Some settings */ ],
    'middleware' => [ /* Some settings */ ],
    'csrf' => [ /* Some settings */ ],
    'auth' => [ /* Some settings */ ],
];

• setup — 主に外部ライブラリの初期化ファイルを指定します。詳しくは [TODO] を参照して下さい。
• middleware — ミドルウェアを指定します。詳しくは [TODO] を参照して下さい。
• csrf — CSRFトークンの設定を行います。詳しくは [TODO] を参照して下さい。
• auth — ユーザ認証(セッション認証)の設定を行います。詳しくは [TODO] を参照して下さい。

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

/your-project/config

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');
    });
};

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

ルーティング設定に関する詳細は、FastRouteを参照して下さい。

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

設定ファイル名: {first_key}.setting.php

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

以下に ロギングライブラリである monolog の例を示します。

/apricot/config/setting

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,
];

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

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

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

/** 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);

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

$value = config('monolog.name', $default);

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

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

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

/your-project/config

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 */
    ],
    ...
];

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