1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
---|
2 | <HTML> |
---|
3 | <HEAD> |
---|
4 | <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.17"> |
---|
5 | <TITLE>phpgwapi - VFS Class: Relativity</TITLE> |
---|
6 | <LINK HREF="vfs-5.html" REL=next> |
---|
7 | <LINK HREF="vfs-3.html" REL=previous> |
---|
8 | <LINK HREF="vfs.html#toc4" REL=contents> |
---|
9 | </HEAD> |
---|
10 | <BODY> |
---|
11 | <A HREF="vfs-5.html">Next</A> |
---|
12 | <A HREF="vfs-3.html">Previous</A> |
---|
13 | <A HREF="vfs.html#toc4">Contents</A> |
---|
14 | <HR> |
---|
15 | <H2><A NAME="sec:relativity"></A> <A NAME="s4">4.</A> <A HREF="vfs.html#toc4">Relativity</A></H2> |
---|
16 | |
---|
17 | <P>Ok, just one last thing before we get into relativity. You will |
---|
18 | notice throughout the examples the use of $fakebase. $GLOBALS['phpgw']->vfs->fakebase |
---|
19 | is by default '/home'. The old VFS was hard-coded to use '/home', |
---|
20 | but the naming choice for this is now up to administrators. See the |
---|
21 | <A HREF="vfs-6.html#sec:fakebase">Fakebase directory (changing /home)</A> section for more information. Throughout the rest of this document, |
---|
22 | you will see $fakebase used in calls to the VFS, and /home |
---|
23 | used in actual paths. <EM>You should always use $fakebase when |
---|
24 | making applications. </EM>I suggest doing $fakebase = $GLOBALS['phpgw']->vfs->fakebase; |
---|
25 | right off the bat to keep things neater.</P> |
---|
26 | <H2><A NAME="ss4.1">4.1</A> <A HREF="vfs.html#toc4.1">What is it and how does it work?</A> |
---|
27 | </H2> |
---|
28 | |
---|
29 | <P>One of the design challenges for a Virtual File System is to |
---|
30 | try to figure out whether the calling application is referring to |
---|
31 | a file inside or outside the virtual root, and if inside, exactly |
---|
32 | where. To solve this problem, the eGoupWare VFS uses RELATIVE |
---|
33 | defines that are used in bitmasks passed to each function. The result |
---|
34 | is that any set of different relativities can be used in combination |
---|
35 | with each other. Let's look at a few examples. Say you want to move |
---|
36 | 'logo.png' from the user's home directory to the current directory.</P> |
---|
37 | |
---|
38 | <P> |
---|
39 | <PRE> |
---|
40 | $GLOBALS['phpgw']->vfs->mv (array( |
---|
41 | 'from' => 'logo.png', |
---|
42 | 'to' => 'logo.png', |
---|
43 | 'relatives' => array( |
---|
44 | RELATIVE_USER, |
---|
45 | RELATIVE_ALL |
---|
46 | ) |
---|
47 | )); |
---|
48 | </PRE> |
---|
49 | </P> |
---|
50 | <P>RELATIVE_USER means relative to the user's home directory. RELATIVE_ALL |
---|
51 | means relative to the current directory, as set by cd () and as reported |
---|
52 | by pwd (). So if the current directory was "$fakebase/my_group/project1", |
---|
53 | the call to mv () would be processed as:</P> |
---|
54 | <P> |
---|
55 | <PRE> |
---|
56 | MOVE "$fakebase/jason/logo.png" TO "$fakebase/my_group/project1/logo.png" |
---|
57 | </PRE> |
---|
58 | </P> |
---|
59 | <P>and the actual file system call would be:</P> |
---|
60 | <P> |
---|
61 | <PRE> |
---|
62 | rename ('/var/www/egroupware/files/home/jason/logo.php', '/var/www/egroupware/files/home/my_group/project1/logo.png'); |
---|
63 | </PRE> |
---|
64 | </P> |
---|
65 | <P>Those used to the old VFS will note that you do not have to translate |
---|
66 | the path beforehand. Let's look at another example. Suppose you were |
---|
67 | moving an email attachment stored in eGoupWare's temporary directory |
---|
68 | to the 'attachments' directory within the user's home directory (we're |
---|
69 | assuming the attachments directory exists). Note that the temporary |
---|
70 | directory is <EM>outside</EM> the virtual root.</P> |
---|
71 | <P> |
---|
72 | <PRE> |
---|
73 | $GLOBALS['phpgw']->vfs->mv (array( |
---|
74 | 'from' => $GLOBALS['phpgw_info']['server']['temp_dir'] . '/' . $randomdir . '/' . $randomfile, |
---|
75 | 'to' => 'attachments/actual_name.ext', |
---|
76 | 'relatives' => array( |
---|
77 | RELATIVE_NONE|VFS_REAL, |
---|
78 | RELATIVE_USER |
---|
79 | ) |
---|
80 | )); |
---|
81 | </PRE> |
---|
82 | </P> |
---|
83 | <P>$randomdir and $randomfile are what the directory |
---|
84 | and file might be called before they are given a proper name by the |
---|
85 | user, which is actual_name.ext in this example. RELATIVE_NONE is |
---|
86 | the define for using full path names. However, RELATIVE_NONE is still |
---|
87 | relative to the virtual root, so we pass along VFS_REAL as well, |
---|
88 | to say that the file is <EM>outside</EM> the virtual root, somewhere else |
---|
89 | in the file system. Once again, RELATIVE_USER means relative to the |
---|
90 | user's home directory. So the actual file system call might look |
---|
91 | like this (keep in mind that $randomdir and $randomfile |
---|
92 | are just random strings):</P> |
---|
93 | <P> |
---|
94 | <PRE> |
---|
95 | rename ('/var/www/egroupware/tmp/0ak5adftgh7/jX42sC9M', '/var/www/egroupware/files/home/jason/attachments/actual_name.ext'); |
---|
96 | </PRE> |
---|
97 | </P> |
---|
98 | <P>Of course you don't have to know that, nor should you be concerned |
---|
99 | with it; you can take it for granted that the VFS will translate |
---|
100 | the paths correctly. Let's take a look at one more example, this |
---|
101 | time using the RELATIVE_USER_APP define. RELATIVE_USER_APP is used |
---|
102 | to store quasi-hidden application files, similar to the Unix convention |
---|
103 | of ~/.appname. It simply appends .appname to the user's home |
---|
104 | directory. For example, if you were making an HTML editor application |
---|
105 | named 'htmledit', and wanted to keep a backup file in case something |
---|
106 | goes wrong, you could use RELATIVE_USER_APP to store it:</P> |
---|
107 | <P> |
---|
108 | <PRE> |
---|
109 | $GLOBALS['phpgw']->vfs->write (array( |
---|
110 | 'string' => 'file.name~', |
---|
111 | 'relatives' => array( |
---|
112 | RELATIVE_USER_APP |
---|
113 | ), |
---|
114 | 'content' => $contents |
---|
115 | )); |
---|
116 | </PRE> |
---|
117 | </P> |
---|
118 | <P>This assumes that ~/.htmledit exists of course. The backup |
---|
119 | file "file.name~" would then be written in $fakebase/jason/.htmledit/file.name~. |
---|
120 | Note that storing files like this might not be as good of a solution |
---|
121 | as storing them in the temporary directory or in the database. But |
---|
122 | it is there in case you need it.</P> |
---|
123 | <H2><A NAME="sec:relatives_complete_list"></A> <A NAME="ss4.2">4.2</A> <A HREF="vfs.html#toc4.2">Complete List</A> |
---|
124 | </H2> |
---|
125 | |
---|
126 | <P>Here is the complete list of RELATIVE defines, and what they |
---|
127 | do:</P> |
---|
128 | <P> |
---|
129 | <DL> |
---|
130 | <DT><B>RELATIVE_ROOT</B><DD><P>Don't translate the path at all. Just prepends |
---|
131 | a /. You'll probably want to use RELATIVE_NONE though, which handles |
---|
132 | both virtual and real files.</P> |
---|
133 | <DT><B>RELATIVE_USER</B><DD><P>User's home directory</P> |
---|
134 | <DT><B>RELATIVE_CURR_USER</B><DD><P>Current user's home directory. If the |
---|
135 | current directory is $fakebase/my_group/project1, this will |
---|
136 | return is $fakebase/my_group</P> |
---|
137 | <DT><B>RELATIVE_USER_APP</B><DD><P>Append .appname to the user's home directory, |
---|
138 | where appname is the current application's appname</P> |
---|
139 | <DT><B>RELATIVE_PATH</B><DD><P>DO NOT USE. Relative to the current directory, |
---|
140 | used in RELATIVE_ALL</P> |
---|
141 | <DT><B>RELATIVE_NONE</B><DD><P>Not relative to anything. Use this with VFS_REAL |
---|
142 | for files outside the virtual root. Note that using RELATIVE_NONE |
---|
143 | by itself still means relative to the virtual root</P> |
---|
144 | <DT><B>RELATIVE_CURRENT</B><DD><P>An alias for the currently set RELATIVE |
---|
145 | define, or RELATIVE_ALL if none is set (see the Defaults section)</P> |
---|
146 | <DT><B>VFS_REAL</B><DD><P>File is outside of the virtual root. Usually used |
---|
147 | with RELATIVE_NONE</P> |
---|
148 | <DT><B>RELATIVE_ALL</B><DD><P>Relative to the current directory. Use RELATIVE_ALL<EM></EM>instead of RELATIVE_PATH</P> |
---|
149 | </DL> |
---|
150 | </P> |
---|
151 | <H2><A NAME="sec:relatives_defaults"></A> <A NAME="ss4.3">4.3</A> <A HREF="vfs.html#toc4.3">Defaults</A> |
---|
152 | </H2> |
---|
153 | |
---|
154 | <P>You might be thinking to yourself that passing along RELATIVE |
---|
155 | defines with every VFS call is overkill, especially if your application |
---|
156 | always uses the same relativity. The default RELATIVE define for |
---|
157 | all VFS calls is RELATIVE_CURRENT. RELATIVE_CURRENT itself defaults |
---|
158 | to RELATIVE_ALL (relative to the current path), <EM>unless</EM> your application |
---|
159 | sets a specific relativity. If your application requires most of |
---|
160 | the work to be done outside of the virtual root, you may wish to |
---|
161 | set RELATIVE_CURRENT to RELATIVE_NONE|VFS_REAL. set_relative () is |
---|
162 | the function to do this. For example:</P> |
---|
163 | <P> |
---|
164 | <PRE> |
---|
165 | $GLOBALS['phpgw']->vfs->set_relative (array( |
---|
166 | 'mask' => RELATIVE_NONE|VFS_REAL |
---|
167 | )); |
---|
168 | |
---|
169 | $GLOBALS['phpgw']->vfs->read (array( |
---|
170 | 'string' => '/etc/passwd' |
---|
171 | )); |
---|
172 | |
---|
173 | $GLOBALS['phpgw']->vfs->cp (array( |
---|
174 | 'from' => '/usr/include/stdio.h', |
---|
175 | 'to' => '/tmp/stdio.h' |
---|
176 | )); |
---|
177 | |
---|
178 | $GLOBALS['phpgw']->vfs->cp (array( |
---|
179 | 'from' => '/usr/share/pixmaps/yes.xpm', |
---|
180 | 'to' => 'icons/yes.xpm', |
---|
181 | 'relatives' => array( |
---|
182 | RELATIVE_CURRENT, |
---|
183 | RELATIVE_USER |
---|
184 | ) |
---|
185 | )); |
---|
186 | </PRE> |
---|
187 | </P> |
---|
188 | <P>You should notice that no relativity array is needed in the other |
---|
189 | calls that refer to files outside the virtual root, but one is needed |
---|
190 | for calls that include files inside the virtual root. Any RELATIVE |
---|
191 | define can be set as the default and works in the same fashion. To |
---|
192 | retrieve the currently set define, use get_relative (). Note that |
---|
193 | the relativity is reset after each page request; that is, it's good |
---|
194 | only for the life of the current page loading, and is not stored |
---|
195 | in session management.</P> |
---|
196 | <HR> |
---|
197 | <A HREF="vfs-5.html">Next</A> |
---|
198 | <A HREF="vfs-3.html">Previous</A> |
---|
199 | <A HREF="vfs.html#toc4">Contents</A> |
---|
200 | </BODY> |
---|
201 | </HTML> |
---|