— y2sunlight 2020-07-29

Apricot ドキュメント に戻る

目次

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

HTMLテンプレートは、BladeOneをラップしたViewクラスが担当します。Viewクラスはシングルトンとして実装し、以下のように使用します。BladeOneと同じメソッド使用できますが、apricotで使用するのはrun()メソッドだけです。

使用法: View::{メソッド}

• $view — テンプレート名 ( テンプレートファイル名は {$view}.blade.php になる)
• $variables — ビュー変数 (['変数名'=>'値']の形式の連想配列)
• return値 — HTMLテキストを返す

完全修飾クラス名を短くコーディングする為に、クラスのエイリアスを作成します。このエイリアスは、特にHTMLテンプレートでの使用を想定しています。

以下に示す初期設定ファイル(aliases.setup.php)を config/setup フォルダの下に作成して下さい。

/apricot/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,
        '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
};

• よく使うコアクラスとアプリ用のヘルパークラスのエイリアスを作っています

アプリ用のヘルパー関数を作る準備として 表示用のHelperクラスを作成しておきます。必要に応じて、関数やクラスを追加していきます。

• ViewHelper — 表示用(主にHTMLテンプレートで使用)

/apricot/app/Helpers

ViewHelper.php

<?php
namespace App\Helpers;
 
/**
 * View Helper
 */
class ViewHelper
{
    /**
     * Returns a formatted date string.
     *
     * This method is an example of a view helper.
     *
     * @param string $datetime
     * @param string $format
     * @return string
     */
    static function formatDatetime(string $datetime, string $format='Y-m-d'):string
    {
        return date($format, strtotime($datetime));
    }
}

apricotで採用しているテンプレートエンジン BladeOne の文法に従ってアプリ全体のレイアウトを作ります。また、cssとJavaScriptファイルも準備します。

• layout.blade.php — アプリ全体のレイアウト
• main.css — アプリ共通のスタイルシート
• main.js — アプリ共通で使用するJavaScript

/apricot/config/setting

bladeone.setting.php

<?php
/**
 * This file contains BladeOne settings.
 */
return
[
    'template_path' => env('VIEW_TEMPLATE',assets_dir('views')),
    'compile_path' => env('VIEW_CACHE',var_dir('cache/views')),
    'mode' => \eftec\bladeone\BladeOne::MODE_AUTO,
];

• template_path — HTMLテンプレートファイルのパス(既定値は assets/views/)
• compile_path — コンパイル後のHTMLファイルのパス(既定値は var/cache/)
• mode — 実行モード(既定値は MODE_AUTO)

Viewクラスには以下の初期設定ファイルが存在します。

/apricot/config/setup

bladeone.setup.php

<?php
/**
 * Initial setting of View template (Blade One)
 */
return function():bool
{
    // @now directive
    Apricot\View::directive('now', function()
    {
        return "<?php echo date('Y-m-d H:i'); ?>";
    });
 
    // @csrf directive
    Apricot\View::directive('csrf', function()
    {
        $name = Apricot\Foundation\Security\CsrfToken::CSRF_KEY;
        return '<input name="'.$name.'" type="hidden" value="{{Session(\''.$name.'\')}}">';
    });
 
    return true; // Must return true on success
};

ここでは、HTMLテンプレートで使用するカスタムディレクティブを追加します。上のコードは、現在時刻を表示する @now ディレクティブの追加を行っています。CSRFトークンを出力する @csrf ディレクティブなどもここで実装する予定です。

トランスレーションは Translationクラスに実装されており、このクラスも基本的な機能だけをシンプルに作成しています。

Translationクラスの実装コードを以下に示します。ユーザはこのクラスを直接利用するのではなく、次節に示す Langクラスを使用して下さい。

/apricot/core/Foundation

Translation.php

<?php
namespace Apricot\Foundation;
 
/**
 * Plain Translation Class
 */
class Translation
{
    /**
     * @var string Language code(ISO 639-1)
     */
    private $lang;
 
    /**
     * @var array Messages
     */
    private $messages = [];
 
    /**
     * Constructor
     *
     * @param string $lang language code(ISO 639-1)
     */
    public function __construct(string $lang='en')
    {
        $this->lang = $lang;
 
        // Reads messages.
        foreach(glob(assets_dir("lang/{$lang}/*.php")) as $file)
        {
            $arr = explode('.', basename($file));
            if (is_file($file)) $this->read($file, $arr[0]);
        }
    }
 
    /**
     * Gets the language code(ISO 639-1).
     *
     * @return string
     */
    public function getLangCode():string
    {
        return $this->lang;
    }
 
    /**
     * Checks if the given key is present.
     *
     * @param string $key
     * @return bool
     */
    public function has(string $key):bool
    {
        return array_key_exists($key, $this->messages);
    }
 
    /**
     * Gets the message specified by the key.
     *
     * @param string $key
     * @param string $params
     * @return string
     */
    public function get(string $key, array $params = []):string
    {
        if ($this->has($key))
        {
            $message = $this->messages[$key];
            if (!empty($params))
            {
                $message = str_replace(array_keys($params), array_values($params), $message);
            }
        }
        else
        {
            $message = $key;
        }
        return $message;
    }
 
    /**
     * Reads messages.
     *
     * @param string $lang_file
     * @param string $top_key
     */
    private function read(string $lang_file, string $top_key)
    {
        $messages = require_once $lang_file;
        if (is_array($messages) && count($messages))
        {
            $dot_arr = array_dot($messages, $top_key.'.');
            $this->messages = array_merge($this->messages, $dot_arr);
        }
    }
}

アプリの作成過程で使用する共通の言語テキストを準備します。個別の画面については、その都度に追加して行きます。

/apricot/assets/lang/ja

messages.php

<?php
return [
    'app'=>[
        'title'=>env('APP_NAME'),
        'menu'=>[
            'menu1'=>'menu1',
            'menu2'=>'Menu2',
            'menu3'=>'Menu3',
            'logout'=>'Logout',
            'about_me'=>'About Me',
        ],
    ],
    'success' => [
        'db' => [
            'insert' => 'データを登録しました',
            'update' => 'データを更新しました',
            'delete' => 'データを削除しました',
        ],
    ],
    'error'=>[
        'unknown'=>'エラーが発生しました',
        'db' => [
            'access' => 'データアクセスが失敗しました',
            'insert' => 'データの登録が失敗しました',
            'update' => 'データの更新が失敗しました',
            'delete' => 'データの削除が失敗しました',
            'optimisstic_lock'=>'データが他のユーザによって更新されています',
        ],
    ],
];

• app — アプリケーションのタイトルやメニュー
• success — 処理が成功した場合のメッセージ
• error — エラー用のメッセージ

Langクラスは 上のTranslationクラスをシングルトンにしたもので、以下のメソッドがあります。

使用法: Lang::{メソッド}

Langクラスのget()メソッドは良く使用されるのでヘルパー関数に追加しておきます。

/apricot/core/helpers

boilerplates.php

if (! function_exists('__'))
{
    /**
     * Returns the translated message specified by the dot-notation key.
     *
     * @param string $key dot-notation key
     * @param string $params
     * @return string translated Message
     */
    function __($key, $params = [])
    {
        return Apricot\Lang::get($key, $params);
    }
}

この関数名は __ です。２つ並んだアンダースコアはPythonプログラマーの間では dunders (double underscoreの意) と呼ばれ特別なクラス内メンバに付加されますが、ここではそのような意味はなくトランスレータを表す関数名としてLaravelに準じました。