php-doc-en/language-snippets.ent

<!-- $Revision$ -->
<!-- Keep 'em sorted -->


<!-- Notes -->

<!ENTITY note.bin-safe '<note><simpara>This function is
binary-safe.</simpara></note>'>

<!ENTITY note.clearstatcache '<note><simpara>The results of this 
function are cached. See <function>clearstatcache</function> for 
more details.</simpara></note>'>

<!ENTITY note.context-support '<note><simpara>Context support was added
with PHP 5.0.0.</simpara></note>'>

<!ENTITY note.exec-bg '<note><para>If you start a program using this function
and want to leave it running in the background, you have to make sure that the
output of that program is redirected to a file or some other output stream or
else PHP will hang until the execution of the program ends.</para></note>'>

<!ENTITY note.func-callback '<note><simpara>Instead of a function name, an
array containing an object reference and a method name can also be
supplied.</simpara></note>'>

<!ENTITY note.line-endings '<note><simpara>If you are having problems
with PHP not recognizing the line endings when reading files either on or
created by a Macintosh computer, you might want to enable the
<link linkend="ini.auto-detect-line-endings">auto_detect_line_endings</link>
run-time configuration option.</simpara></note>'>

<!ENTITY note.no-remote '<note><simpara>This function will not work on 
<link linkend="features.remote-files">remote files</link> as the file to
be examined must be accessible via the servers filesystem.</simpara></note>'>

<!ENTITY note.not-bin-safe '<warning><simpara>This function
is not (yet) binary safe!</simpara></warning>'>

<!ENTITY note.no-windows '<note><simpara>This function is not
implemented on Windows platforms.</simpara></note>'>

<!ENTITY note.no-windows.extension '<note><simpara>This extension is not
available on Windows platforms.</simpara></note>'>

<!ENTITY note.randomseed '<note><simpara>As of PHP 4.2.0, there is no need 
to seed the random number generator with <function>srand</function> or 
<function>mt_srand</function> as this is now done automatically.
</simpara></note>'>

<!ENTITY note.registerglobals '<note><title>register_globals: important 
note</title><para>Since PHP 4.2.0, the default value for the PHP directive 
<link linkend="ini.register-globals">register_globals</link> is <emphasis>
off</emphasis>.  The PHP community encourages all to not rely on this 
directive but instead use other means, such as the &link.superglobals;.
</para></note>'>

<!ENTITY note.superglobals '<note><title>Superglobals: availability note
</title><para>Since PHP 4.1.0, superglobal arrays such as <varname>$_GET
</varname>, <varname>$_POST</varname>, and <varname>$_SERVER</varname>, 
etc. have  been available.  For more information, read the manual section 
on &link.superglobals;</para></note>'>

<!-- Tips -->

<!ENTITY tip.fopen-wrapper '<tip><simpara>You can use a URL as a
filename with this function if the <link linkend="ini.allow-url-fopen"
>fopen wrappers</link> have been enabled.
See <function>fopen</function> for more details on how to specify
the filename and <xref linkend="wrappers"/> for a list of supported
URL protocols.</simpara></tip>'>

<!ENTITY tip.fopen-wrapper.stat '<tip><simpara>As of PHP 5.0.0 this function
can also be used with <emphasis>some</emphasis> URL wrappers.  Refer to 
<xref linkend="wrappers"/> for a listing of which wrappers support 
<function>stat</function> family of functionality.</simpara></tip>'>

<!ENTITY tip.ob-capture '<tip><simpara>As with anything that outputs
its result directly to the browser, you can use the <link
linkend="ref.outcontrol">output-control functions</link> to capture
the output of this function, and save it in a
<type>string</type> (for example).</simpara></tip>'>


<!-- Warnings -->

<!ENTITY warn.escapeshell '<warning><para>If you are going to allow data coming
from user input to be passed to this function, then you should be using 
<function>escapeshellarg</function> or <function>escapeshellcmd</function>
to make sure that users cannot trick the system into executing arbitrary
commands.</para></warning>'>

<!ENTITY warn.experimental '<warning><simpara>This extension is
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this extension --
including the names of its functions and anything else documented
about this extension -- may change without notice in a future release of PHP. 
Use this extension at your own risk.</simpara></warning>'>

<!ENTITY warn.experimental.func '<warning><simpara>This function is
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this function, the
name of this function, and anything else documented about this
function may change without notice in a future release of PHP. 
Use this function at your own risk.</simpara></warning>'>

<!ENTITY warn.imaprecodeyaz '<warning><simpara>The <link
linkend="ref.imap">IMAP</link> extension cannot be used in conjuction with
the <link linkend="ref.recode">recode</link>, <link
linkend="ref.yaz">YAZ</link> or <link
linkend="ref.cyrus">Cyrus</link> extensions.  This is due to the fact that they
both share the same internal symbol.</simpara></warning>'>

<!ENTITY warn.install.cgi '<warning><para>By using the CGI setup, your server
is open to several possible attacks. Please read our
<link linkend="security.cgi-bin">CGI security section</link> to learn how to
defend yourself from those attacks.</para></warning>'>

<!ENTITY note.magicquotes.gpc '<note><title>directive note: magic_quotes_gpc
</title><para>The PHP directive <link linkend="ini.magic-quotes-gpc">
magic_quotes_gpc</link> defaults to <literal>on</literal>.  It essentially 
runs <function>addslashes</function> on all your GET,  POST, and COOKIE data.
You may use <function>stripslashes</function> to strip them.</para></note>'>

<!ENTITY warn.no-win32-fopen-wrapper '<warning><para>Windows versions of PHP
prior to PHP 4.3.0 do not support accessing remote files via this function, even if
<link linkend="ini.allow-url-fopen">allow_url_fopen</link> is enabled.
</para></warning>'>

<!ENTITY warn.ssl-non-standard '<warning><para>When using SSL, Microsoft IIS
will violate the protocol by closing the connection without sending a
close_notify indicator.  PHP will report this as "SSL: Fatal Protocol Error"
when you reach the end of the data.  To workaround this, you should lower your
<link linkend="ini.error-reporting">error_reporting</link> level not to include warnings.
PHP 4.3.7 and higher can detect buggy IIS server software when you open
the stream using the https:// wrapper and will suppress the warning for you.
If you are using <function>fsockopen</function> to create an ssl:// socket,
you are responsible for detecting and suppressing the warning yourself.
</para></warning>'>

<!ENTITY warn.undocumented.func '<warning><simpara>This function is
currently not documented; only the argument list is
available.</simpara></warning>'>


<!-- Misc -->

<!ENTITY example.outputs '<para>The above example will output:</para>'>

<!ENTITY example.outputs.similar '<para>The above example will output 
something similar to:</para>'>

<!ENTITY array.resetspointer '<note><simpara>This function will 
<function>reset</function> the <type>array</type> pointer after 
use.</simpara></note>'>

<!ENTITY seealso.callback 'information about the <link linkend="language.types.callback">callback</link> type'>

<!ENTITY avail.register-long-arrays 'As of PHP 5.0.0, the long PHP 
<link linkend="language.variables.predefined">predefined variable</link>
arrays may be disabled with the 
<link linkend="ini.register-long-arrays">register_long_arrays</link>
directive.'>

<!ENTITY ini.shorthandbytes '<simpara>When an <type>integer</type> is used, the 
value is measured in bytes.  You may also use shorthand notation as described 
in <link linkend="faq.using.shorthandbytes">this FAQ</link>.</simpara>'>

<!ENTITY info.deprecated.alias 'For downward compatibility, the following 
deprecated alias may be used: '>

<!-- Returns -->

<!ENTITY return.success 'Returns &true; on success or &false; on failure.'>

<!ENTITY return.void 'No value is returned.'>

<!ENTITY return.falseproblem '<warning><simpara>This function may
return Boolean &false;, but may also return a non-Boolean value which
evaluates to &false;, such as <literal>0</literal> or
&quot;&quot;. Please read the section on <link
linkend="language.types.boolean">Booleans</link> for more
information. Use <link linkend="language.operators.comparison">the ===
operator</link> for testing the return value of this
function.</simpara></warning>'>




<!-- Image (GD) Notes -->
<!ENTITY note.config.t1lib '<note><simpara>This function is only available 
if PHP is compiled using <option role="configure">--with-t1lib[=DIR]</option>.
</simpara></note>'>

<!ENTITY note.config.jpeg '<note><simpara>JPEG support is only available if 
PHP was compiled against GD-1.8 or later.</simpara></note>'>

<!ENTITY note.config.wbmp '<note><simpara>WBMP support is only available if 
PHP was compiled against GD-1.8 or later.</simpara></note>'>

<!ENTITY note.bundled.gd '<note><simpara>This function is only available if
PHP is compiled with the bundled version of the GD library.</simpara></note>'>

<!ENTITY note.gd.2 '<note><simpara>This function requires GD 2.0.1 or later.</simpara></note>'>

<!-- DomXml Notes -->
<!ENTITY node.inserted 'This node will not show up in the document unless it
is inserted with e.g. <function>domnode_append_child</function>.'>


<!-- Dom Notes -->
<!ENTITY dom.node.inserted 'This node will not show up in the document unless 
it is inserted with e.g. <link 
linkend="function.dom-domnode-appendchild">DOMNode->appendChild()</link>.'>


<!-- FileSystem entities -->
<!ENTITY fs.validfp.all '<para>The file pointer must be valid, and must point to
a file successfully opened by <function>fopen</function> or
<function>fsockopen</function>.</para>'>

<!-- Oracle -->
<!ENTITY oci.charset "<para>Using Oracle server version 9.2 and greater, you can
indicate <parameter>charset</parameter> parameter, which will be used in the new
connection. If you're using Oracle server &lt; 9.2, this parameter will be ignored
and NLS_LANG environment variable will be used instead.</para>">

<!-- PCNTL Notes -->
<!ENTITY pcntl.parameter.status '<para>The parameter 
<parameter>status</parameter> is the status parameter supplied to a successfull
call to <function>pcntl_waitpid</function>.</para>'>


<!-- XSLT Notes -->
<!ENTITY note.xslt.windows '<note><para>Please note that <emphasis>file://</emphasis>
is needed in front of path if you use Windows.</para></note>'>


<!-- Notes for safe-mode limited functions: -->
<!ENTITY note.sm.disabled '<note><simpara>&sm.disabled;</simpara></note>'>

<!ENTITY note.sm.uidcheck '<note><simpara>When <link 
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether 
the files or directories you are about to operate on have the same UID (owner) as the 
script that is being executed.</simpara></note>'>

<!ENTITY note.sm.uidcheck.dir '<note><simpara>When <link 
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether 
the directory in which you are about to operate has the same UID (owner) as the 
script that is being executed.</simpara></note>'>

<!ENTITY note.open-basedir.func '<note><para>This function is affected by <link 
linkend="ini.open-basedir">open_basedir</link>.</para></note>'>


<!ENTITY note.language-construct '<note><simpara>Because this is a 
language construct and not a function, it cannot be called using 
<link linkend="functions.variable-functions">variable functions</link></simpara>
</note>'>

<!-- Common pieces in features/safe-mode.xml 
     Jade doesn't allow in-line entities, so I put them here... Though they 
     should have been inline in safe-mode.xml -->
<!ENTITY sm.uidcheck 'Checks whether the files or directories you are 
about to operate on have the same UID (owner) as the script that is being
executed.'>

<!ENTITY warn.sm.exec '<warning><simpara>With <link linkend="features.safe-mode">safe mode</link> enabled,
all words following the initial command string are treated as a single argument. Thus, 
<literal>echo y | echo x</literal> becomes <literal>echo "y | echo x"</literal>.</simpara></warning>'>

<!ENTITY note.exec-path '<note><simpara>When
<link linkend="features.safe-mode">safe mode</link> is enabled, you can only
execute executables within the <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
For practical reasons it is currently not allowed to have <literal>..</literal>
components in the path to the executable. </simpara></note>'>

<!ENTITY sm.uidcheck.dir 'Checks whether the directory in which
you are about to operate has the same UID (owner) as the script that is being
executed.'>

<!ENTITY sm.disabled 'This function is disabled in <link 
linkend="features.safe-mode">safe mode</link>.'>

<!-- Common pieces in partintro-sections -->
<!ENTITY no.config '<para>This extension has no configuration directives defined in &php.ini;.</para>'>
<!ENTITY no.resource '<para>This extension has no resource types defined.</para>'>
<!ENTITY no.constants '<para>This extension has no constants defined.</para>'>
<!ENTITY no.requirement '<para>No external libraries are needed to build this extension.</para>'>
<!ENTITY no.install '<para>There is no installation needed to use these
functions; they are part of the PHP core.</para>'>

<!-- Used in every chapter that has directive descriptions -->
<!ENTITY ini.descriptions.title '<para>Here&apos;s a short explanation of
the configuration directives.</para>'>

<!-- Common pieces for reference part BEGIN-->

<!-- Used in reference/$extname/ini.xml -->
<!ENTITY extension.runtime '<simpara>
The behaviour of these functions is affected by settings in &php.ini;.
</simpara>'>

<!ENTITY ini.php.constants 'For further details and definitions of the 
PHP_INI_* constants, see the <xref linkend="ini"/>.'>

<!-- Used in reference/$extname/constants.xml -->
<!ENTITY extension.constants '<simpara>
The constants below are defined by this extension, and
will only be available when the extension has either
been compiled into PHP or dynamically loaded at runtime.
</simpara>'>

<!-- For STANDARD Constants used in reference/$extname/constants.xml -->
<!ENTITY extension.constants.core '<simpara>
The constants below are always available as part of the PHP core.
</simpara>'>

<!-- Used in reference/$extname/classes.xml -->
<!ENTITY extension.classes '<simpara>
The classes below are defined by this extension, and
will only be available when the extension has either
been compiled into PHP or dynamically loaded at runtime.
</simpara>'>

<!ENTITY note.extension.php5 '<note><simpara>
This extension requires PHP 5.</simpara></note>'>

<!-- PECL entities -->
<!ENTITY pecl.moved 'This <ulink url="&url.pecl;">PECL</ulink> extension
is not bundled with PHP.'>

<!ENTITY pecl.bundled 'This <ulink url="&url.pecl;">PECL</ulink> extension
is bundled with PHP.'>

<!ENTITY pecl.info 'Additional information such as new releases,
downloads, source files, maintainer information, and a CHANGELOG, can be
located here: '>

<!ENTITY pecl.source.4 'In PHP 4 this <acronym>PECL</acronym> extensions
source can be found in the <filename>ext/</filename> directory within the
PHP source or at the <acronym>PECL</acronym> link above.'>

<!ENTITY pecl.windows.4 'In PHP 4 this <acronym>DLL</acronym> resides in
the <filename>extensions/</filename> directory within the PHP Windows
binaries download.'>

<!ENTITY pecl.windows.download 'You may download this <acronym>PECL</acronym>
extension <acronym>DLL</acronym> from the <ulink url="&url.php.downloads;">
PHP Downloads</ulink> page or at <ulink url="&url.php.snapshots;">
&url.php.snapshots;</ulink>.'>

<!ENTITY pecl.windows.download.unbundled 'You may obtain this
unbundled <acronym>PECL</acronym> extension from the various
<acronym>PECL</acronym> snaps pages (select the appropriate repository for
your version of PHP): <ulink url="&url.pecl.get.win.php4.3;">PECL for PHP
4.3.x</ulink>, <ulink url="&url.pecl.get.win.php5.0;">PECL for PHP 5.0.x
</ulink> or <ulink url="&url.pecl.get.win.unstable;">PECL Unstable</ulink>.'>

<!ENTITY pecl.moved-ver 'This extension has been moved to the <ulink 
url="&url.pecl;">PECL</ulink> repository and is no longer bundled with 
PHP as of PHP '>

<!-- kept for BC -->
<!ENTITY note.pecl-php5 '<note><simpara>
This extension has been removed as of PHP 5 and moved to the
<ulink url="&url.pecl;">PECL</ulink> repository.
</simpara></note>'>

<!-- Common pieces for reference part END -->


<!ENTITY windows.builtin '<simpara> The windows version of PHP has built in
support for this extension. You do not need to load any additional
extension in order to use these functions.</simpara>'>

<!-- These are here as helpers for manual consistency and brievety-->
<!ENTITY safemode '<link linkend="ini.safe-mode">safe mode</link>'>

<!-- Notes for SAPI/Apache -->
<!ENTITY note.apache.nsapi-module '<note><para>As of PHP 4.3.3 you can use this function with the
<link linkend="ref.nsapi">NSAPI server module</link> in Netscape/iPlanet/SunONE
webservers, too.</para></note>'>

<!-- SimpleXML Notes -->
<!ENTITY simplexml.iteration '<note><simpara>SimpleXML has made a rule of adding
iterative properties to most methods. They cannot be viewed using <function>var_dump</function>
or anything else which can examine objects.</simpara></note>'>

<!-- SQLite Notes -->
<!ENTITY sqlite.case-fold '<para>The column names returned by
<constant>SQLITE_ASSOC</constant> and <constant>SQLITE_BOTH</constant> will be
case-folded according to the value of the
<link linkend="ini.sqlite.assoc-case">sqlite.assoc_case</link> configuration
option.</para>'>

<!ENTITY sqlite.decode-bin '<para>When the <parameter>decode_binary</parameter>
parameter is set to &true; (the default), PHP will decode the binary encoding
it applied to the data if it was encoded using the
<function>sqlite_escape_string</function>.  You should normally leave this
value at its default, unless you are interoperating with databases created by
other sqlite capable applications.</para>'>

<!ENTITY sqlite.no-unbuffered '<note><para>This function cannot be used with 
unbuffered result handles.</para></note>'>

<!ENTITY sqlite.param-compat '<note><simpara>Two alternative syntaxes are
supported for compatibility with other database extensions (such as MySQL).
The preferred form is the first, where the <parameter>dbhandle</parameter>
parameter is the first parameter to the function.</simpara></note>'>

<!ENTITY sqlite.result-type '<para>The optional <parameter>result_type</parameter>
parameter accepts a constant and determines how the returned array will be
indexed. Using <constant>SQLITE_ASSOC</constant> will return only associative
indices (named fields) while <constant>SQLITE_NUM</constant> will return
only numerical indices (ordinal field numbers). <constant>SQLITE_BOTH</constant>
will return both associative and numerical indices.
<constant>SQLITE_BOTH</constant> is the default for this function.</para>'>

<!-- Database Notes -->
<!ENTITY database.field-case '<note><simpara>Field names returned by this function
are <emphasis>case-sensitive</emphasis>.</simpara></note>'>

<!ENTITY database.fetch-null '<note><simpara>This function sets NULL fields to
PHP &null; value.</simpara></note>'>

<!-- MySQL Notes -->
<!-- The mysql.*.description entities are used in the parameters refsect1 -->
<!ENTITY mysql.linkid.description '<varlistentry><term><parameter>
link_identifier</parameter></term><listitem><para>The MySQL connection. If the 
link identifier is not specified, the last link opened by 
<function>mysql_connect</function> is assumed. If no such link is found, it
will try to create one as if <function>mysql_connect</function> was called
with no arguments. If by chance no connection is found or established, an
<constant>E_WARNING</constant> level warning is generated.</para></listitem>
</varlistentry>'>

<!ENTITY mysql.result.description '<varlistentry><term><parameter>
result</parameter></term><listitem><para>The result <type>resource</type> that
is being evaluated. This result comes from a call to 
<function>mysql_query</function>.</para></listitem></varlistentry>'>

<!ENTITY mysql.field-offset.req.description '<varlistentry><term><parameter>
field_offset</parameter></term><listitem><para>The numerical field offset. The 
<parameter>field_offset</parameter> starts at <literal>0</literal>. If 
<parameter>field_offset</parameter> does not exist, an error of level
<constant>E_WARNING</constant> is also issued.</para></listitem></varlistentry>'>

<!-- Sybase Notes -->
<!ENTITY sybase.ct.only '<note><simpara>This function is only available using
the CT library interface to Sybase, and not the DB library.</simpara></note>'>

<!ENTITY sybase.db.only '<note><simpara>This function is only available using
the DB library interface to Sybase, and not the CT library.</simpara></note>'>

<!-- CPDF Unit length -->
<!ENTITY cpdf.ul '<para>The optional parameter <parameter>mode</parameter>
determines the unit length. If it is 0 or omitted the default unit as specified
for the page is used. Otherwise the coordinates are measured in postscript
points disregarding the current unit.</para>'>

<!-- Xattr entities -->
<!ENTITY xattr.namespace '<para>Extended attributes have two different namespaces: user 
and root namespace. User namespace is available for all users while root namespace
is available only for user with root privileges. xattr operates on user namespace 
by default, but you can change that using <parameter>flags</parameter> argument.</para>'>

<!-- Notes for IPv6 -->
<!ENTITY ipv6.brackets '<note><simpara>When specifying a numerical IPv6 address
(e.g. fe80::1) you must enclose the IP in square brackets.  For example,  
<literal>tcp://[fe80::1]:80</literal>.</simpara></note>'>

<!ENTITY ipv6.php5 '<note><simpara>IPv6 Support was added with PHP 5.0.0.</simpara></note>'>

<!-- Notes for tidy -->
<!ENTITY note.tidy.ze2 '<note><simpara> This function is only available with Zend Engine 2,
this means PHP &gt;= 5.0.0.</simpara></note>'>

<!ENTITY note.tidy.1only '<note><simpara>This function is only avaliable in
Tidy 1.0. It became obsolete in Tidy 2.0 and thus has been removed.</simpara></note>'>

<!ENTITY note.tidy.2only '<note><simpara>The optional parameters
<parameter>config</parameter> and <parameter>encoding</parameter> were
added in Tidy 2.0.</simpara></note>'>

<!ENTITY tidy.conf-enc '<para>The <parameter>config</parameter> parameter
can be passed either as an array or as a string. If you pass it as a string,
it means the name of the configuration file, otherwise it is interpreted as
the options themselves. Check <ulink url="&url.tidy.conf;">&url.tidy.conf;</ulink>
for an explanation about each option.</para><para>The
<parameter>encoding</parameter> parameter sets the encoding for input/output
documents. The possible values for <parameter>encoding</parameter> are:
ascii, latin0, latin1, raw, utf8, iso2022, mac, win1252, ibm858, utf16,
utf16le, utf16be, big5 and shiftjis.</para>'>

<!-- Snippets for the installation section -->
<!ENTITY warn.apache2.compat '<warning><para>We do not recommend using a threaded MPM
in production with Apache2.  Use the prefork MPM instead, or use Apache1.  For information
on why, read the related FAQ entry on using
<link linkend="faq.installation.apache2">Apache2 with a threaded MPM</link></para></warning>'>

<!ENTITY note.apache.slashes '<note><simpara>Remember that when adding
path values in the Apache configuration files on Windows, all backslashes
such as <filename>c:\directory\file.ext</filename> must be converted to
forward slashes, as <filename>c:/directory/file.ext</filename>.</simpara></note>'>

<!-- Snippets and titles for the contributors section -->
<!ENTITY Credit.Authors.and.Contributors 'Authors and Contributors'>

<!ENTITY Credit.Introduction '<para> We highlight the currently most active
people on the manual frontpage, but there are many more contributors who
currently help in our work or provided a great amount of help to the project
in the past. There are a lot of unnamed people who help out with their user
notes on manual pages, which continually get included in the references, the
work of whom we are also very thankful for. All the lists provided below are in
alphabetical order.
</para>'>

<!ENTITY Credit.Authors.and.Editors 'Authors and Editors'>

<!ENTITY Credit.Past.Authors.Text 'The following contributors should be
recognized for the impact they have made and/or continue to make by adding
content to the manual:'>

<!ENTITY Credit.Past.Editors.Text 'The following contributors have done
significant work editing the manual:'>

<!ENTITY Credit.Note.Editors.Title 'User Note Maintainers'>

<!ENTITY Credit.Note.Editors.Active 'The currently most active maintainers are:'>

<!ENTITY Credit.Note.Editors.Inactive 'These people have also put a lot of effort
into managing user notes:'>

<!ENTITY listendand ' and'>

<!-- classkit entities -->
<!ENTITY note.classkit.selfmanipulation '<note><simpara>This function cannot
be used to manipulate the currently running (or chained) method.</simpara>
</note>'>