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/phpgroupware/files/home/user/file1',
     'to' => '/var/www/phpgroupware/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.