vfs.sgml

eGroupWare is a multi-user, web-based groupware suite developed on a custom set of PHP-based APIs. C

<!doctype linuxdoc system>

<article>
<!-- LyX 1.1 created this file. For more info see http://www.lyx.org/ -->
<title>
phpgwapi - VFS Class
</title>
<author>
Jason Wies
</author>
<date>
June 2001, February 2002
</date>
<abstract>
The VFS, or Virtual File System, handles all file system activity
 for eGoupWare.
</abstract>
<sect>
Introduction and Purpose<label id="sec:introduction" >
<p>
The latest version of the VFS for eGoupWare combines actual
 file system manipulation with fully integrated database support.
 It features nearly transparent handling of files and directories,
 as well as files inside and outside the virtual root. This document
 is intended to provide API and application developers with a guide
 to incorporating the VFS into their work.
</p>
<sect>
Basics<label id="sec:basics" >
<sect1>
Prerequisites<label id="sec:prerequisites" >
<p>
You must explicitly enable the VFS class. To do this, set 'enable_vfs_class'
 to True in &dollar;GLOBALS&lsqb;'phpgw_info'&rsqb;&lsqb;'flags'&rsqb;.
 An example:
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw_info'&rsqb;&lsqb;'flags'&rsqb; = array(
     'currentapp' =&gt; 'phpwebhosting',
     'noheader' =&gt; False,
     'noappheader' =&gt; False,
     'enable_vfs_class' =&gt; True,
     'enable_browser_class' =&gt; True
);
</verb>
</p><sect1>
Concepts<label id="sec:concepts" >
<p>
The VFS in located in phpgwapi/inc/class.vfs_sql.inc.php. You
 can look over it, but I don't suggest trying to understand how it
 works. It isn't necessary to know its internals to use it, but you
 may find the inline comments helpful. The basic things to keep in
 mind:
</p>
<p>
<itemize>
 <item>
Files and directories are synonymous in almost all cases
</itemize>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;mv (array(
     'from' =&gt; 'file1',
     'to' =&gt; 'dir/file2'
));

&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;mv (array(
     'from' =&gt; 'dir1',
     'to' =&gt; 'dir/dir1'
));

&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;rm (array(
     'string' =&gt; 'file'
));

&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;rm (array(
     'string' =&gt; 'dir'
));
</verb>
</p><p>
All work as you would except them to. The major exception is:
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;touch (array(
     'string' =&gt; 'file'
));
</verb>
</p><p>
vs.
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;mkdir (array(
     'string' =&gt; 'dir'
));

</verb>
<p>
<itemize>
 <item>
Users and groups are synonymous
</itemize>
</p><p>
As far as the actual paths are concerned, users and groups are
 the same. /home/username works the same as /home/groupname.
</p>
<p>
<itemize>
 <item>
You should never have to know the real paths of files
</itemize>
</p><p>
One of the VFS's responsibilities is to translate paths for you.
 While you certainly <em>can</em> operate using full paths, it is much simpler
 to use the virtual paths. For example, instead of using:
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;cp (array(
     'from' =&gt; '/var/www/egroupware/files/home/user/file1',
     'to' =&gt; '/var/www/egroupware/files/home/user/file2',
     'relatives' =&gt; array(
          RELATIVE_NONE|VFS_REAL,
          RELATIVE_NONE|VFS_REAL
     )
));
</verb>
</p><p>
you might use
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;cp (array(
     'from' =&gt; '/home/user/file1',
     'to' =&gt; '/home/user/file2',
     'relatives' =&gt; array(
          RELATIVE_NONE,
          RELATIVE_NONE
     )
));
</verb>
</p><p>
(We'll get to the RELATIVE's in a minute.)
</p>
<p>
Site administrators should be able to move their files dir around
 on their system and know that everything will continue to work smoothly.
</p>
<p>
<itemize>
 <item>
Relativity is <em>vital</em>
</itemize>
</p><p>
Relativity is a new feature in the VFS, and its importance cannot
 be stressed enough. It will make your life much easier, especially
 for file system intensive applications, but it will take some getting
 used to. If something doesn't work right the first time, chances
 are great it has to do with incorrect relativity settings. We will
 deal with relativity in depth in the Relativity section.
</p>
<sect>
Basic Functions<label id="sec:basic_functions" >
<p>
These are two functions you'll need to know before we get into
 relativity.
</p>
<sect1>
path_parts ()<label id="sec:path_parts" >
<p>
The job of path_parts () is to translate any given file location
 into its many component parts for any relativity. The values passed
 to path_parts () are:
</p>
<p>
<verb>
string
relatives
object
</verb>
</p><p>
'string' is the path you want to translate, 'relatives' is the
 standard relativity array, and 'object' specifies how you would like
 the return value: if 'object' is True, an object will be returned;
 if 'object' is False, an array will be returned. I think you'll find
 the object easier to deal with, and we'll be using it throughout
 this document. The most important returned values (but not all) for
 path_parts () are:
</p>
<p>
<verb>
fake_full_path
fake_leading_dirs
fake_extra_path
fake_name
real_full_path
real_leading_dirs
real_extra_path
real_name
</verb>
</p><p>
Just like you would think, fake_full_path contains the full virtual
 path of 'string', and real_full_path contains the full real path
 of 'string'. The fake_name and real_name variables should always
 be the same, and contain the final file or directory name. The leading_dirs
 contain everything except the name, and the extra_path is everything
 from the / before "home" to the end of the leading_dirs. To better
 illustrate, here is an example:
</p>
<p>
<verb>
&dollar;p = &dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;path_parts (array(
     'string' =&gt; '/home/jason/dir/file',
     'relatives' =&gt; array(
         RELATIVE_NONE
     )
));
</verb>
<p>
<itemize>
 <item>
&dollar;p-&gt;fake_full_path - /home/jason/dir/file
 <item>
&dollar;p-&gt;fake_leading_dirs - /home/jason/dir
 <item>
&dollar;p-&gt;fake_extra_path - home/jason/dir
 <item>
&dollar;p-&gt;fake_name - file
 <item>
&dollar;p-&gt;real_full_path - /var/www/egroupware/files/home/jason/dir/file
 <item>
&dollar;p-&gt;real_leading_dirs - /var/www/egroupware/files/home/jason/dir
 
 <item>
&dollar;p-&gt;real_extra_path - home/jason/dir
 <item>
&dollar;p-&gt;real_name - file
</itemize>
</p><p>
As you can see, path_parts () is a very useful function and will
 save you from doing those darn substr ()'s yourself. For those of
 you used to the prior VFS, note that <em>getabsolutepath () is depreciated</em>.
 getabsolutepath () still exists (albeit in a much different form),
 and is responsible for some of the path translation, but it is an
 <em>internal</em> function only. Applications should only use path_parts ().
 We have shown you how to use path_parts () so you can experiment
 with it using different paths and relativities as we explore relativity.
</p>
<sect1>
cd ()<label id="sec:cd" >
<p>
Part of the overall goal for the VFS in eGoupWare is to give
 the user a seamless experience during their session. For example,
 if they upload a file using a file manager to the directory /home/my_group/project1,
 and then go to download an email attachment, the default directory
 will be /home/my_group/project1. This is accomplished using the cd
 () function. Examples: 
</p>
<p>
<verb>
/* cd to their home directory */
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;cd (array(
     'string' =&gt; '/'
));

/* cd to /home/jason/dir */
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;cd (array(
     'string' =&gt; '/home/jason/dir',
     'relative' =&gt; False,
     'relatives' =&gt; array(
          RELATIVE_NONE
     )
));

/* When following the above, cd's to /home/jason/dir/dir2 */
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;cd (array(
     'string' =&gt; 'dir2',
     'relative' =&gt; True
));
</verb>
</p><p>
If 'relative' is True, the 'string' is simply appended to the
 current path. If you want to know what the current path is, use &dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;pwd
 ().
</p>
<p>
Now you're ready for relativity.
</p>
<sect>
Relativity<label id="sec:relativity" >
<p>
Ok, just one last thing before we get into relativity. You will
 notice throughout the examples the use of &dollar;fakebase. &dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;fakebase
 is by default '/home'. The old VFS was hard-coded to use '/home',
 but the naming choice for this is now up to administrators. See the
 <ref id="sec:fakebase" name="Fakebase directory (changing /home)" > section for more information. Throughout the rest of this document,
 you will see &dollar;fakebase used in calls to the VFS, and /home
 used in actual paths. <em>You should always use &dollar;fakebase when
 making applications. </em>I suggest doing &dollar;fakebase = &dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;fakebase;
 right off the bat to keep things neater.
</p>
<sect1>
What is it and how does it work?
<p>
One of the design challenges for a Virtual File System is to
 try to figure out whether the calling application is referring to
 a file inside or outside the virtual root, and if inside, exactly
 where. To solve this problem, the eGoupWare VFS uses RELATIVE
 defines that are used in bitmasks passed to each function. The result
 is that any set of different relativities can be used in combination
 with each other. Let's look at a few examples. Say you want to move
 'logo.png' from the user's home directory to the current directory.
 
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;mv (array(
    'from' =&gt; 'logo.png',
    'to' =&gt; 'logo.png',
    'relatives' =&gt; array(
          RELATIVE_USER,
          RELATIVE_ALL
     )