— y2sunlight 2020-07-29

Apricot ドキュメント に戻る

目次

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

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

/your-project

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

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

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

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

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

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

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

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

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

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

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

• cache — キャッシュファイル
• logs — ログファイル
• 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 --- ルーティングの設定を行います

アプリケーション変数は /your-project/config/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 — 主に外部ライブラリの初期化ファイルを指定します。
• middleware — ミドルウェアを指定します。詳しくは「middlewareの実装」を参照して下さい。
• csrf — CSRFトークンの設定を行います。詳しくは「csrf対策」を参照して下さい。
• auth — ユーザ認証(セッション認証)の設定を行います。詳しくは「[TODO]」を参照して下さい。

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

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

上例は、以下のように登録されているアプリケーション変数を検索します。

[
    'auth' => [
        'expires_sec'=> 2*7*24*3600,
    ],
];

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パス と 「コントローラクラス@アクションメソッド」を対応付けています。

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

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

ルーティングのより詳しい説明は「コントローラのルーティング」を参照して下さい。

アプリケーション内の様々な設定は、ディレクトリー /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ディレクトリ内からファイルパスを取得するボイラープレートです。

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

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

/your-project/config/setup

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

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