sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-15 16:38:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

ref.strings (a* => c*): Switch to new doc style

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@237388 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Mehdi Achour 2007-06-11 00:50:48 +00:00
parent a988f7effc
commit c7d32a20aa
12 changed files with 614 additions and 185 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

150
reference/strings/functions/addcslashes.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
<!-- $Revision: 1.11 $ -->
<refentry id="function.addcslashes">
<refnamediv>
<refname>addcslashes</refname>
<refpurpose>Quote string with slashes in a C style</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>addcslashes</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
@ -15,21 +15,89 @@
</methodsynopsis>
<para>
Returns a string with backslashes before characters that are
listed in <parameter>charlist</parameter> parameter. If
<parameter>charlist</parameter> contains characters
<literal>\n</literal>, <literal>\r</literal> etc., they are
converted in C-like style, while other non-alphanumeric characters
with ASCII codes lower than 32 and higher than 126 converted to
octal representation.
listed in <parameter>charlist</parameter> parameter.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
Be careful if you choose to escape characters 0, a, b, f, n, r,
t and v. They will be converted to \0, \a, \b, \f, \n, \r, \t
and \v.
In PHP \0 (NULL), \r (carriage return), \n (newline) and \t (tab)
are predefined escape sequences, while in C all of these are
predefined escape sequences.
<variablelist>
<varlistentry>
<term><parameter>str</parameter></term>
<listitem>
<para>
The string to be escaped.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>charlist</parameter></term>
<listitem>
<para>
A list of characters to be escaped. If
<parameter>charlist</parameter> contains characters
<literal>\n</literal>, <literal>\r</literal> etc., they are
converted in C-like style, while other non-alphanumeric characters
with ASCII codes lower than 32 and higher than 126 converted to
octal representation.
</para>
<para>
When you define a sequence of characters in the charlist argument
make sure that you know what characters come between the
characters that you set as the start and end of the range.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
echo addcslashes('foo[ ]', 'A..z');
// output: \f\o\o\[ \]
// All upper and lower-case letters will be escaped
// ... but so will the [\]^_` and any tabs, line
// feeds, carriage returns, etc.
?>
]]>
</programlisting>
</informalexample>
Also, if the first character in a range has a higher ASCII value
than the second character in the range, no range will be
constructed. Only the start, end and period characters will be
escaped. Use the <function>ord</function> function to find the
ASCII value for a character.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
echo addcslashes("zoo['.']", 'z..A');
// output: \zoo['\.']
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
Be careful if you choose to escape characters 0, a, b, f, n, r,
t and v. They will be converted to \0, \a, \b, \f, \n, \r, \t
and \v.
In PHP \0 (NULL), \r (carriage return), \n (newline) and \t (tab)
are predefined escape sequences, while in C all of these are
predefined escape sequences.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the escaped string.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<parameter>charlist</parameter> like "\0..\37", which would
escape all characters with ASCII code between 0 and 31.
@ -44,47 +112,21 @@ $escaped = addcslashes($not_escaped, "\0..\37!@\177..\377");
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
When you define a sequence of characters in the charlist argument
make sure that you know what characters come between the
characters that you set as the start and end of the range.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
echo addcslashes('foo[ ]', 'A..z');
// output: \f\o\o\[ \]
// All upper and lower-case letters will be escaped
// ... but so will the [\]^_` and any tabs, line
// feeds, carriage returns, etc.
?>
]]>
</programlisting>
</informalexample>
Also, if the first character in a range has a higher ASCII value
than the second character in the range, no range will be
constructed. Only the start, end and period characters will be
escaped. Use the <function>ord</function> function to find the
ASCII value for a character.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
echo addcslashes("zoo['.']", 'z..A');
// output: \zoo['\.']
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
See also <function>stripcslashes</function>,
<function>stripslashes</function>,
<function>addslashes</function>,
<function>htmlspecialchars</function>, and
<function>quotemeta</function>.
<simplelist>
<member><function>stripcslashes</function></member>
<member><function>stripslashes</function></member>
<member><function>addslashes</function></member>
<member><function>htmlspecialchars</function></member>
<member><function>quotemeta</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

54
reference/strings/functions/addslashes.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
<!-- $Revision: 1.6 $ -->
<refentry id="function.addslashes">
<refnamediv>
<refname>addslashes</refname>
<refpurpose>Quote string with slashes</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>addslashes</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
@ -42,6 +42,33 @@
<function>get_magic_quotes_gpc</function> may come in handy for
checking this.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>str</parameter></term>
<listitem>
<para>
The string to be escaped.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the escaped string.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>An <function>addslashes</function> example</title>
@ -57,15 +84,22 @@ echo addslashes($str);
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>stripslashes</function>,
<function>stripcslashes</function>,
<function>addcslashes</function>,
<function>htmlspecialchars</function>,
<function>quotemeta</function>, and
<function>get_magic_quotes_gpc</function>.
<simplelist>
<member><function>stripcslashes</function></member>
<member><function>stripslashes</function></member>
<member><function>addcslashes</function></member>
<member><function>htmlspecialchars</function></member>
<member><function>quotemeta</function></member>
<member><function>get_magic_quotes_gpc</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

41
reference/strings/functions/bin2hex.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
<!-- $Revision: 1.4 $ -->
<refentry id="function.bin2hex">
<refnamediv>
<refname>bin2hex</refname>
<refpurpose>Convert binary data into hexadecimal representation</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>bin2hex</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
@ -17,10 +17,41 @@
of <parameter>str</parameter>. The conversion is done byte-wise
with the high-nibble first.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
See also <function>pack</function> and <function>unpack</function>.
<variablelist>
<varlistentry>
<term><parameter>str</parameter></term>
<listitem>
<para>
A character.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the hexadecimal representation of the given string.
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>pack</function></member>
<member><function>unpack</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

8
reference/strings/functions/chop.xml
View file

@ -1,6 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
<!-- $Revision: 1.4 $ -->
<refentry id="function.chop">
<refnamediv>
<refname>chop</refname>
@ -13,6 +12,10 @@
&info.function.alias;
<function>rtrim</function>.
</simpara>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
<function>chop</function> is different than the Perl
@ -21,6 +24,7 @@
</para>
</note>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

56
reference/strings/functions/chr.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
<!-- $Revision: 1.6 $ -->
<refentry id="function.chr">
<refnamediv>
<refname>chr</refname>
<refpurpose>Return a specific character</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>chr</methodname>
<methodparam><type>int</type><parameter>ascii</parameter></methodparam>
@ -15,6 +15,38 @@
<para>
Returns a one-character string containing the character specified
by <parameter>ascii</parameter>.
</para>
<para>
This function complements <function>ord</function>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>ascii</parameter></term>
<listitem>
<para>
The ascii code.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the specified character.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>chr</function> example</title>
<programlisting role="php">
@ -31,16 +63,18 @@ $str = sprintf("The string ends in escape: %c", 27);
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
You can find an ASCII-table over here: <ulink url="&url.asciitable;"
>&url.asciitable;</ulink>.
</para>
<para>
This function complements <function>ord</function>. See also
<function>sprintf</function> with a format string of
<literal>%c</literal>.
<simplelist>
<member><function>sprintf</function> with a format string of <literal>%c</literal></member>
<member>An <ulink url="&url.asciitable;">ASCII-table</ulink></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

78
reference/strings/functions/chunk-split.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
<!-- $Revision: 1.10 $ -->
<refentry id="function.chunk-split">
<refnamediv>
<refname>chunk_split</refname>
<refpurpose>Split a string into smaller chunks</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>chunk_split</methodname>
<methodparam><type>string</type><parameter>body</parameter></methodparam>
@ -17,9 +17,53 @@
<para>
Can be used to split a string into smaller chunks which is useful for
e.g. converting <function>base64_encode</function> output to match RFC
2045 semantics. It inserts <parameter>end</parameter> (defaults to
"\r\n") every <parameter>chunklen</parameter> characters (defaults to
76). It returns the new string leaving the original string untouched.
2045 semantics. It inserts <parameter>end</parameter> every
<parameter>chunklen</parameter> characters.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>body</parameter></term>
<listitem>
<para>
The string to be chunked.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>chunklen</parameter></term>
<listitem>
<para>
The chunk length. Defaults to 76.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>end</parameter></term>
<listitem>
<para>
The line ending sequence. Defaults to "\r\n".
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the chunked string.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>chunk_split</function> example</title>
<programlisting role="php">
@ -32,13 +76,21 @@ $new_string = chunk_split(base64_encode($data));
</programlisting>
</example>
</para>
<simpara>
See also <function>str_split</function>,
<function>explode</function>, <function>split</function>,
<function>wordwrap</function> and
<ulink url="&url.rfc;2045">RFC 2045</ulink>.
</simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>str_split</function></member>
<member><function>explode</function></member>
<member><function>split</function></member>
<member><function>wordwrap</function></member>
<member><ulink url="&url.rfc;2045">RFC 2045</ulink></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

60
reference/strings/functions/convert-cyr-string.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
<!-- $Revision: 1.5 $ -->
<refentry id="function.convert-cyr-string">
<refnamediv>
<refname>convert_cyr_string</refname>
<refpurpose>Convert from one Cyrillic character set to another</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>convert_cyr_string</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
@ -15,11 +15,42 @@
<methodparam><type>string</type><parameter>to</parameter></methodparam>
</methodsynopsis>
<para>
This function returns the given string converted from one
Cyrillic character set to another. The <parameter>from</parameter>
and <parameter>to</parameter> arguments are single characters that
represent the source and target Cyrillic character sets. The
supported types are:
Converts from one Cyrillic character set to another.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>str</parameter></term>
<listitem>
<para>
The string to be converted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>from</parameter></term>
<listitem>
<para>
The source Cyrillic character set, as a single character.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>to</parameter></term>
<listitem>
<para>
The target Cyrillic character set, as a single character.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Supported characters are:
<itemizedlist>
<listitem>
<simpara>
@ -53,9 +84,20 @@
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the converted string.
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
&note.bin-safe;
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

43
reference/strings/functions/convert-uudecode.xml
View file

@ -1,12 +1,13 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<refentry id="function.convert-uudecode">
<refnamediv>
<refname>convert_uudecode</refname>
<refpurpose>Decode a uuencoded string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>convert_uudecode</methodname>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
@ -14,6 +15,33 @@
<para>
<function>convert_uudecode</function> decodes a uuencoded string.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
The uuencoded data.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the decoded data as a string.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>convert_uudecode</function> example</title>
@ -27,10 +55,17 @@ echo convert_uudecode("+22!L;W9E(%!(4\"$`\n`");
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>convert_uuencode</function>.
<simplelist>
<member><function>convert_uuencode</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

45
reference/strings/functions/convert-uuencode.xml
View file

@ -1,12 +1,13 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<refentry id="function.convert-uuencode">
<refnamediv>
<refname>convert_uuencode</refname>
<refpurpose>Uuencode a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>convert_uuencode</methodname>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
@ -20,6 +21,33 @@
characters, making them safe for network transmissions. Uuencoded data is
about 35% larger than the original.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
The data to be encoded.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the uuencoded data.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>convert_uuencode</function> example</title>
@ -34,11 +62,18 @@ echo convert_uuencode($some_string);
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>convert_uudecode</function> and
<function>base64_encode</function>.
<simplelist>
<member><function>convert_uudecode</function></member>
<member><function>base64_encode</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

60
reference/strings/functions/count-chars.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.4 -->
<!-- $Revision: 1.9 $ -->
<refentry id="function.count-chars">
<refnamediv>
<refname>count_chars</refname>
<refpurpose>Return information about characters used in a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>count_chars</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
@ -16,8 +16,37 @@
<para>
Counts the number of occurrences of every byte-value (0..255) in
<parameter>string</parameter> and returns it in various ways.
The optional parameter <parameter>mode</parameter> defaults to
0. Depending on <parameter>mode</parameter>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>string</parameter></term>
<listitem>
<para>
The examined string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
The optional parameter <parameter>mode</parameter> defaults to 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Depending on <parameter>mode</parameter>
<function>count_chars</function> returns one of the following:
<itemizedlist>
<listitem>
@ -50,6 +79,10 @@
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>count_chars</function> example</title>
@ -82,11 +115,18 @@ There were 1 instance(s) of "w" in the string.
</screen>
</example>
</para>
<simpara>
See also <function>strpos</function> and
<function>substr_count</function>.
</simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>strpos</function></member>
<member><function>substr_count</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

51
reference/strings/functions/crc32.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.37 -->
<!-- $Revision: 1.8 $ -->
<refentry id="function.crc32">
<refnamediv>
<refname>crc32</refname>
<refpurpose>Calculates the crc32 polynomial of a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>crc32</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
@ -23,11 +23,40 @@
<function>sprintf</function> or <function>printf</function> to get
the string representation of the unsigned crc32 checksum.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>str</parameter></term>
<listitem>
<para>
The data.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
This second example shows how to print a converted checksum with the
<function>printf</function> function:
<example>
<title>Displaying a crc32 checksum</title>
<para>
This example shows how to print a converted checksum with the
<function>printf</function> function:
</para>
<programlisting role="php">
<![CDATA[
<?php
@ -38,10 +67,18 @@ printf("%u\n", $checksum);
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
See also <function>md5</function> and <function>sha1</function>.
<simplelist>
<member><function>md5</function></member>
<member><function>sha1</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

153
reference/strings/functions/crypt.xml
View file

@ -1,13 +1,13 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
<!-- $Revision: 1.13 $ -->
<refentry id="function.crypt">
<refnamediv>
<refname>crypt</refname>
<refpurpose>One-way string encryption (hashing)</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>crypt</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
@ -16,16 +16,9 @@
<para>
<function>crypt</function> will return an encrypted string using the
standard Unix <abbrev>DES</abbrev>-based encryption algorithm or
alternative algorithms that may be available on the system. Arguments
are a string to be encrypted and an optional salt string to base the
encryption on. See the Unix man page for your crypt function for more
information.
alternative algorithms that may be available on the system.
</para>
<simpara>
If the salt argument is not provided, one will be randomly
generated by PHP each time you call this function.
</simpara>
<simpara>
<para>
Some operating systems support more than one type of encryption. In
fact, sometimes the standard DES-based encryption is replaced by an
MD5-based encryption algorithm. The encryption type is triggered by the
@ -34,16 +27,11 @@
salt is provided, PHP will auto-generate a standard two character salt by
default, unless the default encryption type on the system is MD5, in
which case a random MD5-compatible salt is generated. PHP sets a
constant named CRYPT_SALT_LENGTH which tells you whether a regular two
character salt applies to your system or the longer twelve character salt
is applicable.
</simpara>
<simpara>
If you are using the supplied salt, you should be aware that the salt is
generated once. If you are calling this function repeatedly, this may
impact both appearance and security.
</simpara>
<simpara>
constant named <constant>CRYPT_SALT_LENGTH</constant> which tells you
whether a regular two character salt applies to your system or the longer
twelve character salt is applicable.
</para>
<para>
The standard DES-based encryption <function>crypt</function> returns the
salt as the first two characters of the output. It also only uses the
first eight characters of <parameter>str</parameter>, so longer strings
@ -58,36 +46,72 @@
<itemizedlist>
<listitem>
<simpara>
CRYPT_STD_DES - Standard DES-based encryption with a two character salt
<constant>CRYPT_STD_DES</constant> - Standard DES-based encryption with a two character salt
</simpara>
</listitem>
<listitem>
<simpara>
CRYPT_EXT_DES - Extended DES-based encryption with a nine character salt
<constant>CRYPT_EXT_DES</constant> - Extended DES-based encryption with a nine character salt
</simpara>
</listitem>
<listitem>
<simpara>
CRYPT_MD5 - MD5 encryption with a twelve character salt starting with
<constant>CRYPT_MD5</constant> - MD5 encryption with a twelve character salt starting with
$1$
</simpara>
</listitem>
<listitem>
<simpara>
CRYPT_BLOWFISH - Blowfish encryption with a sixteen character salt
<constant>CRYPT_BLOWFISH</constant> - Blowfish encryption with a sixteen character salt
starting with $2$ or $2a$
</simpara>
</listitem>
</itemizedlist>
<note>
<simpara>
There is no decrypt function, since <function>crypt</function>
uses a one-way algorithm.
</simpara>
</note>
<example>
<title><function>crypt</function> examples</title>
<programlisting role="php">
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>str</parameter></term>
<listitem>
<para>
The string to be encrypted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>salt</parameter></term>
<listitem>
<para>
An optional salt string to base the encryption on. If not provided,
one will be randomly generated by PHP each time you call this function.
</para>
<para>
If you are using the supplied salt, you should be aware that the salt
is generated once. If you are calling this function repeatedly, this
may impact both appearance and security.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the encrypted string.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>crypt</function> examples</title>
<programlisting role="php">
<![CDATA[
<?php
$password = crypt('mypassword'); // let the salt be automatically generated
@ -101,11 +125,11 @@ if (crypt($user_input, $password) == $password) {
}
?>
]]>
</programlisting>
</example>
<example>
<title>Using <function>crypt</function> with htpasswd</title>
<programlisting role="php">
</programlisting>
</example>
<example>
<title>Using <function>crypt</function> with htpasswd</title>
<programlisting role="php">
<![CDATA[
<?php
// Set the password
@ -115,11 +139,11 @@ $password = 'mypassword';
$hash = crypt($password);
?>
]]>
</programlisting>
</example>
<example>
<title>Using <function>crypt</function> with different encryption types</title>
<programlisting role="php">
</programlisting>
</example>
<example>
<title>Using <function>crypt</function> with different encryption types</title>
<programlisting role="php">
<![CDATA[
<?php
if (CRYPT_STD_DES == 1) {
@ -139,22 +163,41 @@ if (CRYPT_BLOWFISH == 1) {
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Standard DES: rl.3StKT.4T8M
Extended DES: _J9..rasmBYk8r9AiWNc
MD5: $1$rasmusle$rISCgZzpwk3UhDidwXvin0
Blowfish: $2a$07$rasmuslerd............nIdrcHdxcUxWomQX9j6kvERCFjTg7Ra
]]>
</screen>
</example>
<simpara>
See also <function>md5</function> and <link linkend="ref.mcrypt">the
Mcrypt extension</link>.
</simpara>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<simpara>
There is no decrypt function, since <function>crypt</function> uses a
one-way algorithm.
</simpara>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>md5</function></member>
<member>The <link linkend="ref.mcrypt">Mcrypt</link> extension</member>
<member>The Unix man page for your crypt function for more information</member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file