There are two functions you'll need to know before we get into relativity.
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
)
));
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.
Part of the overall goal for the VFS in phpGroupWare 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.