svn: /phpdoc/bg/trunk/ chapters/intro.xml reference/strings/functions/htmlspecialchars.xml
[email protected] (Stanislav Yordanov) Mon, 04 Apr 2016 20:02:17 +0000
| Newsgroups | php.doc.bg |
|---|---|
| Message-ID | <[email protected]> |
stanprog Mon, 04 Apr 2016 20:02:17 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=338919
Log:
sync to EN
Changed paths:
U phpdoc/bg/trunk/chapters/intro.xml
U phpdoc/bg/trunk/reference/strings/functions/htmlspecialchars.xml
svn-diffs-338919.txt
(text/x-diff, 15 KB)
Modified: phpdoc/bg/trunk/chapters/intro.xml
===================================================================
--- phpdoc/bg/trunk/chapters/intro.xml 2016-04-04 19:15:44 UTC (rev 338918)
+++ phpdoc/bg/trunk/chapters/intro.xml 2016-04-04 20:02:17 UTC (rev 338919)
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
-<!-- EN-Revision: 306611 Maintainer: stanprog Status: ready -->
+<!-- EN-Revision: 338916 Maintainer: stanprog Status: ready -->
<chapter xml:id="introduction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<info><title>Въведение</title></info>
@@ -9,7 +9,8 @@
<para>
<acronym>PHP</acronym> (рекурсивно съкращение от <literal>PHP: Hypertext
Preprocessor</literal>) е широко използван скриптов език с отворен код, предназначен за обща употреба,
- който е изключително удобен за уеб разработки и може да се вгражда в HTML.
+ който е изключително удобен за уеб
+ разработки и може да се вгражда в HTML.
</para>
<para>
Добре, но какво означава това? Пример:
@@ -19,8 +20,7 @@
<info><title>Въвеждащ пример</title></info>
<programlisting role="php">
<![CDATA[
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML>
<html>
<head>
<title>Пример</title>
Modified: phpdoc/bg/trunk/reference/strings/functions/htmlspecialchars.xml
===================================================================
--- phpdoc/bg/trunk/reference/strings/functions/htmlspecialchars.xml 2016-04-04 19:15:44 UTC (rev 338918)
+++ phpdoc/bg/trunk/reference/strings/functions/htmlspecialchars.xml 2016-04-04 20:02:17 UTC (rev 338919)
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
-<!-- EN-Revision: 288721 Maintainer: stanprog Status: ready -->
+<!-- EN-Revision: 334627 Maintainer: stanprog Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.htmlspecialchars" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>htmlspecialchars</refname>
@@ -12,24 +12,29 @@
<methodsynopsis>
<type>string</type><methodname>htmlspecialchars</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
- <methodparam choice="opt"><type>int</type><parameter>quote_style</parameter><initializer>ENT_COMPAT</initializer></methodparam>
- <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>ENT_COMPAT | ENT_HTML401</initializer></methodparam>
+ <methodparam choice="opt"><type>string</type><parameter>encoding</parameter><initializer>ini_get("default_charset")</initializer></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>double_encode</parameter><initializer>true</initializer></methodparam>
</methodsynopsis>
<para>
- Някои знаци имат специално значение в HTML и трябва да се представят
- в HTML единици, ако искаме да запазим тяхното значение.
- Функцията връща низ с направени някои от въпросните преобразувания;
- преобразувания, които са полезни при всекидневната работа в областта
- на уеб програмирането. Ако трябва всички HTML единици да бъдат
- преобразувани използвайте функцията <function>htmlentities</function>.
+ Някои знаци имат специално значение в HTML и трябва
+ да се представят в HTML единици, ако искаме да запазим тяхното
+ значение. Функцията връща низ с направени въпросните
+ преобразувания. Ако трябва всички HTML единици да бъдат
+ преобразувани използвайте функцията
+ <function>htmlentities</function>.
</para>
- <simpara>
- Функцията е полезна за предотвратяване на появата на HTML код при
- информация предоставена от потребителя, като например във форуми
- и книги за гости.
- </simpara>
<para>
+ Ако входният низ предаден на тази функция и резултатният документ имат един и
+ същ набор от знаци, функцията е достатъчно за подготвяне на данните
+ за включване в повечето части на HTML документ. Иначе, ако входните данни
+ съдържат знаци, не са кодирани в набора от знаци на резултатния документ
+ и искате да запазите тези знаци (като числови или именувани елементи),
+ то тази и функция <function>htmlentities</function> (която преобразува
+ само поднизове със съответните елементи) няма да бъдат достатъчни.
+ Вместо нея ще трябва да използвате функция <function>mb_encode_numericentity</function>.
+ </para>
+ <para>
Поддържаните преобразувания са:
<itemizedlist>
<listitem>
@@ -45,8 +50,8 @@
</listitem>
<listitem>
<simpara>
- ''' (единични кавички) се преобразува до '&#039;' само когато
- <constant>ENT_QUOTES</constant> е установен.
+ "'" (единични кавички) се преобразува до '&#039;' (или &apos;)
+ само когато <constant>ENT_QUOTES</constant> е установен.
</simpara>
</listitem>
<listitem>
@@ -76,27 +81,102 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><parameter>quote_style</parameter></term>
+ <term><parameter>flags</parameter></term>
<listitem>
<para>
- Незадължителният втори аргумент
- <parameter>quote_style</parameter>, указва как функцията да
- преобразува единичните и двойните кавички. Режимът по подразбиране
- <constant>ENT_COMPAT</constant> е обратно съвместим режим, при който
- се преобразуват само двойните кавички, а единичните се оставят без изменение.
- Ако е установен <constant>ENT_QUOTES</constant> единичните и двойните
- кавички се преобразуват, а ако е установен <constant>ENT_NOQUOTES</constant>,
- единичните и двойните кавички се оставят без изменение.
+ Побитова маска на един или повече от следните флагове, която указва как се да се обработят кавичките,
+ невалидните кодови последователности и използвания туп на документа. Стойността по подразбиране е
+ <literal>ENT_COMPAT | 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>
+ Заменя невалидните кодови последователности с Уникод
+ U+FFFD (при UTF-8) или &#FFFD; (при използване на друго кодиране), вместо да връща празен низ.
+ </entry>
+ </row>
+ <row>
+ <entry><constant>ENT_DISALLOWED</constant></entry>
+ <entry>
+ Заменя неверните кодове на символи за зададен тип на документа с
+ Уникод U+FFFD (при UTF-8) или &#FFFD; (при използване на друго кодиране),
+ вместо да ги оставя както са си. Това може да е полезно, например
+ за осигуряване на добре форматирани 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>charset</parameter></term>
+ <term><parameter>encoding</parameter></term>
<listitem>
+ &strings.parameter.encoding;
<para>
- Дефинира набора от знаци, който да се
- използва при преобразуването.
- По подразбиране се използва ISO-8859-1.
+ За целите на тази функция, кодиранията
+ <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>
@@ -105,9 +185,8 @@
<term><parameter>double_encode</parameter></term>
<listitem>
<para>
- Когато параметърът <parameter>double_encode</parameter>
- е изключен, PHP няма да извърпи кодиране на съществуващите
- html единици, по подразбиране се преобразува всичко.
+ Когато параметърът <parameter>double_encode</parameter> е изключен, PHP няма
+ да извърши кодиране на съществуващите html единици, по подразбиране се преобразува всичко.
</para>
</listitem>
</varlistentry>
@@ -120,6 +199,12 @@
<para>
Преобразуваният низ.
</para>
+ <para>
+ Ако входният низ <parameter>string</parameter> съдържа невалидна
+ последователност от знаци в указаното кодиране, то ще бъде върнат
+ празен низ, освен ако не са установени флаговете
+ <constant>ENT_IGNORE</constant> или <constant>ENT_SUBSTITUTE</constant>.
+ </para>
</refsect1>
<refsect1 role="changelog">
@@ -134,18 +219,34 @@
</row>
</thead>
<tbody>
+ &strings.changelog.encoding;
<row>
- <entry>5.2.3</entry>
+ <entry>5.4.0</entry>
<entry>
- Добавен е параметърът <parameter>double_encode</parameter>.
+ Стойността по подразбиране за параметъра <parameter>encoding</parameter>
+ беше променена на UTF-8.
</entry>
</row>
<row>
- <entry>4.1.0</entry>
+ <entry>5.4.0</entry>
<entry>
- Добавен е параметърът <parameter>charset</parameter>.
+ Добавени са константите <constant>ENT_SUBSTITUTE</constant>, <constant>ENT_DISALLOWED</constant>,
+ <constant>ENT_HTML401</constant>, <constant>ENT_XML1</constant>,
+ <constant>ENT_XHTML</constant> и <constant>ENT_HTML5</constant>.
</entry>
</row>
+ <row>
+ <entry>5.3.0</entry>
+ <entry>
+ Добавена е константата <constant>ENT_IGNORE</constant>.
+ </entry>
+ </row>
+ <row>
+ <entry>5.2.3</entry>
+ <entry>
+ Добавен е параметърът <parameter>double_encode</parameter>.
+ </entry>
+ </row>
</tbody>
</tgroup>
</informaltable>