目次

Apricot 配置と構成

y2sunlight 2020-07-29

Apricot ドキュメント に戻る

目次


ディレクトリー構成

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

/your-project

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

app ディレクトリー

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

assets ディレクトリー

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

config ディレクトリー

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

core ディレクトリー

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

public ディレクトリー

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

var ディレクトリー

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

vendor ディレクトリー

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


publicディレクトリー

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

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

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


.htcccess

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 を変更すれば任意の場所にプロジェクトディレクトリーを配置することができます。

兄弟関係(siblings)

 ┌── your-project [プロジェクトディレクトリー]
 |     |
 |     ├── app
 |     ├── assets
 |     ├── config
 |     ├── core
 |     ├── var
 |     └── vendor
 |
 ├── public [公開ディレクトリー]
 |
index.php
$project_path = dirname(__DIR__).'/your-project';
$public_path = __DIR__;

祖父母孫関係(Grandparent-Grandchild)

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"
環境変数設定内容必須
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ログレベル (省略時はdebug)string

環境変数の取得にはボイラープレートの 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 に設定します。アプリケーション変数には、以下のようなアプリケーションの構成やセキュリティーに関係する設定が含まれています。

/your-project/config

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

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

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


routes.phpファイル

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

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