Grav 1.6 へのアップデート

Grav 1.6 は、Grav の最初のリリース以来、最大のアップデートでした。いくつかの新機能追加、改善、バグ修正がなされ、そして Grav 2.0 への道を開くたくさんのアーキテクチャの変更が提供されています。

あなたが開発者もしくはサイト管理者であれば、テストサイトでは デバッグバー を有効化してください。なぜなら、デバッグバーには、いくつかの便利なツールがあり、それらによって、 Grav のそれ以降のバージョンで動作する準備を確実にしてくれるからです。

デバッグバーの deprecated タブ

デバッグバーの Deprecated （非推奨） タブを見てください。 このタブは、非推奨の問題を特定し、 Grav を新しいバージョンへアップグレードする前に、それらを修正したり、レポートしたりしてくれます。 Deprecated タブ内にある問題を修正ことで、サイトは速くなり、将来アップグレードする時間を削減してくれます。

すべての問題を確実に捕まえるために、キャッシュをクリアし、キャッシュを無効化して Grav を実行すべきです。そうすることで、すべてのエラーを捕まえる可能性が最大化されます。以下の手順を進める際でさえ、キャッシュのクリア後にのみ YAML/Twig エラーのいくつかが現れることに気がつくかもしれません。

Deprecated タブには、見つかった非推奨機能のリストが掲載されます。すべての問題について、クリックして非推奨に関するメッセージを開くことができます。このメッセージは、問題と問題の所在をさかのぼる簡単な説明文で、このメッセージのおかげで、コードの場所が分かり、修正できるようになります。右側には、非推奨エラーのタイプが表示されます。右下のバッジをクリックすることにより、表示されたタイプをフィルタリングできます。

非推奨メッセージを開いたとき、最初のうちはその内容に圧倒されるかもしれません。しかし多くの場合、必要なのは最初の数行で、（メッセージと、ファイルと、もしあれば行数）で、ほとんどの内容は無視できます。

非推奨の問題は、いくつかのタイプに分類できます：

• yaml: YAML もしくはマークダウンファイルで、非推奨の YAML 構文を使っている。
• twig: Twig ファイルに、非推奨の Twig 構文を含んでいるか、もしくはそれ以外の Twig 関係の問題。
• grav: Grav の非推奨のメソッドもしくはプロパティが使われている。
• vendor: 非推奨のサードパーティ製ライブラリコードが使われている。
• unknown: 上記以外の非推奨メッセージ。

YAML のパース

Grav 1.6 では、 Symfony 4.2 YAML parser が使われます。これは、以前の Symfony 3.4 のパーサーよりも、より厳密に YAML 標準仕様 に従っています。これはつまり、以前機能していた YAML ファイルであっても、妥当でない YAML であればエラーを起こしうるということです。しかし、ファイルが 4.2 バージョンのパーサーで読み込み失敗したとしても、 Grav はデフォルトで古い 3.4 バージョンのパーサーで読み込み、サイトを運用し続けます。とはいえ、このことはサイトパフォーマンスを悪化させるので、問題を見つけ、修正し、パフォーマンスを最適化すべきです。

Grav 1.6.7 以降では、 YAML パース時の問題を検出する CLI コマンドが新しく追加されました。 bin/grav yamllinter を実行し、サイト内の YAML パースエラーを見つけ、修正してください。 Grav 1.6 以上にアップグレードした直後に、このコマンドを実行することをおすすめします。

管理パネルプラグイン 1.9.3 以降では、 YAML Linter を Tools > Reports に統合していますので、 CLI コマンドのかわりにこちらを利用することもできます。

YAML エラーの探し方

• クオテーションマークで囲んでいない文字列の最初を @, \, |, % そして > で始めないでください。 @data-options: [] を使わないでください。代わりに、 data-options@: [] を使ってください。
• すべてのキーについて、コロン : の後はホワイトスペースを入れてください。 key:value ではなく、 key: value を使用してください。
• すべてのキーについて、 null, true, false, 2.0 (実数値) は、クオテーションマークで囲んでください。キーは、整数もしくは文字列のみです。
• 同様に、値の null, true, false, 2 そして 2.0 は、それが文字列を意味するのであれば、クオテーションマークで囲んでください。
• 文字列をダブルクオテーションで囲む場合は、 \ 文字でエスケープしなければいけません。

また、デバッグバーで、非推奨の YAML を見つけることができます。デバッグバーを開き、 Deprecation タブを見るだけです。タブが見当たらない場合は、問題は検出されていません。

YAML 互換モード

デフォルトでは、 YAML 互換モードは、 Grav 1.6 で有効化されています。これにより、アップグレード後も、古いサイトを動かし続けることができますが、この状態は、新しいサイトでは理想的とは言えません。YAML パースのエラーについて、修正し、テストをしてください。

この設定は、 user/config/system.yaml で変更できます：

strict_mode:
  yaml_compat: false

既存サイトでは、この設定を触らないことをおすすめします。むしろ、互換モードを false にして、テストサイトを作成してください。Grav 1.6 以上で作成された新しいサイトは、すべて互換モードが無効化しておいてください。これにより、 Grav 2.0 にアップグレードする際には、多くの時間が削減できます。

Twig

遅延ブロック

あなたのテーマをアップデートして、 Grav 1.6 で提供された遅延アセットブロックがサポートされるようにしてください。もしくは、テーマを修正してカスタムテーマにしていたり、独自のテーマを開発している場合は、ご自身でこの新しい機能と、Grav とそのプラグインの新しいバージョンが使えるようにしてください。以下のブログ投稿が参考になります： Important Theme Updates

Twig における非推奨

Grav 1系で、現在使われている Twig 1系の代わりに、Grav 2.0 では、 Twig 2系 を使う予定です。Twig 2 では、いくつかの非推奨機能があります。このため、 Grav 2.0 へアップグレードする前に、これらの問題をすべて見つけ出し、修正しておくと良いでしょう。

デバッグバーでは、 Twig の非推奨問題を見つけることができます。デバッグバーを開き、 Deprecated タブをクリックしてください。

Twig 問題の探し方

• ファイルでインポートしたマクロは、（include 呼び出し経由の）子テンプレートでは利用できない。これらで利用する場合は、各ファイルで明示的にマクロをインポートする必要。
• |replace() フィルタは、パラメータとして連想配列が渡されたときのみ機能する：{ "I like this and that."|replace({'this': 'foo', 'that': 'bar'}) }}.
• sameas() によるテストは、 same as() と書かれるべき。

非推奨に関するより詳しい情報は、 このページで見つかります 。

オートエスケープ

Grav は、 XSS 攻撃を除けば、脆弱性からは安全です。XSS 攻撃は、ユーザーからの信頼できない入力を適切にエスケープしていないコードがあれば、大した労力もなく発生してしまう脆弱性です。Twig は、テンプレートファイルを簡単に作成できますが、同時に、テンプレートファイル内で使われる多くの変数について、それらをサニタイズすることも忘れられがちです。たとえ入力がフィルタリングされ、安全であったとしても、本来エスケープされるべき特殊文字が含まれていて、適切な HTML コードが作成されない可能性があります。

たとえば、以下のような Twig テンプレートがあったとします：

{% set my_string = '<script>echo("hello there!");<script>' %}
<p>
    {{ my_string }}
</p>

デフォルトでは、 Grav は Twig オートエスケープを無効化して 、テンプレートのシンプル化、クリア化してきましたが、不幸なことに、これは良くない決定でした。特殊文字が含まれるかもしれない、もしくは信頼できないソースからの変数に、常にエスケープし続けることを覚えていられる人など、私たちも含め、誰もいなかったからです。より悪いことに、その変数が HTML 安全かどうかも、通常は分からないものです。ほとんどの XSS 脆弱性からサイトを守るには、 config 設定でオートエスケープを有効化すべきです。不幸なことに、 Twig テンプレートを使うテーマやプラグインは、この設定が有効化されていると機能しない傾向があります。 – そして、明示的にエスケープされていないテンプレートは、悪意のあるコンテンツに対して脆弱である場合が多いです。

上記の例では、オートエスケープが無効化されているので、出力はピュアな HTML としてレンダリングされるでしょう。そして、アラートボックスが "hello there!" とポップアップされます。しかし、 Twig エスケープフィルタの |e もしくは e|('html') を使って、この部分をエスケープするべきです：

{% set my_string = '<script>echo("hello there!");<script>' %}
<p>
    {{ my_string|e }}
</p>

多くの人は、 Twig 内の変数をエスケープし忘れる傾向にあり、すべての場所に |e を使うのはテンプレートファイルの可読性を落とすため、 user/config/system.yaml に新しい設定が用意されました：

strict_mode:
  twig_compat: false

この設定は、すべての Twig テンプレートファイル内で、 オートエスケープ を有効化することに特化しています。そして、オートエスケープの有効化・無効化の古い設定を破棄します。この設定の副作用として、サイトには、いくつかのコンテンツのかけらが残されます。それらは、コンテンツが無理にエスケープされたもので、 |raw フィルタを使って HTML を、 HTML のみを含むように修正されなければいけません。多くのテンプレートとプラグインは、強制エスケープに対応したアップデートをしていません。そのため、これらの修正が必要なバグについて、速やかに報告をお願いします。

オートエスケープを使うための変更については、簡単なものではありません。変更中に、すべてのテンプレートファイルには、 |e と、 |raw の両方のフィルタが存在し、テンプレートファイルがどちらのモードでも安全になるようにしなければなりません。もしくは、 Twig タグの {% autoescape %} を使うこともできます。

より詳しい情報は、 Twig マニュアル をご覧ください。