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