vfs.txt

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

Next Previous Contents
===============================================================================
*****  1. Introduction_and_Purpose *****
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.
===============================================================================
Next Previous Contents


Next Previous Contents
===============================================================================
*****  2. Basics *****
*****  2.1 Prerequisites *****
You must explicitly enable the VFS class. To do this, set 'enable_vfs_class' to
True in $GLOBALS['phpgw_info']['flags']. An example:
$GLOBALS['phpgw_info']['flags'] = array(
     'currentapp' => 'phpwebhosting',
     'noheader' => False,
     'noappheader' => False,
     'enable_vfs_class' => True,
     'enable_browser_class' => True
);
*****  2.2 Concepts *****
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:
    * Files and directories are synonymous in almost all cases
$GLOBALS['phpgw']->vfs->mv (array(
     'from' => 'file1',
     'to' => 'dir/file2'
));

$GLOBALS['phpgw']->vfs->mv (array(
     'from' => 'dir1',
     'to' => 'dir/dir1'
));

$GLOBALS['phpgw']->vfs->rm (array(
     'string' => 'file'
));

$GLOBALS['phpgw']->vfs->rm (array(
     'string' => 'dir'
));
All work as you would except them to. The major exception is:
$GLOBALS['phpgw']->vfs->touch (array(
     'string' => 'file'
));
vs.
$GLOBALS['phpgw']->vfs->mkdir (array(
     'string' => 'dir'
));
    * Users and groups are synonymous
As far as the actual paths are concerned, users and groups are the same. /home/
username works the same as /home/groupname.
    * You should never have to know the real paths of files
One of the VFS's responsibilities is to translate paths for you. While you
certainly can operate using full paths, it is much simpler to use the virtual
paths. For example, instead of using:
$GLOBALS['phpgw']->vfs->cp (array(
     'from' => '/var/www/egroupware/files/home/user/file1',
     'to' => '/var/www/egroupware/files/home/user/file2',
     'relatives' => array(
          RELATIVE_NONE|VFS_REAL,
          RELATIVE_NONE|VFS_REAL
     )
));
you might use
$GLOBALS['phpgw']->vfs->cp (array(
     'from' => '/home/user/file1',
     'to' => '/home/user/file2',
     'relatives' => array(
          RELATIVE_NONE,
          RELATIVE_NONE
     )
));
(We'll get to the RELATIVE's in a minute.)
Site administrators should be able to move their files dir around on their
system and know that everything will continue to work smoothly.
    * Relativity is vital
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.
===============================================================================
Next Previous Contents


Next Previous Contents
===============================================================================
*****  3. Basic_Functions *****
These are two functions you'll need to know before we get into relativity.
*****  3.1 path_parts_() *****
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:
string
relatives
object
'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:
fake_full_path
fake_leading_dirs
fake_extra_path
fake_name
real_full_path
real_leading_dirs
real_extra_path
real_name
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 = $GLOBALS['phpgw']->vfs->path_parts (array(
     'string' => '/home/jason/dir/file',
     'relatives' => array(
         RELATIVE_NONE
     )
));
    * $p->fake_full_path - /home/jason/dir/file
    * $p->fake_leading_dirs - /home/jason/dir
    * $p->fake_extra_path - home/jason/dir
    * $p->fake_name - file
    * $p->real_full_path - /var/www/egroupware/files/home/jason/dir/file
    * $p->real_leading_dirs - /var/www/egroupware/files/home/jason/dir
    * $p->real_extra_path - home/jason/dir
    * $p->real_name - file
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 getabsolutepath () is depreciated. getabsolutepath () still exists
(albeit in a much different form), and is responsible for some of the path
translation, but it is an internal 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.
*****  3.2 cd_() *****
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:
/* cd to their home directory */
$GLOBALS['phpgw']->vfs->cd (array(
     'string' => '/'
));

/* cd to /home/jason/dir */
$GLOBALS['phpgw']->vfs->cd (array(
     'string' => '/home/jason/dir',
     'relative' => False,
     'relatives' => array(
          RELATIVE_NONE
     )
));

/* When following the above, cd's to /home/jason/dir/dir2 */
$GLOBALS['phpgw']->vfs->cd (array(
     'string' => 'dir2',
     'relative' => True
));
If 'relative' is True, the 'string' is simply appended to the current path. If
you want to know what the current path is, use $GLOBALS['phpgw']->vfs->pwd ().
Now you're ready for relativity.
===============================================================================
Next Previous Contents


Next Previous Contents
===============================================================================
*****  4. Relativity *****
Ok, just one last thing before we get into relativity. You will notice
throughout the examples the use of $fakebase. $GLOBALS['phpgw']->vfs->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 Fakebase_directory_
(changing_/home) section for more information. Throughout the rest of this
document, you will see $fakebase used in calls to the VFS, and /home used in
actual paths. You should always use $fakebase when making applications.I
suggest doing $fakebase = $GLOBALS['phpgw']->vfs->fakebase; right off the bat
to keep things neater.
***** 4.1 What_is_it_and_how_does_it_work? *****
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.
$GLOBALS['phpgw']->vfs->mv (array(
    'from' => 'logo.png',
    'to' => 'logo.png',
    'relatives' => array(
          RELATIVE_USER,
          RELATIVE_ALL
     )
));
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 "$fakebase/my_group/project1", the call to mv
() would be processed as:
MOVE "$fakebase/jason/logo.png" TO "$fakebase/my_group/project1/logo.png"
and the actual file system call would be:
rename ('/var/www/egroupware/files/home/jason/logo.php', '/var/www/