差分

このページの2つのバージョン間の差分を表示します。

--- apricot:usage:ja:config [2020/07/29 14:47]
tanaka [配置]
+++ apricot:usage:ja:config [2020/09/03 13:44] (現在)
y2sunlight [Apricot 配置と構成]
@@ 行 1: / 行 1: @@
-> 編集中
-----
 ====== Apricot 配置と構成 ======
  --- //[[http://www.y2sunlight.com|y2sunlight]] 2020-07-29//
-[[apricot:usage:ja|Apricotの使用法 に戻る]]
+[[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:model|Apricot データベースとモデル]]
+  * [[apricot:usage:ja:database|Apricot データベース]]
+  * [[apricot:usage:ja:model|Apricot モデルとサービス]]
   * [[apricot:usage:ja:middleware|Apricot ミドルウェア]]
   * [[apricot:usage:ja:controller|Apricot コントローラ]]
-  * [[apricot:usage:ja:errors-logging|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 [プロジェクト]
+your-project [プロジェクトディレクトリー]
  |
- ├── app [アプリケーション]
+ ├── app
- |    |
+ ├── assets
- |    ├── Controllers [コントローラ]
+ ├── config
- |    ├── Exceptions [例外]
+ ├── core
- |    ├── Foundation [基盤]
+ ├── public
- |    ├── Helpers    [ヘルパー]
+ ├── var
- |    ├── Middleware [ミドルウェア]
+ └── vendor
- |    └── Models     [モデル]
+</code>
- |
- ├── assets [リソース]
+=== app ディレクトリー===
- |    |
+アプリケーションの本体を配置するディレクトリーで以下サブディレクトリーがあります。
- |    ├── lang  [言語別の出力テキスト]
- |    ├── sql   [SQLファイル]
+  * ''Controllers'' --- URLと結びついたアクション(メソッド)から構成される
- |    └── views [HTMLテンプレート]
+  * ''Exceptions'' --- アプリケーション例外クラスと集約例外コントローラ
- |
+  * ''Foundation'' --- コントローラ、モデル、エラーバッグなどのベースクラス
- ├── config [設定ファイル]
+  * ''Helpers'' --- ビューヘルパーなどの共通のユーティリティクラス
- |    |
+  * ''Middleware'' --- アクション起動時の前処理(まはた後処理)を行うミドルウェア
- |    ├── setting [機能別の一般設定]
+  * ''Models'' --- 通常データベースのテーブル単位で作り、アプリケーションのデータモデル
- |    └── setup   [機能別の起動設定]
+  * ''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 [プロジェクトディレクトリー]
  |
- ├── core [Apricotのコア]
- |    |
- |    ├── Derivations [ライブラリの派生クラス]
- |    ├── Exceptions  [例外]
- |    ├── Foundation  [基盤]
- |    └── helpers     [ヘルパー関数]
- |
  ├── public [公開フォルダ]
  |    |
- |    ├── css/
+ |    ├── css/        [cssファイル用]
- |    ├── img/
+ |    ├── img/        [画像ファイル用]
- |    ├── js/
+ |    ├── js/         [JavaScriptファイル用]
- |    ├── var/
+ |    ├── var/        [ライブラリリソース用(実行時に配置)]
- |    ├── .htaccess
+ |    ├── resources/  [ライブラリリソース用(配布時に配置)]
- |    └── index.php
+ |    ├── .htaccess   [Apacheの設定]
- |
+ |    └── index.php   [フロントコントローラ]
- ├── var  [データファイル]
+</code>
- |    |
- |    ├── cache [キャッシュ]
- |    ├── db    [DBファイル(sqlite)]
- |    └── logs  [ログ]
- |
- └── vendor [外部ライブラリ]
+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>
-=== appフォルダ===
+この設定では、ApacheのRewriteEngineを有効にして、publicフォルダ下に実在しないファイル及びフォルダに対する全てのリクエストをindex.phpに転送します。詳しくはApacheの[[https://httpd.apache.org/docs/2.4/ja/mod/mod_rewrite.html|マニュアル]]を参照して下さい。
-アプリケーションの本体を保存するフォルダーで以下のクラスが存在します。
-  * 【 基盤 】コントローラ、モデル、エラーバッグなどのベースクラス
+\\
-  * 【 例外 】アプリケーション例外クラスと集約例外コントローラ
-  * 【 モデル 】通常データベースのテーブル単位で作り、アプリケーションのデータモデルとなる
-  * 【 コントローラ 】通常画面単位に作り、URLと結びついたアクション(メソッド)から構成されている
-  * 【 ミドルウェア 】アクション起動時の前処理(まはた後処理)を行うクラス
-  * 【 ヘルパー 】ビューヘルパーなどの共通のユーティリティクラス
-=== assetsフォルダ ===
+===== アプリケーションの配置 =====
-アプリケーションのリソースを保存します。
-  *【 ビューテンプレート 】画面を作成するHTMLテンプレート([[basic-library:bladeone:3.37|BladeOne]]で使用)
+フロントコントローラ ''index.php'' は、以下に示すように、起動後直ぐに公開ディレクトリーとプロジェクトディレクトリーを取得してアプリケーションを初期化します。
-  *【 言語別のテキスト 】トランスレーションの為の言語別のテキスト
-  *【 SQLファイル 】データベース構築の為のSQL
-=== configフォルダ ===
+{{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__;
-=== coreフォルダ ===
+//-------------------------------------------------------------------
-Apricotのコアクラスを保存します。コアの主な目的は次の３つです。
+// Initializes the application
+//-------------------------------------------------------------------
+$application = new Apricot\Application($project_path, $public_path);
-  * アプリケーションの構成管理を提供する
+...
-  * リクエストからレスポンスまでの標準的な処理方法を提供する
+</code>
-  * ロギング、例外集約、デバックの機能を提供する
-=== publicフォルダ ===
+このように、デフォルトのindex.php の実装では、公開ディレクトリーとプロジェクトディレクトリーの関係は以下のような親子関係を想定しています。
-公開用のフォルダです。ここのはApricotのフロントコントローラ( ''index.php'' )があります。
-=== varフォルダ ===
+<code>
-アプリケーションの次のデータを保存するフォルダです。
+your-project [プロジェクトディレクトリー]
+ |
+ ├── app
+ ├── assets
+ ├── config
+ ├── core
+ ├── var
+ ├── vendor
+ |
+ └── public [公開ディレクトリー]
+</code>
-  * ログファイル
+プロジェクトディレクトリーは公開ディレクトリーからの相対パスで設定することがきでるので、例えば、以下で示すように index.php を変更すれば任意の場所にプロジェクトディレクトリーを配置することができます。
-  * キャッシュファイル
-  * データベースファイルなど
-=== vendorフォルダ ===
-Composerが使用する外部ライブラリーの保存フォルダです。
+=== 兄弟関係(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 **
@@ 行 139: / 行 235: @@
 ^環境変数^設定内容^型^必須^
-|APP_NAME|アプリケーション名(半角英数字)|string|〇|
+|APP_NAME|アプリケーション名|string|〇|
-|APP_VERSION|バージョン|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>
 \\
 ===== アプリケーション設定 =====
-app.php はライブラリとミドルウェアに関する構成とセキュリティーの定義が含まれています。
+アプリケーションの設定ファイルは、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**
@@ 行 166: / 行 459: @@
         config_dir('setup/validator.setup.php'), /* Valitron\Validator */
     ],
-    'middleware' =>[
+    ...
-        \App\Middleware\AccessLog::class,        /* Access log */
-        \App\Middleware\VerifyCsrfToken::class,  /* Verify CSRF Token */
-//      \App\Middleware\Auth\BasicAuth::class,   /* Basic authentication */
-        \App\Middleware\Auth\SessionAuth::class, /* Session authentication */
-    ],
-    'csrf' =>[
-        'disposable' => false,
-    ],
-    'auth' =>[
-        'db'=>[
-            'user'=>[
-                'account' =>'account',
-                'password' =>'password',
-                'remember' =>'remember_token',
-            ],
-        ],
-        'expires_sec'=> 2*7*24*3600, /* 2weekws */
-        'menu'=> true,
-    ],
 ];
 </code>
-  * setup --- ライブラリの初期化ファイルの所在(フルパス)
+Apricotのアプリケーションインスタンスは、起動時にセットアップ構成で定義されて順序でに従ってsetupファイルを実行します。ここで使用されている ''config_dir()'' は configディレクトリ内からファイルパスを取得するボイラープレートです。
-  * middleware --- ミドルウェアの完全修飾クラス名
-  * auth --- ユーザ認証(セッション認証)の設定
-  * csrf --- CSRFトークンの設定
 \\
-===== パッケージ設定 =====
+==== クラスエイリアス ====
->TODO
-\\
+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>
-===== ルーティング =====
+ここでは、よく使うシングルトンとテンプレート用のヘルパークラスのエイリアスを作っています。
->TODO
 \\

Ground Sunlight

ユーザ用ツール

サイト用ツール

差分

ページ用ツール