mirror of
https://github.com/php/doc-ja.git
synced 2026-03-24 07:02:08 +01:00
d68f90e3e9
- 参照下さい - 参照して下さい - 参照してください を「参照ください」に置き換えた。 個人的には「参照ください」は違和感のある日本語だが、既存の訳で圧倒的な優勢だったそれを採用した。 closes: #23
360 lines
14 KiB
XML
360 lines
14 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: eabde0419cf90f596f60db00e31fcb6ebe41ac55 Maintainer: takagi Status: ready -->
|
|
<!-- CREDITS: hirokawa,shimooka,mumumu -->
|
|
<refentry xml:id="function.htmlspecialchars" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refnamediv>
|
|
<refname>htmlspecialchars</refname>
|
|
<refpurpose>特殊文字を HTML エンティティに変換する</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>htmlspecialchars</methodname>
|
|
<methodparam><type>string</type><parameter>string</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401</initializer></methodparam>
|
|
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>encoding</parameter><initializer>&null;</initializer></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>double_encode</parameter><initializer>&true;</initializer></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
文字の中には HTML において特殊な意味を持つものがあり、
|
|
それらの本来の値を表示したければ
|
|
HTML の表現形式に変換してやらなければなりません。
|
|
この関数は、これらの変換を行った結果の文字列を返します。
|
|
入力文字列の中で名前付きエンティティに関連づけられたものを
|
|
すべて変換する必要がある場合には、代わりに
|
|
<function>htmlentities</function>
|
|
を使用してください。
|
|
</para>
|
|
<para>
|
|
この関数への入力文字列と最終的なドキュメントとの間で文字セットが一致している場合は、
|
|
この関数を使えば HTML ドキュメントに組み込むための準備として十分です。
|
|
しかし、この関数への入力の中に、最終的なドキュメントの文字セットでは符号化できない文字がある場合もあります。
|
|
そんな文字も (数値エンティティや名前つきエンティティなどで) 残したい場合は、
|
|
この関数と <function>htmlentities</function>
|
|
(これは、名前付きエンティティに対応する文字しか置換しません)
|
|
を使うだけでは不十分です。そんな場合は
|
|
<function>mb_encode_numericentity</function> を使う必要があります。
|
|
</para>
|
|
<para>
|
|
<table>
|
|
<title>変換対象となる文字</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>変換前</entry>
|
|
<entry>変換後</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>&</literal> (アンパサンド)</entry>
|
|
<entry><literal>&amp;</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>"</literal> (ダブルクォート)</entry>
|
|
<entry><constant>ENT_NOQUOTES</constant> が指定されていない場合、<literal>&quot;</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>'</literal> (シングルクォート)</entry>
|
|
<entry>
|
|
<literal>&#039;</literal> (<constant>ENT_HTML401</constant> の場合) あるいは <literal>&apos;</literal> (
|
|
<constant>ENT_XML1</constant>、<constant>ENT_XHTML</constant>、
|
|
<constant>ENT_HTML5</constant> の場合)。ただし
|
|
<constant>ENT_QUOTES</constant> が指定されている場合に限る
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal><</literal> (小なり)</entry>
|
|
<entry><literal>&lt;</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>></literal> (大なり)</entry>
|
|
<entry><literal>&gt;</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>string</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
変換される文字列。
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>flags</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
以下のフラグを組み合わせたビットマスクです。
|
|
クォートや無効な符号単位シーケンス、そして文書型の扱いを指定します。
|
|
デフォルトは <literal>ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401</literal> です。
|
|
<table>
|
|
<title>利用可能な <parameter>flags</parameter> 定数</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>定数名</entry>
|
|
<entry>説明</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><constant>ENT_COMPAT</constant></entry>
|
|
<entry>ダブルクオートは変換しますがシングルクオートは変換しません。</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>ENT_QUOTES</constant></entry>
|
|
<entry>シングルクオートとダブルクオートを共に変換します。</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>ENT_NOQUOTES</constant></entry>
|
|
<entry>シングルクオートとダブルクオートは共に変換されません。</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>ENT_IGNORE</constant></entry>
|
|
<entry>
|
|
無効な符号単位シーケンスを含む文字列を渡したときに、
|
|
空の文字列を返すのではなく無効な部分を切り捨てるようになります。
|
|
このフラグは使わないようにしましょう。
|
|
<link xlink:href="&url.delete.nonchars;">セキュリティの問題が発生する可能性があります</link>。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>ENT_SUBSTITUTE</constant></entry>
|
|
<entry>
|
|
無効な符号単位シーケンスを含む文字列を渡したときに、
|
|
空の文字列を返すのではなく Unicode の置換文字に置き換えます。
|
|
UTF-8 の場合は U+FFFD、それ以外の場合は &#xFFFD; となります。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>ENT_DISALLOWED</constant></entry>
|
|
<entry>
|
|
指定した文書型において無効な符号位置を、Unicode の代替文字である
|
|
U+FFFD (UTF-8) あるいは &#xFFFD; で置き換えます。
|
|
これを設定しなければ、無効な符号位置をそのまま残します。
|
|
これは、外部コンテンツを埋め込んだ XML 文書を整形式に保つために有用です。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>ENT_HTML401</constant></entry>
|
|
<entry>
|
|
コードを HTML 4.01 として処理します。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>ENT_XML1</constant></entry>
|
|
<entry>
|
|
コードを XML 1 として処理します。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>ENT_XHTML</constant></entry>
|
|
<entry>
|
|
コードを XHTML として処理します。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>ENT_HTML5</constant></entry>
|
|
<entry>
|
|
コードを HTML 5 として処理します。
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>encoding</parameter></term>
|
|
<listitem>
|
|
&strings.parameter.encoding;
|
|
<para>
|
|
この関数を使ううえでは
|
|
<literal>ISO-8859-1</literal> と <literal>ISO-8859-15</literal>、
|
|
<literal>UTF-8</literal>、<literal>cp866</literal>、
|
|
<literal>cp1251</literal>、<literal>cp1252</literal> そして
|
|
<literal>KOI8-R</literal> は事実上同等です。
|
|
<parameter>string</parameter> 自体がそのエンコーディングにおける有効な文字列である限り、
|
|
これらのエンコーディングでは
|
|
<function>htmlspecialchars</function> の影響が及ぶ文字がみな同じ位置にあるからです。
|
|
</para>
|
|
&reference.strings.charsets;
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>double_encode</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
<parameter>double_encode</parameter> をオフにすると、PHP
|
|
は既存の html エンティティをエンコードしません。
|
|
デフォルトでは、既存のエンティティも含めてすべてを変換します。
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
変換後の文字列を返します。
|
|
</para>
|
|
<para>
|
|
入力の <parameter>string</parameter> の中に
|
|
エンコーディング <parameter>encoding</parameter> における無効なコードユニットシーケンスが含まれており、
|
|
かつ <constant>ENT_IGNORE</constant> フラグが設定されていなければ、
|
|
<function>htmlspecialchars</function> は空文字列を返します。
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>8.1.0</entry>
|
|
<entry>
|
|
<parameter>flags</parameter> のデフォルト値が
|
|
<constant>ENT_COMPAT</constant> から
|
|
<constant>ENT_QUOTES</constant> | <constant>ENT_SUBSTITUTE</constant> | <constant>ENT_HTML401</constant>
|
|
に変更されました。
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title><function>htmlspecialchars</function> の例</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
|
|
echo $new; // <a href='test'>Test</a>
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<note>
|
|
<para>
|
|
この関数は上記のあげたもの以外に関しては一切の変換を行わないことに注意してください。
|
|
すべての変換を行うには
|
|
<function>htmlentities</function> を参照ください。
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
<parameter>flags</parameter> の値が曖昧な場合、以下のルールが適用されます:
|
|
</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
<constant>ENT_COMPAT</constant>, <constant>ENT_QUOTES</constant>,
|
|
<constant>ENT_NOQUOTES</constant> のいずれも存在しない場合、
|
|
デフォルトは <constant>ENT_NOQUOTES</constant> になります。
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<constant>ENT_COMPAT</constant>, <constant>ENT_QUOTES</constant>,
|
|
<constant>ENT_NOQUOTES</constant> のうちひとつ以上が存在する場合、
|
|
<constant>ENT_QUOTES</constant> がもっとも優先度が高くなり、
|
|
その後に <constant>ENT_COMPAT</constant> が続きます。
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<constant>ENT_HTML401</constant>, <constant>ENT_HTML5</constant>,
|
|
<constant>ENT_XHTML</constant>,
|
|
<constant>ENT_XML1</constant> のいずれも存在しなければ、
|
|
デフォルトは <constant>ENT_HTML401</constant> になります。
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<constant>ENT_HTML401</constant>, <constant>ENT_HTML5</constant>,
|
|
<constant>ENT_XHTML</constant>,
|
|
<constant>ENT_XML1</constant> のうちひとつ以上が存在している場合、
|
|
<constant>ENT_HTML5</constant> が最も優先度が高くなり、
|
|
<constant>ENT_XHTML</constant>,
|
|
<constant>ENT_XML1</constant> そして <constant>ENT_HTML401</constant> の順に続きます。
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<constant>ENT_DISALLOWED</constant>, <constant>ENT_IGNORE</constant>,
|
|
<constant>ENT_SUBSTITUTE</constant> のうち、ひとつ以上が存在している場合、
|
|
<constant>ENT_IGNORE</constant> の優先度がもっとも高くなり、
|
|
<constant>ENT_SUBSTITUTE</constant> がその後に続きます。
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>get_html_translation_table</function></member>
|
|
<member><function>htmlspecialchars_decode</function></member>
|
|
<member><function>strip_tags</function></member>
|
|
<member><function>htmlentities</function></member>
|
|
<member><function>nl2br</function></member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|