-Ok, one more thing before we discuss relativity, and that is the cd ()
- function. 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 /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. The prototype and examples:
-
+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 /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. The prototype and examples:
@@ -229,9 +226,9 @@ Now you're ready for relativity.
Relativity
Ok, just one last thing before we get into relativity. You will notice
- throughout the examples the use of $fakebase. $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 "Notes -> Fakebase directory"
+ throughout the examples the use of $fakebase. $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 "Notes - Fakebase directory"
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
@@ -295,7 +292,7 @@ Those used to the old VFS will note that you do not have to translate the
-rename ("/var/www/phpgroupware/tmp/0ak5adftgh7/jX42sC9M", "/var/www/phpgroupware/files/home/users/jason/attachments/actual_name.ext");
+rename ("/var/www/phpgroupware/tmp/0ak5adftgh7/jX42sC9M", "/var/www/phpgroupware/files/home/jason/attachments/actual_name.ext");
Of course you don't have to know that, nor should you be concerned with
@@ -1143,6 +1140,33 @@ The old VFS was hard-coded to use "/home" as the fake base directory,
I suggest setting $fakebase = $phpgw->vfs->fakebase; right
off the bat to keep things neater.
+
+About this Document
+
+Copyright and License
+
+Copyright (c) 2001 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 .
+
+
+History
+
+Original document released in June 2001 by Jason Wies.
+
+
+Contributing
+
+Contributions are always welcome. Please send to the current maintainer,
+ Jason Wies, .
+
diff --git a/phpgwapi/doc/vfs/vfs.txt b/phpgwapi/doc/vfs/vfs.txt
index a06176f337..e733204d0b 100644
--- a/phpgwapi/doc/vfs/vfs.txt
+++ b/phpgwapi/doc/vfs/vfs.txt
@@ -1,910 +1,1034 @@
+ phpgwapi - VFS Class
+ Jason Wies
+ June 2001
+ The VFS, or Virtual File System, handles all file system activity for
+ phpGroupWare.
-phpgwapi - VFS Class
+ 11.. IInnttrroodduuccttiioonn aanndd PPuurrppoossee
-Jason Wies
+ The latest version of the VFS for phpGroupWare 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.
-June 2001
+ 22.. BBaassiiccss
-Abstract
+ 22..11.. PPrreerreeqquuiissiitteess
-The VFS, or Virtual File System, handles all file system activity for
-phpGroupWare.
+ You must explicitly enable the VFS class. To do this, set
+ "enable_vfs_class" to True in $phpgw_info["flags"]. An example:
-1 Introduction and Purpose
-The latest version of the VFS for phpGroupWare 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.
+ $phpgw_info["flags"] = array("currentapp" => "phpwebhosting",
+ "noheader" => False,
+ "noappheader" => False,
+ "enable_vfs_class" => True,
+ "enable_browser_class" => True);
-2 Basics
-2.1 Prerequisites
-You must explicitly enable the VFS class. To do this, set "enable_vfs_class"
-to True in $phpgw_info["flags"]. An example:
+ 22..22.. CCoonncceeppttss
-$phpgw_info["flags"] = array("currentapp" => "phpwebhosting",
+ The VFS in located in phpgwapi/inc/class.vfs.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:
-"noheader" => False,
-"noappheader" => False,
+ +o Files and directories are synonymous in almost all cases
-"enable_vfs_class" => True,
-"enable_browser_class" => True);
+ $phpgw->vfs->mv ("file1", "dir/file2");
+ $phpgw->vfs->mv ("dir1", "dir/dir1");
+ $phpgw->vfs->rm ("file");
+ $phpgw->vfs->rm ("dir");
-2.2 Concepts
-The VFS in located in phpgwapi/inc/class.vfs.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
+ All work as you would except them to. The major exception is:
-$phpgw->vfs->mv ("file1", "dir/file2");
-$phpgw->vfs->mv ("dir1", "dir/dir1");
+ $phpgw->vfs->touch ("file");
-$phpgw->vfs->rm ("file");
-$phpgw->vfs->rm ("dir");
-All work as you would except them to. The major exception is:
+ vs.
-$phpgw->vfs->touch ("file");
-vs.
+ $phpgw->vfs->mkdir ("dir");
-$phpgw->vfs->mkdir ("dir");
-* Users and groups and synonymous
-As far as the actual paths are concerned, users and groups are the
-same. The VFS has no built in ACL support, so /home/username works
-the same as /home/groupname. See the note on AC L support in the Notes
-section.
+ +o Users and groups and synonymous
-* You should never have to know the real path of files
+ As far as the actual paths are concerned, users and groups are the
+ same. The VFS has no built in ACL support, so /home/username works
+ the same as /home/groupname. See the note on ACL support in the Notes
+ section.
-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:
-$phpgw->vfs->cp ("/var/www/phpgroupware/files/home/user/file1", "/var/www/phpgroupware/files/home/user/file2",
-array (RELATIVE_NONE|VFS_REAL, RELATIVE_NONE|VFS_REAL));
+ +o You should never have to know the real path of files
-you might use
+ One of the VFS's responsibilities is to translate paths for you. While
+ you certainly _c_a_n operate using full paths, it is much simpler to use
+ the virtual paths. For example, instead of using:
-$phpgw->vfs->cp ("/home/user/file1", "/home/user/file2", array (RELATIVE_NONE,
-RELATIVE_NONE));
-(We'll get to the RELATIVE's in a minute.)
+ $phpgw->vfs->cp ("/var/www/phpgroupware/files/home/user/file1", "/var/www/phpgroupware/files/home/user/file2", array (RELATIVE_NONE|VFS_REAL, RELATIVE_NONE|VFS_REAL));
-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.
+ you might use
-3 Basic Functions
-These are two functions you'll need to know before we get into relativity.
+ $phpgw->vfs->cp ("/home/user/file1", "/home/user/file2", array (RELATIVE_NONE, RELATIVE_NONE));
-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 prototype for path_parts
-() is:
-function path_parts ($string, $relatives = array (RELATIVE_CURRENT),
-$object = True)
+ (We'll get to the RELATIVE's in a minute.)
-$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:
+ Site administrators should be able to move their files dir around on
+ their system and know that everything will continue to work smoothly.
-fake_full_path
-fake_leading_dirs
+ +o Relativity is _v_i_t_a_l
-fake_extra_path
+ 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.
-fake_name
+ 33.. BBaassiicc FFuunnccttiioonnss
-real_full_path
+ These are two functions you'll need to know before we get into
+ relativity.
-real_leading_dirs
+ 33..11.. ppaatthh__ppaarrttss (())
-real_extra_path
+ The job of path_parts () is to translate any given file location into
+ its many component parts for any relativity. The prototype for
+ path_parts () is:
-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:
+ function path_parts ($string, $relatives = array (RELATIVE_CURRENT), $object = True)
-$p = $phpgw->vfs->path_parts ("/home/jason/dir/file", array (RELATIVE_NONE));
-* $p->fake_full_path - /home/jason/dir/file
-* $p->fake_leading_dirs - /home/jason/dir
+ $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:
-* $p->fake_extra_path - home/jason/dir
-* $p->fake_name - file
+ fake_full_path
+ fake_leading_dirs
+ fake_extra_path
+ fake_name
+ real_full_path
+ real_leading_dirs
+ real_extra_path
+ real_name
-* $p->real_full_path - /var/www/phpgroupware/files/home/jason/dir/file
-* $p->real_leading_dirs - /var/www/phpgroupware/files/home/jason/dir
-* $p->real_extra_path - home/jason/dir
+ 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->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 relativity in Section [sec:relativity].
+ $p = $phpgw->vfs->path_parts ("/home/jason/dir/file", array (RELATIVE_NONE));
-3.2 cd ()
-Ok, one more thing before we discuss relativity, and that is the cd
-() function. 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 /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. The prototype and examples:
-function cd ($target = "/", $relative = True, $relatives = array (RELATIVE_CURRENT))
+ +o $p->fake_full_path - /home/jason/dir/file
-$phpgw->vfs->cd ("/"); /* cd to their home directory */
+ +o $p->fake_leading_dirs - /home/jason/dir
-$phpgw->vfs->cd ("/home/jason/dir", False, array (RELATIVE_NONE));
-/* cd to /home/jason/dir */
+ +o $p->fake_extra_path - home/jason/dir
-$phpgw->vfs->cd ("dir2", True); /* When following the above, cd's to
-/home/jason/dir/dir2 */
+ +o $p->fake_name - file
-If $relatives is True, the $target is simply appended to the current
-path. If you want to know what the current path is, use $phpgw->vfs->pwd
-().
+ +o $p->real_full_path -
+ /var/www/phpgroupware/files/home/jason/dir/file
-Now you're ready for relativity.
+ +o $p->real_leading_dirs - /var/www/phpgroupware/files/home/jason/dir
-4 Relativity
-Ok, just one last thing before we get into relativity. You will notice
-throughout the examples the use of $fakebase. $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 "Notes -> Fakebase
-directory" 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 = $phpgw->vfs->fakebase; right
-off the bat to keep things neater.
+ +o $p->real_extra_path - home/jason/dir
-4.1 What is it and how does it work?
+ +o $p->real_name - file
-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 phpGroupWare 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.
+ 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 _g_e_t_a_b_s_o_l_u_t_e_p_a_t_h _(_) _i_s _d_e_p_r_e_c_i_a_t_e_d.
+ getabsolutepath () still exists (albeit in a much different form), and
+ is responsible for some of the path translation, but it is an _i_n_t_e_r_n_a_l
+ 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.
-$phpgw->vfs->mv ("logo.png", "", array (RELATIVE_USER, RELATIVE_ALL));
+ 33..22.. ccdd (())
-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:
+ 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 /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. The prototype and examples:
-MOVE "$fakebase/jason/logo.png" TO "$fakebase/my_group/project1/logo.png"
-and the actual file system call would be:
-rename ("/var/www/phpgroupware/files/home/jason/logo.php", "/var/www/phpgroupware/files/home/my_group/project1/logo.png");
+ function cd ($target = "/", $relative = True, $relatives = array (RELATIVE_CURRENT))
+ $phpgw->vfs->cd ("/"); /* cd to their home directory */
+ $phpgw->vfs->cd ("/home/jason/dir", False, array (RELATIVE_NONE)); /* cd to /home/jason/dir */
+ $phpgw->vfs->cd ("dir2", True); /* When following the above, cd's to /home/jason/dir/dir2 */
-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 phpGroupWare'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.
-$phpgw->vfs->mv ("$phpgw_info[server][temp_dir]/$randomdir/$randomfile",
-"attachments/actual_name.ext", 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):
+ If $relatives is True, the $target is simply appended to the current
+ path. If you want to know what the current path is, use
+ $phpgw->vfs->pwd ().
-rename ("/var/www/phpgroupware/tmp/0ak5adftgh7/jX42sC9M", "/var/www/phpgroupware/files/home/users/jason/attachments/actual_name.ext");
+ Now you're ready for relativity.
-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
-would use RELATIVE_USER_APP to store it:
+ 44.. RReellaattiivviittyy
-$phpgw->vfs->write ("file.name~", array (RELATIVE_USER_APP), $contents);
+ Ok, just one last thing before we get into relativity. You will notice
+ throughout the examples the use of $fakebase. $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 "Notes -
+ Fakebase directory" 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. _Y_o_u _s_h_o_u_l_d _a_l_w_a_y_s _u_s_e _$_f_a_k_e_b_a_s_e _w_h_e_n
+ _m_a_k_i_n_g _a_p_p_l_i_c_a_t_i_o_n_s_. I suggest doing $fakebase =
+ $phpgw->vfs->fakebase; right off the bat to keep things neater.
-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.
+ 44..11.. WWhhaatt iiss iitt aanndd hhooww ddooeess iitt wwoorrkk??
-4.2 Complete List
+ 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 phpGroupWare 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.
-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
+ $phpgw->vfs->mv ("logo.png", "", array (RELATIVE_USER, RELATIVE_ALL));
-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_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:
-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)
+ MOVE "$fakebase/jason/logo.png" TO "$fakebase/my_group/project1/logo.png"
-VFS_REAL File is outside of the virtual root. Usually used with RELATIVE_NONE
-RELATIVE_ALL Relative to the current directory. Use RELATIVE_ALL
- instead of RELATIVE_PATH
-4.3 Defaults
+ and the actual file system call would be:
-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:
-$phpgw->vfs->set_relative (RELATIVE_NONE|VFS_REAL);
+ rename ("/var/www/phpgroupware/files/home/jason/logo.php", "/var/www/phpgroupware/files/home/my_group/project1/logo.png");
-$phpgw->vfs->read ("/etc/passwd");
-$phpgw->vfs->cp ("/usr/include/stdio.h", "/tmp/stdio.h");
-$phpgw->vfs->cp ("/usr/share/pixmaps/yes.xpm", "icons/yes.xpm", array
-(RELATIVE_CURRENT, RELATIVE_USER));
+ 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 phpGroupWare'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 _o_u_t_s_i_d_e the virtual root.
+ $phpgw->vfs->mv ("$phpgw_info[server][temp_dir]/$randomdir/$randomfile", "attachments/actual_name.ext", array (RELATIVE_NONE|VFS_REAL, 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.
-5 Function reference
-5.1 About
+ $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 _o_u_t_s_i_d_e 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):
-This function reference is periodically auto-generated from the inline
-comments in phpgwapi/inc/class.vfs.inc.php. For the most up-to-date
-(and nicer looking) reference, see class.vfs.inc.php. This reference
-is created as a separate DocBook document (using the inline2lyx.pl
-script), so it might look a bit out of place.
-5.2 class vfs
+ rename ("/var/www/phpgroupware/tmp/0ak5adftgh7/jX42sC9M", "/var/www/phpgroupware/files/home/jason/attachments/actual_name.ext");
-abstract: virtual file system
-description: Authors: Zone, Seek3r
-5.3 class path_class
+ 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 would use RELATIVE_USER_APP to store it:
-abstract: helper class for path_parts
-5.4 vfs
+ $phpgw->vfs->write ("file.name~", array (RELATIVE_USER_APP), $contents);
-abstract: constructor, sets up variables
-function vfs ()
-5.5 set_relative
+ 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.
-abstract: Set path relativity
+ 44..22.. CCoommpplleettee LLiisstt
-param: $mask Relative bitmask (see RELATIVE_ defines)
+ Here is the complete list of RELATIVE defines, and what they do:
-function set_relative ($mask)
-5.6 get_relative
+ RREELLAATTIIVVEE__RROOOOTT
+ 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.
-abstract: Return relativity bitmask
+ RREELLAATTIIVVEE__UUSSEERR
+ User's home directory
-discussion: Returns relativity bitmask, or the default of "completely
-relative" if unset
+ RREELLAATTIIVVEE__CCUURRRR__UUSSEERR
+ Current user's home directory. If the current directory is
+ $fakebase/my_group/project1, this will return is
+ $fakebase/my_group
-function get_relative ()
+ RREELLAATTIIVVEE__UUSSEERR__AAPPPP
+ Append .appname to the user's home directory, where appname is
+ the current application's appname
-5.7 sanitize
+ RREELLAATTIIVVEE__PPAATTHH
+ DO NOT USE. Relative to the current directory, used in
+ RELATIVE_ALL
+ RREELLAATTIIVVEE__NNOONNEE
+ 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
- abstract: Removes leading .'s from $string
+ RREELLAATTIIVVEE__CCUURRRREENNTT
+ An alias for the currently set RELATIVE define, or RELATIVE_ALL
+ if none is set (see the Defaults section)
-discussion: You should not pass all filenames through sanitize () unless
-you plan on rejecting
+ VVFFSS__RREEAALL
+ File is outside of the virtual root. Usually used with
+ RELATIVE_NONE
-.files. Instead, pass the name through securitycheck () first, and
-if it fails,
+ RREELLAATTIIVVEE__AALLLL
+ Relative to the current directory. Use RELATIVE_ALLinstead of
+ RELATIVE_PATH
-pass it through sanitize
+ 44..33.. DDeeffaauullttss
-param: $string string to sanitize
+ 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), _u_n_l_e_s_s 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:
-result: $string without it's leading .'s
-function sanitize ($string)
+ $phpgw->vfs->set_relative (RELATIVE_NONE|VFS_REAL);
+ $phpgw->vfs->read ("/etc/passwd");
+ $phpgw->vfs->cp ("/usr/include/stdio.h", "/tmp/stdio.h");
+ $phpgw->vfs->cp ("/usr/share/pixmaps/yes.xpm", "icons/yes.xpm", array (RELATIVE_CURRENT, RELATIVE_USER));
-5.8 securitycheck
-abstract: Security check function
-discussion: Checks for basic violations such as ..
+ 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.
-If securitycheck () fails, run your string through vfs->sanitize ()
+ 55.. FFuunnccttiioonn rreeffeerreennccee
-param: $string string to check security of
+ 55..11.. AAbboouutt
-result: Boolean True/False. True means secure, False means insecure
+ This function reference is periodically auto-generated from the inline
+ comments in phpgwapi/inc/class.vfs.inc.php. For the most up-to-date
+ (and nicer looking) reference, see class.vfs.inc.php. This reference
+ is created as a separate DocBook document (using the inline2lyx.pl
+ script), so it might look a bit out of place.
-function securitycheck ($string)
+ 55..22.. ccllaassss vvffss
-5.9 db_clean
+ abstract: virtual file system
-abstract: Clean $string for use in database queries
+ description: Authors: Zone, Seek3r
-param: $string String to clean
+ 55..33.. ccllaassss ppaatthh__ccllaassss
-result: Cleaned version of $string
+ abstract: helper class for path_parts
-function db_clean ($string)
+ 55..44.. vvffss
-5.10 path_parts
+ abstract: constructor, sets up variables
-abstract: take a real or fake pathname and return an array of its component
-parts
-param: $string full real or fake path
+ function vfs ()
-param: $relatives Relativity array
-param: $object True returns an object instead of an array
-result: $rarray/$robject Array or object containing the fake and real
-component parts of the path
+ 55..55.. sseett__rreellaattiivvee
-discussion: Returned values are:
+ abstract: Set path relativity
-mask
+ param: $mask Relative bitmask (see RELATIVE_ defines)
-outside
-fake_full_path
+ function set_relative ($mask)
-fake_leading_dirs
-fake_extra_path
-fake_name
+ 55..66.. ggeett__rreellaattiivvee
-real_full_path
+ abstract: Return relativity bitmask
-real_leading_dirs
+ discussion: Returns relativity bitmask, or the default of "completely
+ relative" if unset
-real_extra_path
-real_name
+ function get_relative ()
-fake_full_path_clean
-fake_leading_dirs_clean
-fake_extra_path_clean
+ 55..77.. ssaanniittiizzee
-fake_name_clean
+ abstract: Removes leading .'s from $string
-real_full_path_clean
+ discussion: You should not pass all filenames through sanitize ()
+ unless you plan on rejecting
-real_leading_dirs_clean
+ .files. Instead, pass the name through securitycheck () first, and if
+ it fails,
-real_extra_path_clean
+ pass it through sanitize
-real_name_clean
+ param: $string string to sanitize
-"clean" values are run through vfs->db_clean () and
+ result: $string without it's leading .'s
-are safe for use in SQL queries that use key='value'
-They should be used ONLY for SQL queries, so are used
+ function sanitize ($string)
-mostly internally
-mask is either RELATIVE_NONE or RELATIVE_NONE|VFS_REAL,
-and is used internally
+ 55..88.. sseeccuurriittyycchheecckk
-outside is boolean, True if $relatives contains VFS_REAL
+ abstract: Security check function
-function path_parts ($string, $relatives = array (RELATIVE_CURRENT),
-$object = True)
+ discussion: Checks for basic violations such as ..
-5.11 getabsolutepath
+ If securitycheck () fails, run your string through vfs->sanitize ()
-abstract: get the absolute path
+ param: $string string to check security of
-param: $target defaults to False, directory/file to get path of, relative
-to $relatives[0]
+ result: Boolean True/False. True means secure, False means insecure
-param: $mask Relativity bitmask (see RELATIVE_ defines). RELATIVE_CURRENT
-means use $this->relative
-param: $fake Returns the "fake" path, ie /home/user/dir/file (not always
-possible. use path_parts () instead)
+ function securitycheck ($string)
-result: $basedir Full fake or real path
-function getabsolutepath ($target = False, $relatives = array (RELATIVE_CURRENT),
-$fake = True)
-5.12 cd
+ 55..99.. ddbb__cclleeaann
-abstract: Change directory
+ abstract: Clean $string for use in database queries
-discussion: To cd to the files root "/", use cd ("/", False, array
-(RELATIVE_NONE));
+ param: $string String to clean
-param: $target default "/". directory to cd into. if "/" and $relative
-is True, uses "/home/";
+ result: Cleaned version of $string
-param: $relative default True/relative means add target to current
-path, else pass $relative as mask to getabsolutepath()
-function cd ($target = "/", $relative = True, $relatives = array (RELATIVE_CURRENT))
+ function db_clean ($string)
-5.13 pwd
-abstract: current working dir
-param: $full default True returns full fake path, else just the extra
-dirs (false strips the leading /)
+ 55..1100.. ppaatthh__ppaarrttss
-result: $currentdir currentdir
+ abstract: take a real or fake pathname and return an array of its
+ component parts
-function pwd ($full = True)
+ param: $string full real or fake path
-5.14 read
+ param: $relatives Relativity array
-abstract: return file contents
+ param: $object True returns an object instead of an array
-param: $file filename
+ result: $rarray/$robject Array or object containing the fake and real
+ component parts of the path
-param: $relatives Relativity array
+ discussion: Returned values are:
-result: $contents Contents of $file, or False if file cannot be read
+ mask
-function read ($file, $relatives = array (RELATIVE_CURRENT))
+ outside
-5.15 write
+ fake_full_path
-abstract: write to a file
+ fake_leading_dirs
-param: $file file name
+ fake_extra_path
-param: $relatives Relativity array
+ fake_name
-param: $contents contents
+ real_full_path
-result: Boolean True/False
+ real_leading_dirs
-function write ($file, $relatives = array (RELATIVE_CURRENT), $contents)
+ real_extra_path
-5.16 touch
+ real_name
-abstract: Create blank file $file or set the modification time and
-modified by of $file to current time and user
+ fake_full_path_clean
-param: $file File to touch or set modifies
+ fake_leading_dirs_clean
-param: $relatives Relativity array
+ fake_extra_path_clean
-result: Boolean True/False
+ fake_name_clean
-function touch ($file, $relatives = array (RELATIVE_CURRENT))
+ real_full_path_clean
-5.17 cp
+ real_leading_dirs_clean
-abstract: copy file
-param: $from from file/directory
+ real_extra_path_clean
-param: $to to file/directory
+ real_name_clean
-param: $relatives Relativity array
+ "clean" values are run through vfs->db_clean () and
-result: boolean True/False
+ are safe for use in SQL queries that use key='value'
-function cp ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
+ They should be used ONLY for SQL queries, so are used
-5.18 mv
+ mostly internally
-abstract: move file/directory
+ mask is either RELATIVE_NONE or RELATIVE_NONE|VFS_REAL,
-param: $from from file/directory
+ and is used internally
-param: $to to file/directory
+ outside is boolean, True if $relatives contains VFS_REAL
-param: $relatives Relativity array
-result: boolean True/False
+ function path_parts ($string, $relatives = array (RELATIVE_CURRENT), $object = True)
-function mv ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
-5.19 move
-abstract: shortcut to mv
+ 55..1111.. ggeettaabbssoolluutteeppaatthh
-function move ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
+ abstract: get the absolute path
-5.20 rm
+ param: $target defaults to False, directory/file to get path of,
+ relative to $relatives[0]
-abstract: delete file/directory
+ param: $mask Relativity bitmask (see RELATIVE_ defines).
+ RELATIVE_CURRENT means use $this->relative
-param: $string file/directory to delete
+ param: $fake Returns the "fake" path, ie /home/user/dir/file (not
+ always possible. use path_parts () instead)
-param: $relatives Relativity array
+ result: $basedir Full fake or real path
-result: boolean True/False
-function rm ($string, $relatives = array (RELATIVE_CURRENT))
+ function getabsolutepath ($target = False, $relatives = array (RELATIVE_CURRENT), $fake = True)
-5.21 delete
-abstract: shortcut to rm
-function delete ($string, $relatives = array (RELATIVE_CURRENT))
+ 55..1122.. ccdd
-5.22 mkdir
+ abstract: Change directory
-abstract: make a new directory
+ discussion: To cd to the files root "/", use cd ("/", False, array
+ (RELATIVE_NONE));
-param: $dir Directory name
+ param: $target default "/". directory to cd into. if "/" and
+ $relative is True, uses "/home/";
-param: $relatives Relativity array
+ param: $relative default True/relative means add target to current
+ path, else pass $relative as mask to getabsolutepath()
-result: boolean True on success
-function mkdir ($dir, $relatives = array (RELATIVE_CURRENT))
+ function cd ($target = "/", $relative = True, $relatives = array (RELATIVE_CURRENT))
-5.23 set_attributes
-abstract: Update database entry for $file with the attributes in $attributes
-param: $file file/directory to update
+ 55..1133.. ppwwdd
-param: $relatives Relativity array
+ abstract: current working dir
-param: $attributes keyed array of attributes. key is attribute name,
-value is attribute value
-result: Boolean True/False
+ param: $full default True returns full fake path, else just the extra
+ dirs (false strips the leading /)
-discussion: Valid attributes are:
+ result: $currentdir currentdir
-owner_id
-createdby_id
+ function pwd ($full = True)
-modifiedby_id
-created
-modified
+ 55..1144.. rreeaadd
-size
+ abstract: return file contents
-mime_type
+ param: $file filename
-deleteable
+ param: $relatives Relativity array
-comment
+ result: $contents Contents of $file, or False if file cannot be read
-app
-function set_attributes ($file, $relatives = array (RELATIVE_CURRENT),
-$attributes = array ())
+ function read ($file, $relatives = array (RELATIVE_CURRENT))
-5.24 correct_attributes
-abstract: Set the correct attributes for $string (e.g. owner)
-param: $string File/directory to correct attributes of
+ 55..1155.. wwrriittee
-param: $relatives Relativity array
+ abstract: write to a file
-result: Boolean True/False
+ param: $file file name
-function correct_attributes ($string, $relatives = array (RELATIVE_CURRENT))
+ param: $relatives Relativity array
-5.25 file_type
+ param: $contents contents
-abstract: return file/dir type (MIME or other)
+ result: Boolean True/False
-param: $file File or directory path (/home/user/dir/dir2/dir3, /home/user/dir/dir2/file)
-param: $relatives Relativity array
+ function write ($file, $relatives = array (RELATIVE_CURRENT), $contents)
-result: MIME type, "Directory", or nothing if MIME type is not known
-function file_type ($file, $relatives = array (RELATIVE_CURRENT))
-5.26 file_exists
+ 55..1166.. ttoouucchh
-abstract: check if file/directory exists
+ abstract: Create blank file $file or set the modification time and
+ modified by of $file to current time and user
-param: $string file/directory to check existance of
+ param: $file File to touch or set modifies
-param: $relatives Relativity array
+ param: $relatives Relativity array
-result: Boolean True/False
+ result: Boolean True/False
-function file_exists ($string, $relatives = array (RELATIVE_CURRENT))
-5.27 checkperms
+ function touch ($file, $relatives = array (RELATIVE_CURRENT))
-abstract: Check if you have write access to create files in $dir
-discussion: This isn't perfect, because vfs->touch () returns True
-even
-if only the database entry worked. ACLs need to be
+ 55..1177.. ccpp
-implemented for better permission checking. It's
+ abstract: copy file
-also pretty slow, so I wouldn't recommend using it
+ param: $from from file/directory
-often
+ param: $to to file/directory
-param: $dir Directory to check access of
+ param: $relatives Relativity array
-param: $relatives Relativity array
+ result: boolean True/False
-result: Boolean True/False
-function checkperms ($dir, $relatives = array (RELATIVE_CURRENT))
+ function cp ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
-5.28 ls
-abstract: get directory listing
-discussion: Note: the entries are not guaranteed to be returned in
-any logical order
+ 55..1188.. mmvv
-param: $dir Directory
+ abstract: move file/directory
-param: $relatives Relativity array
+ param: $from from file/directory
-param: $checksubdirs Boolean, recursively list all sub directories
-as well?
+ param: $to to file/directory
-param: $mime_type Only return entries matching MIME-type $mime_type.
- Can be "Directory" or "\" for those without MIME types
+ param: $relatives Relativity array
-param: $nofiles Boolean. True means you want to return just the information
-about the directory $dir. If $dir is a file, $nofiles is implied.
- This is the equivalent of 'ls -ld $dir'
+ result: boolean True/False
-result: array of arrays. Subarrays contain full info for each file/dir.
-function ls ($dir = False, $relatives = array (RELATIVE_CURRENT), $checksubdirs
-= True, $mime_type = False, $nofiles = False)
+ function mv ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
-5.29 dir
-abstract: shortcut to ls
-function dir ($dir = False, $relatives = array (RELATIVE_CURRENT),
-$checksubdirs = True, $mime_type = False, $nofiles = False)
+ 55..1199.. mmoovvee
-6 Notes
+ abstract: shortcut to mv
-6.1 Database
-Data about the files and directories within the virtual root is kept
-in the SQL database. Currently, this information includes:
+ function move ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
-* File ID (used internally, primary key for table)
-* Owner ID (phpGW account_id)
-* Created by ID (phpGW account_id)
+ 55..2200.. rrmm
-* Modified by ID (phpGW account_id)
+ abstract: delete file/directory
-* Created (date)
+ param: $string file/directory to delete
-* Modified (date)
+ param: $relatives Relativity array
-* Size (bytes)
+ result: boolean True/False
-* MIME type
-* Deleteable (Y/N/Other?)
+ function rm ($string, $relatives = array (RELATIVE_CURRENT))
-* Comment
-* App (appname of application that created the file)
-* Directory (directory the file or directory is in)
+ 55..2211.. ddeelleettee
-* Name (name of file or directory)
+ abstract: shortcut to rm
-The internal names of these (the database column names) are stored
-in the $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 delete from the
-database. If a file is moved into the virtual root, some information,
-specifically MIME-type, is not 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.
+ function delete ($string, $relatives = array (RELATIVE_CURRENT))
-6.2 ACL support
-Because of the many different ways the VFS can be used, complete ACL
-support is not built in. There is a bit of access control built in,
-just because of the way database queries are made. However, that is
-a discussion beyond the scope of this document. Full ACL support may
-be added at a later time. For now, it is fairly easy to add basic
-access control to your application by matching path expressions. The
-VFS always follows the same naming convention of $fakebase/userorgroup.
-So if you need to check if a user has access to $fakebase/whatever/dir/file,
-you need only know if they their username is 'whatever' or if they
-belong to the group 'whatever', and that the group has access to your
-application. Here is an example from PHPWebHosting:
-###
+ 55..2222.. mmkkddiirr
-# First we get their memberships
+ abstract: make a new directory
-###
+ param: $dir Directory name
-$memberships = $phpgw->accounts->memberships ($account_id);
-###
+ param: $relatives Relativity array
-# We determine if they're in their home directory or a group's directory
+ result: boolean True on success
-# If they request a group's directory, we ensure they have access to
-the group,
-# and the group has access to the app
+ function mkdir ($dir, $relatives = array (RELATIVE_CURRENT))
-###
-if ((preg_match ("+^$fakebase\/(.*)(\/|$)+U", $path, $matches)) && $matches[1]
-!= $account_lid)
-{
+ 55..2233.. sseett__aattttrriibbuutteess
- $phpgw->vfs->working_id = $phpgw->accounts->name2id ($matches[1]);
+ abstract: Update database entry for $file with the attributes in
+ $attributes
- reset ($memberships);
+ param: $file file/directory to update
- while (list ($num, $group_array) = each ($memberships))
+ param: $relatives Relativity array
- {
+ param: $attributes keyed array of attributes. key is attribute name,
+ value is attribute value
- if ($matches[1] == $group_array["account_name"])
+ result: Boolean True/False
- {
+ discussion: Valid attributes are:
- $group_ok = 1;
+ owner_id
- break;
+ createdby_id
- }
+ modifiedby_id
- }
+ created
- if (!$group_ok)
+ modified
- {
+ size
- echo $phpgw->common->error_list (array ("You do not have
-access to group/directory $matches[1]"));
+ mime_type
- exit;
+ deleteable
- }
+ comment
-}
+ app
-You should also check if the group has access to your appilcation.
-6.3 Function aliases
+ function set_attributes ($file, $relatives = array (RELATIVE_CURRENT), $attributes = array ())
-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
+ 55..2244.. ccoorrrreecctt__aattttrriibbuutteess
-* delete -> rm
+ abstract: Set the correct attributes for $string (e.g. owner)
+
+ param: $string File/directory to correct attributes of
+
+ param: $relatives Relativity array
+
+ result: Boolean True/False
+
+
+ function correct_attributes ($string, $relatives = array (RELATIVE_CURRENT))
+
+
+
+ 55..2255.. ffiillee__ttyyppee
+
+ abstract: return file/dir type (MIME or other)
+
+ param: $file File or directory path (/home/user/dir/dir2/dir3,
+ /home/user/dir/dir2/file)
+
+ param: $relatives Relativity array
+
+ result: MIME type, "Directory", or nothing if MIME type is not known
+
+
+ function file_type ($file, $relatives = array (RELATIVE_CURRENT))
+
+
+
+ 55..2266.. ffiillee__eexxiissttss
+
+ abstract: check if file/directory exists
+
+ param: $string file/directory to check existance of
+
+ param: $relatives Relativity array
+
+ result: Boolean True/False
+
+
+ function file_exists ($string, $relatives = array (RELATIVE_CURRENT))
+
+
+
+ 55..2277.. cchheecckkppeerrmmss
+
+ abstract: Check if you have write access to create files in $dir
+
+ discussion: This isn't perfect, because vfs->touch () returns True
+ even
+
+ if only the database entry worked. ACLs need to be
+
+ implemented for better permission checking. It's
+
+ also pretty slow, so I wouldn't recommend using it
+
+ often
+
+ param: $dir Directory to check access of
+
+ param: $relatives Relativity array
+
+ result: Boolean True/False
+
+
+ function checkperms ($dir, $relatives = array (RELATIVE_CURRENT))
+
+
+
+ 55..2288.. llss
+
+ abstract: get directory listing
+
+ discussion: Note: the entries are not guaranteed to be returned in any
+ logical order
+
+ param: $dir Directory
+
+ param: $relatives Relativity array
+
+ param: $checksubdirs Boolean, recursively list all sub directories as
+ well?
+
+ param: $mime_type Only return entries matching MIME-type $mime_type.
+ Can be "Directory" or "\" for those without MIME types
+
+ param: $nofiles Boolean. True means you want to return just the
+ information about the directory $dir. If $dir is a file, $nofiles is
+ implied. This is the equivalent of 'ls -ld $dir'
+
+ result: array of arrays. Subarrays contain full info for each
+ file/dir.
+
+
+ function ls ($dir = False, $relatives = array (RELATIVE_CURRENT), $checksubdirs = True, $mime_type = False, $nofiles = False)
+
+
+
+ 55..2299.. ddiirr
+
+ abstract: shortcut to ls
+
+
+ function dir ($dir = False, $relatives = array (RELATIVE_CURRENT), $checksubdirs = True, $mime_type = False, $nofiles = False)
+
+
+
+ 66.. NNootteess
+
+ 66..11.. DDaattaabbaassee
+
+ Data about the files and directories within the virtual root is kept
+ in the SQL database. Currently, this information includes:
+
+
+ +o File ID (used internally, primary key for table)
+
+ +o Owner ID (phpGW account_id)
+
+ +o Created by ID (phpGW account_id)
+
+ +o Modified by ID (phpGW account_id)
+
+ +o Created (date)
+
+ +o Modified (date)
+
+ +o Size (bytes)
+
+ +o MIME type
+
+ +o Deleteable (Y/N/Other?)
+
+ +o Comment
+
+ +o App (appname of application that created the file)
+
+ +o Directory (directory the file or directory is in)
+
+ +o Name (name of file or directory)
+
+ The internal names of these (the database column names) are stored in
+ the $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 delete from the
+ database. If a file is moved into the virtual root, some information,
+ specifically MIME-type, is not 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.
+
+ 66..22.. AACCLL ssuuppppoorrtt
+
+ Because of the many different ways the VFS can be used, complete ACL
+ support is not built in. There is a bit of access control built in,
+ just because of the way database queries are made. However, that is a
+ discussion beyond the scope of this document. Full ACL support may be
+ added at a later time. For now, it is fairly easy to add basic access
+ control to your application by matching path expressions. The VFS
+ always follows the same naming convention of $fakebase/userorgroup.
+ So if you need to check if a user has access to
+ $fakebase/whatever/dir/file, you need only know if they their username
+ is 'whatever' or if they belong to the group 'whatever', and that the
+ group has access to your application. Here is an example from
+ PHPWebHosting:
+
+
+ ###
+ # First we get their memberships
+ ###
+
+ $memberships = $phpgw->accounts->memberships ($account_id);
+
+ ###
+ # We determine if they're in their home directory or a group's directory
+ # If they request a group's directory, we ensure they have access to the group,
+ # and the group has access to the app
+ ###
+
+ if ((preg_match ("+^$fakebase\/(.*)(\/|$)+U", $path, $matches)) && $matches[1] != $account_lid)
+ {
+ $phpgw->vfs->working_id = $phpgw->accounts->name2id ($matches[1]);
+ reset ($memberships);
+ while (list ($num, $group_array) = each ($memberships))
+ {
+ if ($matches[1] == $group_array["account_name"])
+ {
+ $group_ok = 1;
+ break;
+ }
+ }
+ if (!$group_ok)
+ {
+ echo $phpgw->common->error_list (array ("You do not have access to group/directory $matches[1]"));
+ exit;
+ }
+ }
+
+
+
+ You should also check if the group has access to your appilcation.
+
+ 66..33.. FFuunnccttiioonn aalliiaasseess
+
+ 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):
+
+
+ +o copy -> cp
+
+ +o move -> rm
+
+ +o delete -> rm
+
+ +o dir -> ls
+
+ 66..44.. FFaakkeebbaassee ddiirreeccttoorryy ((cchhaannggiinngg //hhoommee))
+
+ 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
+ $phpgw->vfs->fakebase, and changing it will transparently change it
+ throughout the VFS and all applications. However, this must be done
+ _b_e_f_o_r_e 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. _A_p_p_l_i_c_a_t_i_o_n _p_r_o_g_r_a_m_m_e_r_s _n_e_e_d _t_o
+ _r_e_c_o_g_n_i_z_e _t_h_a_t _/_h_o_m_e _i_s _n_o_t _a_b_s_o_l_u_t_e_, _a_n_d _u_s_e _$_p_h_p_g_w_-_>_v_f_s_-_>_f_a_k_e_b_a_s_e
+ _i_n_s_t_e_a_d. I suggest setting $fakebase = $phpgw->vfs->fakebase; right
+ off the bat to keep things neater.
+
+ 77.. AAbboouutt tthhiiss DDooccuummeenntt
+
+ 77..11.. CCooppyyrriigghhtt aanndd LLiicceennssee
+
+ Copyright (c) 2001 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
+ .
+
+ 77..22.. HHiissttoorryy
+
+ Original document released in June 2001 by Jason Wies.
+
+ 77..33.. CCoonnttrriibbuuttiinngg
+
+ Contributions are always welcome. Please send to the current
+ maintainer, Jason Wies, zone@users.sourceforge.net
+ .
-* 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 $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 $phpgw->vfs->fakebase instead. I suggest setting
-$fakebase = $phpgw->vfs->fakebase; right off the bat to keep things
-neater.
diff --git a/phpgwapi/doc/vfs/vfs_functions.lyx b/phpgwapi/doc/vfs/vfs_functions.lyx
index 1640374db9..e3c37f37cd 100644
--- a/phpgwapi/doc/vfs/vfs_functions.lyx
+++ b/phpgwapi/doc/vfs/vfs_functions.lyx
@@ -23,7 +23,7 @@
\layout Title
\added_space_top vfill \added_space_bottom vfill
-VFS class functions
+phpgwapi - VFS class
\layout Author
Jason Wies
@@ -38,7 +38,7 @@ June 2001
\layout Section
-VFS class functions
+phpgwapi - VFS class
\layout Subsection
class vfs
diff --git a/phpgwapi/doc/vfs/vfs_functions.sgml b/phpgwapi/doc/vfs/vfs_functions.sgml
index 9c113ddc50..55fa430220 100644
--- a/phpgwapi/doc/vfs/vfs_functions.sgml
+++ b/phpgwapi/doc/vfs/vfs_functions.sgml
@@ -3,7 +3,7 @@
-VFS class functions
+phpgwapi - VFS class
Jason Wies
@@ -15,7 +15,7 @@ June 2001
-VFS class functions
+phpgwapi - VFS class
class vfs