[Sommaire] [Imprimer]

   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']-&gt;vfs-&gt;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']-&gt;vfs-&gt;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']-&gt;vfs-&gt;mv (array(
  41      'from' =&gt; 'logo.png',
  42      'to' =&gt; 'logo.png',
  43      'relatives' =&gt; 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']-&gt;vfs-&gt;mv (array(
  74       'from' =&gt; $GLOBALS['phpgw_info']['server']['temp_dir'] . '/' . $randomdir . '/' . $randomfile,
  75       'to' =&gt; 'attachments/actual_name.ext',
  76       'relatives' =&gt; 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']-&gt;vfs-&gt;write (array(
 110       'string' =&gt; 'file.name~',
 111       'relatives' =&gt; array(
 112            RELATIVE_USER_APP
 113       ),
 114       'content' =&gt; $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']-&gt;vfs-&gt;set_relative (array(
 166       'mask' =&gt; RELATIVE_NONE|VFS_REAL
 167  ));
 168  
 169  $GLOBALS['phpgw']-&gt;vfs-&gt;read (array(
 170       'string' =&gt; '/etc/passwd'
 171  ));
 172  
 173  $GLOBALS['phpgw']-&gt;vfs-&gt;cp (array(
 174       'from' =&gt; '/usr/include/stdio.h',
 175       'to' =&gt; '/tmp/stdio.h'
 176  ));
 177  
 178  $GLOBALS['phpgw']-&gt;vfs-&gt;cp (array(
 179       'from' =&gt; '/usr/share/pixmaps/yes.xpm',
 180       'to' =&gt; 'icons/yes.xpm',
 181       'relatives' =&gt; 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>