Skip to content

USAGE.md

Latest commit

 

History

History
111 lines (82 loc) · 4.27 KB

USAGE.md

File metadata and controls

111 lines (82 loc) · 4.27 KB

Usage

この文書は bypassflow/text の代表的な使い方をまとめる文書です。

Stringify

もっとも基本的な使い方です。 値を表示向け文字列へ寄せたいときに使います。

use bypassflow\Text\Text;

$value = [
    'name' => 'alice',
    'active' => true,
];

echo Text::stringify($value);

Niceable を実装した object は、その object 側の表示向け文字列を優先して使います。

HTML Escaping

HTML 文脈へ安全に出したいときの使い方です。 値をそのまま表示したい場面では escapeHtml()、HTML 本文へ文字列を入れたい場面では htmlTextEscape()、HTML 属性値へ文字列を入れたい場面では htmlAttributeEscape() を使います。htmlEscape() は本文向け alias として使えます。

use bypassflow\Text\Text;

echo Text::escapeHtml('<strong>alice</strong>');
echo Text::htmlTextEscape('<strong>alice</strong>');
echo Text::htmlEscape('<strong>alice</strong>');
echo Text::htmlAttributeEscape('"alice & bob"');

Htmlable を実装した object は、HTML 本文文脈で安全な値としてそのまま返します。

Context Escaping

HTML 以外の文脈へ出したいときの使い方です。 JavaScript の quoted string literal、CSS の property value、URL component、URL in HTML attribute、shell argument、JSON expression の変換をまとめて扱えます。jsEscape() と cssEscape() は、それぞれ特化名の alias として使えます。

use bypassflow\Text\Text;

echo Text::javaScriptStringLiteralEscape('<script>');
echo Text::jsEscape('<script>');
echo Text::cssPropertyValueEscape('<script>');
echo Text::cssEscape('<script>');
echo Text::urlEncode('a b/c?d=e');
echo Text::urlInHtmlAttributeEscape('a b/c?d=e');
echo Text::shellEscape('hello world');
echo Text::toJson(['name' => 'alice']);
echo Text::toJsExpression(['name' => 'alice']);

Text::escape() は generic dispatcher として使えますが、公開面では文脈が明確な特化メソッドを優先して使う方が意図が伝わりやすいです。

EscaperInterface ベースで扱いたい場合は、HtmlTextEscaper、HtmlAttributeEscaper、JavaScriptStringLiteralEscaper、CssPropertyValueEscaper、UrlComponentEscaper、UrlInHtmlAttributeEscaper、ShellEscaper を正本として使えます。HtmlEscaper、JavaScriptEscaper、CssEscaper、UrlEscaper は互換 alias として使えます。 なお、shell は単一引数の escape に限定して使い、可能なら proc_open() などで shell を介さず argv 配列を渡す方を優先します。 toJsExpression() は fw3/strings 系譜の「型に応じた JavaScript 式表現を返す」用途を引き継いでいます。

Context Guide

文脈ごとの使い分けを短く確認したいときの目安です。 HTML 本文、HTML 属性値、URL、JavaScript、CSS はそれぞれ別文脈として扱います。

  • HTML 本文
    • Text::htmlTextEscape()
  • HTML 属性値
    • Text::htmlAttributeEscape()
  • URL component
    • Text::urlEncode()
  • URL を HTML 属性値へ入れる場合
    • Text::urlInHtmlAttributeEscape()
  • JavaScript 文字列リテラル
    • Text::javaScriptStringLiteralEscape()
  • CSS property value
    • Text::cssPropertyValueEscape()

Case Conversion

命名や表示で文字列様式を変えたいときに使います。 snake case、chain case、camel case を揃えて扱えます。

use bypassflow\Text\Text;

echo Text::toSnakeCase('PrimaryOwner');
echo Text::toLowerChainCase('PrimaryOwner');
echo Text::toUpperCamelCase('primary_owner');

Byte Formatting

バイトサイズを表示向けに整形したいときの使い方です。 0 は 0B として、負値は符号を保ったまま単位付き文字列へ変換します。 KB / MB / GB / TB 以降の decimal suffix と、KiB / MiB / GiB / TiB の IEC suffix の両方を扱えます。 逆方向の parser もあり、単位付き文字列から byte 数へ戻せます。

use bypassflow\Text\Text;

echo Text::toUnitByteSize(0);
echo Text::toUnitByteSize(2048, 0);
echo Text::toUnitByteSize(-2048, 0);
echo Text::toUnitIecByteSize(2048, 0);
echo Text::fromUnitByteSize('1.5MB');
echo Text::fromUnitIecByteSize('2TiB');