1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 288721 $ -->
<refentry xml:id="phar.mount" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Phar::mount</refname>
<refpurpose>Mount an external path or file to a virtual location within the phar archive</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>Phar::mount</methodname>
<methodparam><type>string</type><parameter>pharpath</parameter></methodparam>
<methodparam><type>string</type><parameter>externalpath</parameter></methodparam>
</methodsynopsis>
<para>
Much like the unix file system concept of mounting external devices to paths within the
directory tree, <function>Phar::mount</function> allows referring to external files
and directories as if they were inside of an archive. This allows powerful
abstraction such as referring to external configuration files as if they were
inside the archive.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>pharpath</parameter></term>
<listitem>
<para>
The internal path within the phar archive to use as the mounted path location.
If executed within a phar archive, this may be a relative path, otherwise this must
be a full <literal>phar</literal> URL.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>externalpath</parameter></term>
<listitem>
<para>
A path or URL to an external file or directory to mount within the phar archive
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
No return. <classname>PharException</classname> is thrown on failure.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>PharException</classname> if any problems occur mounting the path.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>Phar::mount</function> example</title>
<para>
The following example shows accessing an external configuration file as if it were
a path within a phar archive.
</para>
<para>
First, the code inside of a phar archive:
</para>
<programlisting role="php">
<![CDATA[
<?php
$configuration = simplexml_load_string(file_get_contents(
Phar::running(false) . '/config.xml'));
?>
]]>
</programlisting>
<para>
Next the external code used to mount the configuration file:
</para>
<programlisting role="php">
<![CDATA[
<?php
// first set up the association between the abstract config.xml
// and the actual one on disk
Phar::mount('phar:///path/to/archive.phar/config.xml', '/home/example/config.xml');
// now run the application
include '/path/to/archive.phar';
?>
]]>
</programlisting>
<para>
Another method is to put the mounting code inside the stub of the phar archive.
Here is an example of setting up a default
configuration file if no user configuration is specified:
</para>
<programlisting role="php">
<![CDATA[
<?php
// first set up the association between the abstract config.xml
// and the actual one on disk
if (defined('EXTERNAL_CONFIG')) {
Phar::mount('config.xml', EXTERNAL_CONFIG);
if (file_exists(__DIR__ . '/extra_config.xml')) {
Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
}
} else {
Phar::mount('config.xml', 'phar://' . __FILE__ . '/default_config.xml');
Phar::mount('extra.xml', 'phar://' . __FILE__ . '/default_extra.xml');
}
// now run the application
include 'phar://' . __FILE__ . '/index.php';
__HALT_COMPILER();
?>
]]>
</programlisting>
<para>
...and the code externally to load this phar archive:
</para>
<programlisting role="php">
<![CDATA[
<?php
define('EXTERNAL_CONFIG', '/home/example/config.xml');
// now run the application
include '/path/to/archive.phar';
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- 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:"~/.phpdoc/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
-->
|
