vfs.sgml

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

));
</verb>
</p><p>
RELATIVE_USER means relative to the user's home directory. RELATIVE_ALL
 means relative to the current directory, as set by cd () and as reported
 by pwd (). So if the current directory was "&dollar;fakebase/my_group/project1",
 the call to mv () would be processed as:
</p>
<p>
<verb>
MOVE "&dollar;fakebase/jason/logo.png" TO "&dollar;fakebase/my_group/project1/logo.png"
</verb>
</p><p>
and the actual file system call would be:
</p>
<p>
<verb>
rename ('/var/www/egroupware/files/home/jason/logo.php', '/var/www/egroupware/files/home/my_group/project1/logo.png');
</verb>
</p><p>
Those used to the old VFS will note that you do not have to translate
 the path beforehand. Let's look at another example. Suppose you were
 moving an email attachment stored in eGoupWare's temporary directory
 to the 'attachments' directory within the user's home directory (we're
 assuming the attachments directory exists). Note that the temporary
 directory is <em>outside</em> the virtual root.
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;mv (array(
     'from' =&gt; &dollar;GLOBALS&lsqb;'phpgw_info'&rsqb;&lsqb;'server'&rsqb;&lsqb;'temp_dir'&rsqb; . '/' . &dollar;randomdir . '/' . &dollar;randomfile,
     'to' =&gt; 'attachments/actual_name.ext',
     'relatives' =&gt; array(
          RELATIVE_NONE|VFS_REAL,
          RELATIVE_USER
     )
));
</verb>
</p><p>
&dollar;randomdir and &dollar;randomfile are what the directory
 and file might be called before they are given a proper name by the
 user, which is actual_name.ext in this example. RELATIVE_NONE is
 the define for using full path names. However, RELATIVE_NONE is still
 relative to the virtual root, so we pass along VFS_REAL as well,
 to say that the file is <em>outside</em> the virtual root, somewhere else
 in the file system. Once again, RELATIVE_USER means relative to the
 user's home directory. So the actual file system call might look
 like this (keep in mind that &dollar;randomdir and &dollar;randomfile
 are just random strings):
</p>
<p>
<verb>
rename ('/var/www/egroupware/tmp/0ak5adftgh7/jX42sC9M', '/var/www/egroupware/files/home/jason/attachments/actual_name.ext');
</verb>
</p><p>
Of course you don't have to know that, nor should you be concerned
 with it; you can take it for granted that the VFS will translate
 the paths correctly. Let's take a look at one more example, this
 time using the RELATIVE_USER_APP define. RELATIVE_USER_APP is used
 to store quasi-hidden application files, similar to the Unix convention
 of &tilde;/.appname. It simply appends .appname to the user's home
 directory. For example, if you were making an HTML editor application
 named 'htmledit', and wanted to keep a backup file in case something
 goes wrong, you could use RELATIVE_USER_APP to store it:
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;write (array(
     'string' =&gt; 'file.name&tilde;',
     'relatives' =&gt; array(
          RELATIVE_USER_APP
     ),
     'content' =&gt; &dollar;contents
));
</verb>
</p><p>
This assumes that &tilde;/.htmledit exists of course. The backup
 file "file.name&tilde;" would then be written in &dollar;fakebase/jason/.htmledit/file.name&tilde;.
 Note that storing files like this might not be as good of a solution
 as storing them in the temporary directory or in the database. But
 it is there in case you need it.
</p>
<sect1>
Complete List<label id="sec:relatives_complete_list" >
<p>
Here is the complete list of RELATIVE defines, and what they
 do:
</p>
<p>
<descrip>
 <tag>
RELATIVE_ROOT</tag>Don't translate the path at all. Just prepends
 a /. You'll probably want to use RELATIVE_NONE though, which handles
 both virtual and real files.
 <tag>
RELATIVE_USER</tag>User's home directory
 <tag>
RELATIVE_CURR_USER</tag>Current user's home directory. If the
 current directory is &dollar;fakebase/my_group/project1, this will
 return is &dollar;fakebase/my_group
 <tag>
RELATIVE_USER_APP</tag>Append .appname to the user's home directory,
 where appname is the current application's appname
 <tag>
RELATIVE_PATH</tag>DO NOT USE. Relative to the current directory,
 used in RELATIVE_ALL
 <tag>
RELATIVE_NONE</tag>Not relative to anything. Use this with VFS_REAL
 for files outside the virtual root. Note that using RELATIVE_NONE
 by itself still means relative to the virtual root
 <tag>
RELATIVE_CURRENT</tag>An alias for the currently set RELATIVE
 define, or RELATIVE_ALL if none is set (see the Defaults section)
 <tag>
VFS_REAL</tag>File is outside of the virtual root. Usually used
 with RELATIVE_NONE
 <tag>
RELATIVE_ALL</tag>Relative to the current directory. Use RELATIVE_ALL<em>
 </em>instead of RELATIVE_PATH
</descrip>
</p><sect1>
Defaults<label id="sec:relatives_defaults" >
<p>
You might be thinking to yourself that passing along RELATIVE
 defines with every VFS call is overkill, especially if your application
 always uses the same relativity. The default RELATIVE define for
 all VFS calls is RELATIVE_CURRENT. RELATIVE_CURRENT itself defaults
 to RELATIVE_ALL (relative to the current path), <em>unless</em> your application
 sets a specific relativity. If your application requires most of
 the work to be done outside of the virtual root, you may wish to
 set RELATIVE_CURRENT to RELATIVE_NONE|VFS_REAL. set_relative () is
 the function to do this. For example:
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;set_relative (array(
     'mask' =&gt; RELATIVE_NONE|VFS_REAL
));

&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;read (array(
     'string' =&gt; '/etc/passwd'
));

&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;cp (array(
     'from' =&gt; '/usr/include/stdio.h',
     'to' =&gt; '/tmp/stdio.h'
));

&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;cp (array(
     'from' =&gt; '/usr/share/pixmaps/yes.xpm',
     'to' =&gt; 'icons/yes.xpm',
     'relatives' =&gt; array(
          RELATIVE_CURRENT,
          RELATIVE_USER
     )
));
</verb>
</p><p>
You should notice that no relativity array is needed in the other
 calls that refer to files outside the virtual root, but one is needed
 for calls that include files inside the virtual root. Any RELATIVE
 define can be set as the default and works in the same fashion. To
 retrieve the currently set define, use get_relative (). Note that
 the relativity is reset after each page request; that is, it's good
 only for the life of the current page loading, and is not stored
 in session management.
</p>
<sect>
Function reference<label id="sec:function_reference" >
<p>
To view the function reference for the VFS, use the doc/inlinedocparser.php
 script that comes with eGoupWare, ie <url url="http://localhost/doc/inlinedocparser.php?fn=class.vfs_sql.inc.php" name="http://localhost/doc/inlinedocparser.php?fn=class.vfs_sql.inc.php">.
</p>
<sect>
Notes<label id="sec:notes" >
<sect1>
Database<label id="sec:database" >
<p>
Data about the files and directories within the virtual root
 is kept in the SQL database. Currently, this information includes:
</p>
<p>
<itemize>
 <item>
File ID (used internally, primary key for table)
 <item>
Owner ID (phpGW account_id)
 <item>
Created by ID (phpGW account_id)
 <item>
Modified by ID (phpGW account_id)
 <item>
Created (date)
 <item>
Modified (date)
 <item>
Size (bytes)
 <item>
MIME type
 <item>
Deleteable (Y/N/Other?)
 <item>
Comment
 <item>
App (appname of application that created the file)
 <item>
Directory (directory the file or directory is in)
 <item>
Name (name of file or directory)
 <item>
Link directory (if the file or directory is linked, what the
 actual directory is)
 <item>
Link name (if the file or directory is linked, what the actual
 name is)
 <item>
Version (numeric version of the file)
</itemize>
</p><p>
The internal names of these (the database column names) are stored
 in the &dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;attributes
 array, which is useful for loops, and is guaranteed to be up-to-date.
</p>
<p>
Note that no information is kept about files outside the virtual
 root. If a file is moved outside, all records of it are deleted from
 the database (other than the journaling records). If a file is moved
 into the virtual root, some information, specifically MIME-type,
 is not always stored in the database. The vital information has defaults:
 owner is based on where the file is being stored; size is correctly
 read; deleteable is set to Y.
</p>
<sect1>
ACL support<label id="sec:acl_support" >
<p>
ACL support is built into the VFS. vfs-&gt;acl_check () does
 the actual checking, and is called from all VFS functions as needed.
 If the file or directory sent to acl_check () doesn't exist, the
 permissions for the parent directory are used to determine access.
 ACL checking can be overridden at any time by setting vfs-&gt;override_acl.
 For example:
</p>
<p>
<verb>
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;override_acl = 1;
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;mkdir (array(
     'string' =&gt; &dollar;GLOBALS&lsqb;'fakebase'&rsqb;. '/' . &dollar;group_array&lsqb;'account_name'&rsqb;,
     'relatives' =&gt; array(
          RELATIVE_NONE
     )
));
&dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;override_acl = 0;
</verb>
</p><sect1>
Function aliases<label id="sec:function_aliases" >
<p>
You might have noticed there are some functions that just pass
 the arguments on to other functions. These are provided in part because
 of legacy and in part for convenience. You can use either. Here is
 the list (alias -&gt; actual):
</p>
<p>
<itemize>
 <item>
copy -&gt; cp
 <item>
move -&gt; rm
 <item>
delete -&gt; rm
 <item>
dir -&gt; ls
</itemize>
</p><sect1>
Fakebase directory (changing /home)<label id="sec:fakebase" >
<p>
The old VFS was hard-coded to use '/home' as the fake base directory,
 even though the user never saw it. With the new system, crafty administrators
 may wish to change '/home' to something else, say '/users' or '/public_html'.
 The fake base directory name is stored in &dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;fakebase,
 and changing it will transparently change it throughout the VFS and
 all applications. However, this must be done <em>before</em> any data is in
 the VFS database. If you wish to change it afterwords, you'll have
 to manually update the database, replacing the old value with the
 new value. <em>Application programmers need to recognize that /home is
 not absolute, and use &dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;fakebase
 instead</em>. I suggest setting &dollar;fakebase = &dollar;GLOBALS&lsqb;'phpgw'&rsqb;-&gt;vfs-&gt;fakebase;
 right off the bat to keep things neater.
</p>
<sect>
About this Document
<sect1>
Copyright and License
<p>
Copyright (c) 2001, 2002 Jason Wies
</p>
<p>
Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation License, Version
 1.1 or any later version published by the Free Software Foundation;
 with no Invarient Sections, with no Front-Cover Texts, and no Back-Cover
 Texts.
</p>
<p>
A copy of the license is available at <url url="http://www.gnu.org/copyleft/fdl.html" name="http://www.gnu.org/copyleft/fdl.html">.
</p>
<sect1>
History
<p>
Original document released in June 2001 by Jason Wies.
</p>
<p>
Updated February 2002 to include arrayized parameters, single
 quotes, and GLOBALS.
</p>
<sect1>
Contributing
<p>
Contributions are always welcome. Please send to the current
 maintainer, Jason Wies, 
</p>


</article>