sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-17 17:38:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
php-doc-en/appendices/wrappers.xml
Nuno Lopes 5228538214 arg.. trying to get a better english 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@190812 c90b9560-bf6c-de11-be94-00142212c4b1
2005-07-16 17:00:09 +00:00

1232 lines
38 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.53 $ -->
<appendix id="wrappers">
<title>List of Supported Protocols/Wrappers</title>
<para>
The following is a list of the various URL style protocols that
PHP has built-in for use with the filesystem functions such as
<function>fopen</function> and <function>copy</function>.
In addition to these wrappers, as of PHP 4.3.0, you can write
your own wrappers using PHP script and
<function>stream_wrapper_register</function>.
</para>
<section id="wrappers.file">
<title>Filesystem</title>
<simpara>All versions of PHP. Explicitly using <filename>file://</filename> since PHP 4.3.0</simpara>
<itemizedlist>
<listitem><simpara><filename>/path/to/file.ext</filename></simpara></listitem>
<listitem><simpara><filename>relative/path/to/file.ext</filename></simpara></listitem>
<listitem><simpara><filename>fileInCwd.ext</filename></simpara></listitem>
<listitem><simpara><filename>C:/path/to/winfile.ext</filename></simpara></listitem>
<listitem><simpara><filename>C:\path\to\winfile.ext</filename></simpara></listitem>
<listitem><simpara><filename>\\smbserver\share\path\to\winfile.ext</filename></simpara></listitem>
<listitem><simpara><filename>file:///path/to/file.ext</filename></simpara></listitem>
</itemizedlist>
<simpara>
<filename>file://</filename> is the default wrapper used with PHP and represents the local filesystem.
When a relative path is specified (a path which does not begin with /, \, \\, or a windows drive letter)
the path provided will be applied against the current working directory. In many cases this is the
directory in which the script resides unless it has been changed. Using the CLI sapi, this defaults
to the directory from which the script was called.
</simpara>
<simpara>
With some functions, such as <function>fopen</function> and <function>file_get_contents</function>,
<literal>include_path</literal> may be optionally searched for relative paths as well.
</simpara>
<para>
<table>
<title>Wrapper Summary</title>
<tgroup cols="2">
<thead>
<row>
<entry>Attribute</entry>
<entry>Supported</entry>
</row>
</thead>
<tbody>
<row>
<entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link>.</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Reading</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Writing</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Appending</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Simultaneous Reading and Writing</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports <function>stat</function></entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports <function>unlink</function></entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports <function>rename</function></entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports <function>mkdir</function></entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports <function>rmdir</function></entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section id="wrappers.socket">
<title>Socket</title>
<para>
This section contains the context options supported by the wrappers that
work over sockets, like <literal>tcp</literal>, <literal>http</literal> or
<literal>ftp</literal>.
</para>
<para>
As of PHP 5.1.0 only one option is supported, <literal>bindto</literal>,
which can be used to specify the IP address (either IPv4 or IPv6) and/or
the port number that PHP will use to access the network. The syntax is
<literal>ip:port</literal> (you can set the IP or the port number to
<literal>0</literal> if you want to let the system choose them for you).
</para>
<note>
<para>
As FTP creates two socket connections during normal operation, you cannot
specify the port number in the <literal>bindto</literal> option. So, the
only supported syntax is <literal>ip:0</literal> for the FTP wrapper.
</para>
</note>
<example>
<title>Some examples of how to use the bindto option</title>
<programlisting role="php">
<![CDATA[
<?php
// connect to the internet using the '192.168.0.100' IP
$opts = array('socket' =>
array('bindto' => '192.168.0.100:0'));
// connect to the internet using the '192.168.0.100' IP and port '7000'
$opts = array('socket' =>
array('bindto' => '192.168.0.100:7000'));
// connect to the internet using port '7000'
$opts = array('socket' =>
array('bindto' => '0:7000'));
// create the context...
$context = stream_context_create($opts);
// ...and use it to fetch the data
echo file_get_contents('http://www.example.com', false, $context);
?>
]]>
</programlisting>
</example>
</section>
<section id="wrappers.http">
<title>HTTP and HTTPS</title>
<simpara>PHP 3, PHP 4, PHP 5. <filename>https://</filename> since PHP 4.3.0</simpara>
<itemizedlist>
<listitem><simpara><filename>http://example.com</filename></simpara></listitem>
<listitem><simpara><filename>http://example.com/file.php?var1=val1&amp;var2=val2</filename></simpara></listitem>
<listitem><simpara><filename>http://user:password@example.com</filename></simpara></listitem>
<listitem><simpara><filename>https://example.com</filename></simpara></listitem>
<listitem><simpara><filename>https://example.com/file.php?var1=val1&amp;var2=val2</filename></simpara></listitem>
<listitem><simpara><filename>https://user:password@example.com</filename></simpara></listitem>
</itemizedlist>
<simpara>Allows read-only access to files/resources via HTTP 1.0,
using the HTTP GET method. A <literal>Host:</literal> header is sent with the request
to handle name-based virtual hosts. If you have configured
a <link linkend="ini.user-agent">user_agent</link> string using
your ini file or the stream context, it will also be included
in the request.
</simpara>
&warn.ssl-non-standard;
<simpara>
Redirects have been supported since PHP 4.0.5; if you are using
an earlier version you will need to include trailing slashes in
your URLs. If it's important to know the URL of the resource where
your document came from (after all redirects have been processed),
you'll need to process the series of response headers returned by the
stream.
</simpara>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$url = 'http://www.example.com/redirecting_page.php';
$fp = fopen($url, 'r');
/* Prior to PHP 4.3.0 use $http_response_header
instead of stream_get_meta_data() */
$meta_data = stream_get_meta_data($fp);
foreach($meta_data['wrapper_data'] as $response) {
/* Were we redirected? */
if (substr(strtolower($response), 0, 10) == 'location: ') {
/* update $url with where we were redirected to */
$url = substr($response, 10);
}
}
?>
]]>
</programlisting>
</informalexample>
<simpara>
The stream allows access to the <emphasis>body</emphasis> of
the resource; the headers are stored in the
<varname>$http_response_header</varname> variable.
Since PHP 4.3.0, the headers are available using
<function>stream_get_meta_data</function>.
</simpara>
<simpara>
HTTP connections are read-only; you cannot write data or copy
files to an HTTP resource.
</simpara>
<note>
<simpara>HTTPS is supported starting from PHP 4.3.0, if you
have compiled in support for OpenSSL.
</simpara>
</note>
<para>
<table>
<title>Wrapper Summary</title>
<tgroup cols="2">
<thead>
<row>
<entry>Attribute</entry>
<entry>Supported</entry>
</row>
</thead>
<tbody>
<row>
<entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link>.</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Reading</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Writing</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Appending</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Simultaneous Reading and Writing</entry>
<entry>N/A</entry>
</row>
<row>
<entry>Supports <function>stat</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>unlink</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rename</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>mkdir</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rmdir</function></entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table>
<title>Context options</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Usage</entry>
<entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>method</literal></entry>
<entry>
<constant>GET</constant>, <constant>POST</constant>, or
any other HTTP method supported by the remote server.
</entry>
<entry><constant>GET</constant></entry>
</row>
<row>
<entry><literal>header</literal></entry>
<entry>Additional headers to be sent during request. Values
in this option will override other values (such as
<literal>User-agent:</literal>, <literal>Host:</literal>,
and <literal>Authentication:</literal>).
</entry>
<entry></entry>
</row>
<row>
<entry><literal>user_agent</literal></entry>
<entry>Value to send with User-Agent: header. This value will
only be used if user-agent is <emphasis>not</emphasis> specified
in the <literal>header</literal> context option above.
</entry>
<entry>
&php.ini; setting: <literal>user_agent</literal>
</entry>
</row>
<row>
<entry><literal>content</literal></entry>
<entry>
Additional data to be sent after the headers. Typically used
with POST or PUT requests.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>proxy</literal></entry>
<entry>
URI specifying address of proxy server. (e.g.
<literal>tcp://proxy.example.com:5100</literal> ).
</entry>
<entry></entry>
</row>
<row>
<entry><literal>request_fulluri</literal></entry>
<entry>
When set to &true;, the entire URI will be used when
constructing the request. (i.e.
<literal>GET http://www.example.com/path/to/file.html HTTP/1.0</literal>).
While this is a non-standard request format, some
proxy servers require it.
</entry>
<entry>&false;</entry>
</row>
<row>
<entry><literal>max_redirects</literal></entry>
<entry>
The max number of redirects to follow. Added in PHP 5.1.0.
</entry>
<entry>20</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<title>Underlying socket stream context options</title>
<simpara>
Additional context options may be supported by the
<link linkend="transports.inet">underlying transport</link>
For <literal>http://</literal> streams, refer to context
options for the <literal>tcp://</literal> transport. For
<literal>https://</literal> streams, refer to context options
for the <literal>ssl://</literal> transport.
</simpara>
</note>
</section>
<section id="wrappers.ftp">
<title>FTP and FTPS</title>
<simpara>PHP 3, PHP 4, PHP 5. <filename>ftps://</filename> since PHP 4.3.0</simpara>
<itemizedlist>
<listitem><simpara><filename>ftp://example.com/pub/file.txt</filename></simpara></listitem>
<listitem><simpara><filename>ftp://user:password@example.com/pub/file.txt</filename></simpara></listitem>
<listitem><simpara><filename>ftps://example.com/pub/file.txt</filename></simpara></listitem>
<listitem><simpara><filename>ftps://user:password@example.com/pub/file.txt</filename></simpara></listitem>
</itemizedlist>
<simpara>
Allows read access to existing files and creation of new files
via FTP. If the server does not support passive mode ftp, the
connection will fail.
</simpara>
<simpara>
You can open files for either reading or writing, but not both
simultaneously. If the remote file already exists on the ftp
server and you attempt to open it for writing but have not specified
the context option <literal>overwrite</literal>, the connection
will fail. If you need to overwrite existing files over ftp,
specify the <literal>overwrite</literal> option in the context
and open the file for writing. Alternatively, you can
use the <link linkend="ref.ftp">FTP extension</link>.
</simpara>
<note>
<title>Appending</title>
<simpara>
As of PHP 5.0.0 files may be appended via the
<literal>ftp://</literal> URL wrapper. In prior versions, attempting
to append to a file via <literal>ftp://</literal> will result in failure.
</simpara>
</note>
<simpara>
<filename>ftps://</filename> was introduced in PHP 4.3.0.
It is the same as <filename>ftp://</filename>,
but attempts to negotiate a secure connection with the ftp server.
If the server does not support SSL, then the connection falls back
to regular unencrypted ftp.
</simpara>
<note>
<simpara>FTPS is supported starting from PHP 4.3.0, if you
have compiled in support for OpenSSL.
</simpara>
</note>
<para>
<table>
<title>Wrapper Summary</title>
<tgroup cols="3">
<thead>
<row>
<entry>Attribute</entry>
<entry>PHP 4</entry>
<entry>PHP 5</entry>
</row>
</thead>
<tbody>
<row>
<entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link>.</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Reading</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Writing</entry>
<entry>Yes (new files only)</entry>
<entry>Yes (new files/existing files with <parameter>overwrite</parameter>)</entry>
</row>
<row>
<entry>Allows Appending</entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Simultaneous Reading and Writing</entry>
<entry>No</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>stat</function></entry>
<entry>No</entry>
<entry>
As of PHP 5.0.0: <function>filesize</function>,
<function>filetype</function>, <function>file_exists</function>,
<function>is_file</function>, and <function>is_dir</function> elements only.
As of PHP 5.1.0: <function>filemtime</function>.
</entry>
</row>
<row>
<entry>Supports <function>unlink</function></entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports <function>rename</function></entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports <function>mkdir</function></entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports <function>rmdir</function></entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table>
<title>Context options (as of PHP 5.0.0)</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Usage</entry>
<entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>overwrite</literal></entry>
<entry>
Allow overwriting of already existing files on remote server.
Applies to write mode (uploading) only.
</entry>
<entry>&false; (Disabled)</entry>
</row>
<row>
<entry><literal>resume_pos</literal></entry>
<entry>
File offset at which to begin transfer.
Applies to read mode (downloading) only.
</entry>
<entry>0 (Beginning of File)</entry>
</row>
<row>
<entry><literal>proxy</literal>(PHP 5.1.0 or greater)</entry>
<entry>
Proxy FTP request via http proxy server.
Applies to file read operations only.
Ex: <literal>tcp://squid.example.com:8000</literal>
</entry>
<entry/>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<title>Underlying socket stream context options</title>
<simpara>
Additional context options may be supported by the
<link linkend="transports.inet">underlying transport</link>
For <literal>ftp://</literal> streams, refer to context
options for the <literal>tcp://</literal> transport. For
<literal>ftps://</literal> streams, refer to context options
for the <literal>ssl://</literal> transport.
</simpara>
</note>
</section>
<section id="wrappers.php">
<title>PHP input/output streams</title>
<simpara>
PHP 3.0.13 and up, <filename>php://output</filename>
and <filename>php://input</filename> since PHP 4.3.0,
<filename>php://filter</filename> since PHP 5.0.0.
</simpara>
<itemizedlist>
<listitem><simpara><filename>php://stdin</filename></simpara></listitem>
<listitem><simpara><filename>php://stdout</filename></simpara></listitem>
<listitem><simpara><filename>php://stderr</filename></simpara></listitem>
<listitem><simpara><filename>php://output</filename></simpara></listitem>
<listitem><simpara><filename>php://input</filename></simpara></listitem>
<listitem><simpara><filename>php://filter</filename></simpara></listitem>
</itemizedlist>
<simpara>
<filename>php://stdin</filename>, <filename>php://stdout</filename>
and <filename>php://stderr</filename> allow access to
the corresponding input or output stream of the PHP process.
</simpara>
<simpara>
<filename>php://output</filename> allows you to write to the
output buffer mechanism in the same way as
<function>print</function> and <function>echo</function>.
</simpara>
<simpara>
<filename>php://input</filename> allows you to read raw POST data.
It is a less memory intensive alternative to
<varname>$HTTP_RAW_POST_DATA</varname> and does not need any
special &php.ini; directives.
<filename>php://input</filename> is not available with
<literal>enctype="multipart/form-data"</literal>.
</simpara>
<simpara>
<filename>php://stdin</filename> and
<filename>php://input</filename> are read-only, whereas
<filename>php://stdout</filename>,
<filename>php://stderr</filename> and
<filename>php://output</filename> are write-only.
</simpara>
<simpara>
<filename>php://filter</filename> is a kind of meta-wrapper designed
to permit the application of filters to a stream at the time of
opening. This is useful with all-in-one file functions such as
<function>readfile</function>, <function>file</function>, and
<function>file_get_contents</function> where there is otherwise
no opportunity to apply a filter to the stream prior the contents
being read.
</simpara>
<simpara>
The <filename>php://filter</filename> target takes the following
'parameters' as parts of its 'path'.
</simpara>
<itemizedlist>
<listitem>
<para>
<literal>/resource=&lt;stream to be filtered&gt;</literal>
(<emphasis>required</emphasis>) This parameter must be located at
the end of your <filename>php://filter</filename> specification and
should point to the stream which you want filtered.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
/* This is equivalent to simply:
readfile("http://www.example.com");
since no filters are actually specified */
readfile("php://filter/resource=http://www.example.com");
?>
]]>
</programlisting>
</informalexample>
</para>
</listitem>
<listitem>
<para>
<literal>/read=&lt;filter list to apply to read chain&gt;</literal>
(<emphasis>optional</emphasis>) This parameter takes one or more
filternames separated by the pipe character <literal>|</literal>.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
/* This will output the contents of
www.example.com entirely in uppercase */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");
/* This will do the same as above
but will also ROT13 encode it */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>
]]>
</programlisting>
</informalexample>
</para>
</listitem>
<listitem>
<para>
<literal>/write=&lt;filter list to apply to write chain&gt;</literal>
(<emphasis>optional</emphasis>) This parameter takes one or more
filternames separated by the pipe character <literal>|</literal>.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
/* This will filter the string "Hello World"
through the rot13 filter, then write to
example.txt in the current directory */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>
]]>
</programlisting>
</informalexample>
</para>
</listitem>
<listitem>
<simpara>
<literal>/&lt;filter list to apply to both chains&gt;</literal>
(<emphasis>optional</emphasis>) Any filter lists which are not
prefixed specifically by <literal>read=</literal> or
<literal>write=</literal> will be applied to both the read and
write chains (as appropriate).
</simpara>
</listitem>
</itemizedlist>
<para>
<table>
<title>
Wrapper Summary (For <literal>php://filter</literal>,
refer to summary of wrapper being filtered.)
</title>
<tgroup cols="2">
<thead>
<row>
<entry>Attribute</entry>
<entry>Supported</entry>
</row>
</thead>
<tbody>
<row>
<entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link>.</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Reading</entry>
<entry>
<literal>php://stdin</literal> and
<literal>php://input</literal> only.
</entry>
</row>
<row>
<entry>Allows Writing</entry>
<entry>
<literal>php://stdout</literal>,
<literal>php://stderr</literal>, and
<literal>php://output</literal> only.
</entry>
</row>
<row>
<entry>Allows Appending</entry>
<entry>
<literal>php://stdout</literal>,
<literal>php://stderr</literal>, and
<literal>php://output</literal> only. (Equivalent to writing)
</entry>
</row>
<row>
<entry>Allows Simultaneous Reading and Writing</entry>
<entry>No. These wrappers are unidirectional.</entry>
</row>
<row>
<entry>Supports <function>stat</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>unlink</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rename</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>mkdir</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rmdir</function></entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section id="wrappers.compression">
<title>Compression Streams</title>
<simpara><filename>zlib:</filename> PHP 4.0.4 - PHP 4.2.3 (systems with fopencookie only)</simpara>
<simpara><filename>compress.zlib://</filename> and <filename>compress.bzip2://</filename> PHP 4.3.0 and up</simpara>
<itemizedlist>
<listitem><simpara><filename>zlib:</filename></simpara></listitem>
<listitem><simpara><filename>compress.zlib://</filename></simpara></listitem>
<listitem><simpara><filename>compress.bzip2://</filename></simpara></listitem>
</itemizedlist>
<simpara>
<filename>zlib:</filename> works like <function>gzopen</function>, except that the
stream can be used with <function>fread</function> and the other
filesystem functions. This is deprecated as of PHP 4.3.0 due
to ambiguities with filenames containing ':' characters; use
<filename>compress.zlib://</filename> instead.
</simpara>
<simpara>
<filename>compress.zlib://</filename> and
<filename>compress.bzip2://</filename> are equivalent to
<function>gzopen</function> and <function>bzopen</function>
respectively, and operate even on systems that do not support
fopencookie.
</simpara>
<para>
<table>
<title>Wrapper Summary</title>
<tgroup cols="2">
<thead>
<row>
<entry>Attribute</entry>
<entry>Supported</entry>
</row>
</thead>
<tbody>
<row>
<entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link>.</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Reading</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Writing</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Appending</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Simultaneous Reading and Writing</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>stat</function></entry>
<entry>
No, use the normal <literal>file://</literal> wrapper
to stat compressed files.
</entry>
</row>
<row>
<entry>Supports <function>unlink</function></entry>
<entry>
No, use the normal <literal>file://</literal> wrapper
to unlink compressed files.
</entry>
</row>
<row>
<entry>Supports <function>rename</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>mkdir</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rmdir</function></entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section id="wrappers.ssh2">
<title>Secure Shell 2</title>
<simpara>
<filename>ssh2.shell://</filename>
<filename>ssh2.exec://</filename>
<filename>ssh2.tunnel://</filename>
<filename>ssh2.sftp://</filename>
<filename>ssh2.scp://</filename>
PHP 4.3.0 and up (PECL)
</simpara>
<itemizedlist>
<listitem><simpara><filename>ssh2.shell://user:pass@example.com:22/xterm</filename></simpara></listitem>
<listitem><simpara><filename>ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd</filename></simpara></listitem>
<listitem><simpara><filename>ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14</filename></simpara></listitem>
<listitem><simpara><filename>ssh2.sftp://user:pass@example.com:22/path/to/filename</filename></simpara></listitem>
</itemizedlist>
<note>
<title>This wrapper is not enabled by default</title>
<simpara>
In order to use the <filename>ssh2.*://</filename> wrappers you must install
the <ulink url="&url.pecl.package;ssh2">SSH2</ulink> extension
available from <ulink url="&url.pecl;">PECL</ulink>.
</simpara>
</note>
<simpara>
In addition to accepting traditional URI login details, the ssh2 wrappers
will also reuse open connections by passing the connection resource in the
host portion of the URL.
</simpara>
<example>
<title>Opening a stream from an active connection</title>
<programlisting role="php">
<![CDATA[
<?php
$session = ssh2_connect('example.com', 22);
ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
'/home/username/.ssh/id_rsa', 'secret');
$stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
?>
]]>
</programlisting>
</example>
<para>
<table>
<title>Wrapper Summary</title>
<tgroup cols="6">
<thead>
<row>
<entry>Attribute</entry>
<entry>ssh2.shell</entry>
<entry>ssh2.exec</entry>
<entry>ssh2.tunnel</entry>
<entry>ssh2.sftp</entry>
<entry>ssh2.scp</entry>
</row>
</thead>
<tbody>
<row>
<entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link>.</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Reading</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Writing</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Appending</entry>
<entry>No</entry>
<entry>No</entry>
<entry>No</entry>
<entry>Yes (When supported by server)</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Simultaneous Reading and Writing</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>stat</function></entry>
<entry>No</entry>
<entry>No</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>unlink</function></entry>
<entry>No</entry>
<entry>No</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rename</function></entry>
<entry>No</entry>
<entry>No</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>mkdir</function></entry>
<entry>No</entry>
<entry>No</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rmdir</function></entry>
<entry>No</entry>
<entry>No</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table>
<title>Context options</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Usage</entry>
<entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>session</literal></entry>
<entry>Preconnected ssh2 resource to be reused</entry>
<entry/>
</row>
<row>
<entry><literal>sftp</literal></entry>
<entry>Preallocated sftp resource to be reused</entry>
<entry/>
</row>
<row>
<entry><literal>methods</literal></entry>
<entry>Key exchange, hostkey, cipher, compression, and MAC methods to use</entry>
<entry/>
</row>
<row>
<entry><literal>callbacks</literal></entry>
<entry></entry>
<entry></entry>
</row>
<row>
<entry><literal>username</literal></entry>
<entry>Username to connect as</entry>
<entry></entry>
</row>
<row>
<entry><literal>password</literal></entry>
<entry>Password to use with password authentication</entry>
<entry></entry>
</row>
<row>
<entry><literal>pubkey_file</literal></entry>
<entry>Name of public key file to use for authentication</entry>
<entry></entry>
</row>
<row>
<entry><literal>privkey_file</literal></entry>
<entry>Name of private key file to use for authentication</entry>
<entry></entry>
</row>
<row>
<entry><literal>env</literal></entry>
<entry>Associate array of environment variables to set</entry>
<entry></entry>
</row>
<row>
<entry><literal>term</literal></entry>
<entry>Terminal emulation type to request when allocating a pty</entry>
<entry></entry>
</row>
<row>
<entry><literal>term_width</literal></entry>
<entry>Width of terminal requested when allocating a pty</entry>
<entry></entry>
</row>
<row>
<entry><literal>term_height</literal></entry>
<entry>Height of terminal requested when allocating a pty</entry>
<entry></entry>
</row>
<row>
<entry><literal>term_units</literal></entry>
<entry>Units to use with term_width and term_height</entry>
<entry><constant>SSH2_TERM_UNIT_CHARS</constant></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section id="wrappers.audio">
<title>Audio Streams</title>
<simpara><filename>ogg://</filename> PHP 4.3.0 and up (PECL) </simpara>
<itemizedlist>
<listitem><simpara><filename>ogg://soundfile.ogg</filename></simpara></listitem>
<listitem><simpara><filename>ogg:///path/to/soundfile.ogg</filename></simpara></listitem>
<listitem><simpara><filename>ogg://http://www.example.com/path/to/soundstream.ogg</filename></simpara></listitem>
</itemizedlist>
<note>
<title>This wrapper is not enabled by default</title>
<simpara>
In order to use the <filename>ogg://</filename> wrapper you must install
the <ulink url="&url.pecl.package;oggvorbis">OGG/Vorbis</ulink> extension
available from <ulink url="&url.pecl;">PECL</ulink>.
</simpara>
</note>
<simpara>
Files opened for reading via the <filename>ogg://</filename> wrapper
are treated as compressed audio encoded using the OGG/Vorbis codec.
Similarly, files opened for writing or appending via the
<filename>ogg://</filename> wrapper are writen as compressed audio data.
<function>stream_get_meta_data</function>, when used on an OGG/Vorbis
file opened for reading will return various details about the stream
including the <parameter>vendor</parameter> tag, any included
<parameter>comments</parameter>, the number of
<parameter>channels</parameter>, the sampling <parameter>rate</parameter>,
and the encoding rate range described by:
<parameter>bitrate_lower</parameter>, <parameter>bitrate_upper</parameter>,
<parameter>bitrate_nominal</parameter>, and <parameter>bitrate_window</parameter>.
</simpara>
<para>
<table>
<title>Wrapper Summary</title>
<tgroup cols="2">
<thead>
<row>
<entry>Attribute</entry>
<entry>Supported</entry>
</row>
</thead>
<tbody>
<row>
<entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link>.</entry>
<entry>No</entry>
</row>
<row>
<entry>Allows Reading</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Writing</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Appending</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Allows Simultaneous Reading and Writing</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>stat</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>unlink</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rename</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>mkdir</function></entry>
<entry>No</entry>
</row>
<row>
<entry>Supports <function>rmdir</function></entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table>
<title>Context options</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Usage</entry>
<entry>Default</entry>
<entry>Mode</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>pcm_mode</literal></entry>
<entry>
PCM encoding to apply while reading, one of:
<constant>OGGVORBIS_PCM_U8</constant>, <constant>OGGVORBIS_PCM_S8</constant>,
<constant>OGGVORBIS_PCM_U16_BE</constant>, <constant>OGGVORBIS_PCM_S16_BE</constant>,
<constant>OGGVORBIS_PCM_U16_LE</constant>, and <constant>OGGVORBIS_PCM_S16_LE</constant>.
(8 vs 16 bit, signed or unsigned, big or little endian)
</entry>
<entry>OGGVORBIS_PCM_S16_LE</entry>
<entry>Read</entry>
</row>
<row>
<entry><literal>rate</literal></entry>
<entry>
Sampling rate of input data, expressed in Hz
</entry>
<entry>44100</entry>
<entry>Write/Append</entry>
</row>
<row>
<entry><literal>bitrate</literal></entry>
<entry>
When given as an integer, the fixed bitrate at which to encode. (16000 to 131072)
When given as a float, the variable bitrate quality to use. (-1.0 to 1.0)
</entry>
<entry>128000</entry>
<entry>Write/Append</entry>
</row>
<row>
<entry><literal>channels</literal></entry>
<entry>
The number of audio channels to encode, typically 1 (Mono), or 2 (Stero).
May range as high as 16.
</entry>
<entry>2</entry>
<entry>Write/Append</entry>
</row>
<row>
<entry><literal>comments</literal></entry>
<entry>
An array of string values to encode into the track header.
</entry>
<entry/>
<entry>Write/Append</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
</appendix>
<!-- 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:"../../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
-->
Reference in a new issue View git blame Copy permalink