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> or <link
linkend="ref.yaz">YAZ</link> extensions.  This is due to the fact that they
both share the same internal symbol.</simpara></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 array.resetspointer '<note><simpara>This function will 
<function>reset</function> the <type>array</type> pointer after 
use.</simpara></note>'>

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

<!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>'>

<!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.'>


<!-- 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.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.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>'>

<!-- 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>'>

<!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>'>

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

<!-- 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>'>

<!-- 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>Do not use Apache 2.0.x
and PHP in a production environment neither on Unix nor on Windows.  For
information on why, read the following 
<link linkend="faq.installation.apache2">FAQ entry</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.Editors 'Authors and Editors'>

<!ENTITY Credit.Past.Authors.Text 'Although not active currently,
the following contributors made a big impact with adding content
to the manual previously:'>

<!ENTITY Credit.Past.Editors.Text 'Although not active currently,
the following contributors helped with a lot of editing around
the manual previously:'>

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

<!ENTITY Credit.Note.Editors.Active 'Currently active maintainers are:'>

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

<!ENTITY listendand ', and'>