vfs.txt

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

egroupware/files/home/my_group/project1/logo.png');
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 outside the virtual
root.
$GLOBALS['phpgw']->vfs->mv (array(
     'from' => $GLOBALS['phpgw_info']['server']['temp_dir'] . '/' . $randomdir
. '/' . $randomfile,
     'to' => 'attachments/actual_name.ext',
     'relatives' => array(
          RELATIVE_NONE|VFS_REAL,
          RELATIVE_USER
     )
));
$randomdir and $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 outside 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 $randomdir and $randomfile are just random strings):
rename ('/var/www/egroupware/tmp/0ak5adftgh7/jX42sC9M', '/var/www/
egroupware/files/home/jason/attachments/actual_name.ext');
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 ~/.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:
$GLOBALS['phpgw']->vfs->write (array(
     'string' => 'file.name~',
     'relatives' => array(
          RELATIVE_USER_APP
     ),
     'content' => $contents
));
This assumes that ~/.htmledit exists of course. The backup file "file.name~"
would then be written in $fakebase/jason/.htmledit/file.name~. 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.
*****  4.2 Complete_List *****
Here is the complete list of RELATIVE defines, and what they do:
  RELATIVE_ROOT
      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.
  RELATIVE_USER
      User's home directory
  RELATIVE_CURR_USER
      Current user's home directory. If the current directory is $fakebase/
      my_group/project1, this will return is $fakebase/my_group
  RELATIVE_USER_APP
      Append .appname to the user's home directory, where appname is the
      current application's appname
  RELATIVE_PATH
      DO NOT USE. Relative to the current directory, used in RELATIVE_ALL
  RELATIVE_NONE
      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
  RELATIVE_CURRENT
      An alias for the currently set RELATIVE define, or RELATIVE_ALL if none
      is set (see the Defaults section)
  VFS_REAL
      File is outside of the virtual root. Usually used with RELATIVE_NONE
  RELATIVE_ALL
      Relative to the current directory. Use RELATIVE_ALLinstead of
      RELATIVE_PATH
*****  4.3 Defaults *****
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), unless 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:
$GLOBALS['phpgw']->vfs->set_relative (array(
     'mask' => RELATIVE_NONE|VFS_REAL
));

$GLOBALS['phpgw']->vfs->read (array(
     'string' => '/etc/passwd'
));

$GLOBALS['phpgw']->vfs->cp (array(
     'from' => '/usr/include/stdio.h',
     'to' => '/tmp/stdio.h'
));

$GLOBALS['phpgw']->vfs->cp (array(
     'from' => '/usr/share/pixmaps/yes.xpm',
     'to' => 'icons/yes.xpm',
     'relatives' => array(
          RELATIVE_CURRENT,
          RELATIVE_USER
     )
));
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.
===============================================================================
Next Previous Contents


Next Previous Contents
===============================================================================
*****  5. Function_reference *****
To view the function reference for the VFS, use the doc/inlinedocparser.php
script that comes with eGoupWare, ie http://localhost/doc/
inlinedocparser.php?fn=class.vfs_sql.inc.php.
===============================================================================
Next Previous Contents


Next Previous Contents
===============================================================================
*****  6. Notes *****
*****  6.1 Database *****
Data about the files and directories within the virtual root is kept in the SQL
database. Currently, this information includes:
    * File ID (used internally, primary key for table)
    * Owner ID (phpGW account_id)
    * Created by ID (phpGW account_id)
    * Modified by ID (phpGW account_id)
    * Created (date)
    * Modified (date)
    * Size (bytes)
    * MIME type
    * Deleteable (Y/N/Other?)
    * Comment
    * App (appname of application that created the file)
    * Directory (directory the file or directory is in)
    * Name (name of file or directory)
    * Link directory (if the file or directory is linked, what the actual
      directory is)
    * Link name (if the file or directory is linked, what the actual name is)
    * Version (numeric version of the file)
The internal names of these (the database column names) are stored in the
$GLOBALS['phpgw']->vfs->attributes array, which is useful for loops, and is
guaranteed to be up-to-date.
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.
*****  6.2 ACL_support *****
ACL support is built into the VFS. vfs->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->override_acl. For example:
$GLOBALS['phpgw']->vfs->override_acl = 1;
$GLOBALS['phpgw']->vfs->mkdir (array(
     'string' => $GLOBALS['fakebase']. '/' . $group_array['account_name'],
     'relatives' => array(
          RELATIVE_NONE
     )
));
$GLOBALS['phpgw']->vfs->override_acl = 0;
*****  6.3 Function_aliases *****
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 -> actual):
    * copy -> cp
    * move -> rm
    * delete -> rm
    * dir -> ls
*****  6.4 Fakebase_directory_(changing_/home) *****
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 $GLOBALS['phpgw']->vfs->fakebase, and
changing it will transparently change it throughout the VFS and all
applications. However, this must be done before 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. Application
programmers need to recognize that /home is not absolute, and use $GLOBALS
['phpgw']->vfs->fakebase instead. I suggest setting $fakebase = $GLOBALS
['phpgw']->vfs->fakebase; right off the bat to keep things neater.
===============================================================================
Next Previous Contents

Next Previous Contents
===============================================================================
***** 7. About_this_Document *****
***** 7.1 Copyright_and_License *****
Copyright (c) 2001, 2002 Jason Wies
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.
A copy of the license is available at http://www.gnu.org/copyleft/fdl.html.
***** 7.2 History *****
Original document released in June 2001 by Jason Wies.
Updated February 2002 to include arrayized parameters, single quotes, and
GLOBALS.
***** 7.3 Contributing *****
Contributions are always welcome. Please send to the current maintainer, Jason
Wies, 
===============================================================================
Next Previous Contents