vfs.lyx

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

#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 218
\textclass linuxdoc
\language english
\inputencoding latin1
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 5
\tocdepth 5
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title
\added_space_top vfill \added_space_bottom vfill 
phpgwapi - VFS Class
\layout Author

Jason Wies
\layout Date

June 2001, February 2002
\layout Abstract

The VFS, or Virtual File System, handles all file system activity for phpGroupWa
re.
\layout Section

Introduction and Purpose
\begin_inset LatexCommand \label{sec:introduction}

\end_inset 


\layout Standard

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.
\layout Section

Basics
\begin_inset LatexCommand \label{sec:basics}

\end_inset 


\layout Subsection

Prerequisites
\begin_inset LatexCommand \label{sec:prerequisites}

\end_inset 


\layout Standard

You must explicitly enable the VFS class.
 To do this, set 'enable_vfs_class' to True in $GLOBALS['phpgw_info']['flags'].
 An example:
\layout Verbatim

$GLOBALS['phpgw_info']['flags'] = array(
\layout Verbatim

     'currentapp' => 'phpwebhosting',
\layout Verbatim

     'noheader' => False,
\layout Verbatim

     'noappheader' => False,
\layout Verbatim

     'enable_vfs_class' => True,
\layout Verbatim

     'enable_browser_class' => True
\layout Verbatim

);
\layout Subsection

Concepts
\begin_inset LatexCommand \label{sec:concepts}

\end_inset 


\layout Standard

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:
\layout Itemize

Files and directories are synonymous in almost all cases
\layout Verbatim

$GLOBALS['phpgw']->vfs->mv (array(
\layout Verbatim

     'from' => 'file1',
\layout Verbatim

     'to' => 'dir/file2'
\layout Verbatim

));
\layout Verbatim

\layout Verbatim

$GLOBALS['phpgw']->vfs->mv (array(
\layout Verbatim

     'from' => 'dir1',
\layout Verbatim

     'to' => 'dir/dir1'
\layout Verbatim

));
\layout Verbatim

\layout Verbatim

$GLOBALS['phpgw']->vfs->rm (array(
\layout Verbatim

     'string' => 'file'
\layout Verbatim

));
\layout Verbatim

\layout Verbatim

$GLOBALS['phpgw']->vfs->rm (array(
\layout Verbatim

     'string' => 'dir'
\layout Verbatim

));
\layout Standard

All work as you would except them to.
 The major exception is:
\layout Verbatim

$GLOBALS['phpgw']->vfs->touch (array(
\layout Verbatim

     'string' => 'file'
\layout Verbatim

));
\layout Standard

vs.
\layout Verbatim

$GLOBALS['phpgw']->vfs->mkdir (array(
\layout Verbatim

     'string' => 'dir'
\layout Verbatim

));
\layout Verbatim

\layout Itemize

Users and groups are synonymous
\layout Standard

As far as the actual paths are concerned, users and groups are the same.
 /home/username works the same as /home/groupname.
\layout Itemize

You should never have to know the real paths of files
\layout Standard

One of the VFS's responsibilities is to translate paths for you.
 While you certainly 
\emph on 
can
\emph default 
 operate using full paths, it is much simpler to use the virtual paths.
 For example, instead of using:
\layout Verbatim

$GLOBALS['phpgw']->vfs->cp (array(
\layout Verbatim

     'from' => '/var/www/egroupware/files/home/user/file1',
\layout Verbatim

     'to' => '/var/www/egroupware/files/home/user/file2',
\layout Verbatim

     'relatives' => array(
\layout Verbatim

          RELATIVE_NONE|VFS_REAL,
\layout Verbatim

          RELATIVE_NONE|VFS_REAL
\layout Verbatim

     )
\layout Verbatim

));
\layout Standard

you might use
\layout Verbatim

$GLOBALS['phpgw']->vfs->cp (array(
\layout Verbatim

     'from' => '/home/user/file1',
\layout Verbatim

     'to' => '/home/user/file2',
\layout Verbatim

     'relatives' => array(
\layout Verbatim

          RELATIVE_NONE,
\layout Verbatim

          RELATIVE_NONE
\layout Verbatim

     )
\layout Verbatim

));
\layout Standard

(We'll get to the RELATIVE's in a minute.)
\layout Standard

Site administrators should be able to move their files dir around on their
 system and know that everything will continue to work smoothly.
\layout Itemize

Relativity is 
\emph on 
vital
\layout Standard

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.
\layout Section

Basic Functions
\begin_inset LatexCommand \label{sec:basic_functions}

\end_inset 


\layout Standard

These are two functions you'll need to know before we get into relativity.
\layout Subsection

path_parts ()
\begin_inset LatexCommand \label{sec:path_parts}

\end_inset 


\layout Standard

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:
\layout Verbatim

string
\layout Verbatim

relatives
\layout Verbatim

object
\layout Standard

'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:
\layout Verbatim

fake_full_path
\layout Verbatim

fake_leading_dirs
\layout Verbatim

fake_extra_path
\layout Verbatim

fake_name
\layout Verbatim

real_full_path
\layout Verbatim

real_leading_dirs
\layout Verbatim

real_extra_path
\layout Verbatim

real_name
\layout Standard

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 
\begin_inset Quotes eld
\end_inset 

home
\begin_inset Quotes erd
\end_inset 

 to the end of the leading_dirs.
 To better illustrate, here is an example:
\layout Verbatim

$p = $GLOBALS['phpgw']->vfs->path_parts (array(
\layout Verbatim

     'string' => '/home/jason/dir/file',
\layout Verbatim

     'relatives' => array(
\layout Verbatim

         RELATIVE_NONE
\layout Verbatim

     )
\layout Verbatim

));
\layout Itemize

$p->fake_full_path - /home/jason/dir/file
\layout Itemize

$p->fake_leading_dirs - /home/jason/dir
\layout Itemize

$p->fake_extra_path - home/jason/dir
\layout Itemize

$p->fake_name - file
\layout Itemize

$p->real_full_path - /var/www/egroupware/files/home/jason/dir/file
\layout Itemize

$p->real_leading_dirs - /var/www/egroupware/files/home/jason/dir 
\layout Itemize

$p->real_extra_path - home/jason/dir
\layout Itemize

$p->real_name - file
\layout Standard

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 
\emph on 
getabsolutepath () is depreciated
\emph default 
.
 getabsolutepath () still exists (albeit in a much different form), and
 is responsible for some of the path translation, but it is an 
\emph on 
internal
\emph default 
 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.
\layout Subsection

cd ()
\begin_inset LatexCommand \label{sec:cd}

\end_inset 


\layout Standard

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: 
\layout Verbatim

/* cd to their home directory */
\layout Verbatim

$GLOBALS['phpgw']->vfs->cd (array(
\layout Verbatim

     'string' => '/'
\layout Verbatim

));
\layout Verbatim

\layout Verbatim

/* cd to /home/jason/dir */
\layout Verbatim

$GLOBALS['phpgw']->vfs->cd (array(
\layout Verbatim

     'string' => '/home/jason/dir',
\layout Verbatim

     'relative' => False,
\layout Verbatim

     'relatives' => array(
\layout Verbatim

          RELATIVE_NONE
\layout Verbatim

     )
\layout Verbatim

));
\layout Verbatim

\layout Verbatim

/* When following the above, cd's to /home/jason/dir/dir2 */
\layout Verbatim

$GLOBALS['phpgw']->vfs->cd (array(
\layout Verbatim

     'string' => 'dir2',
\layout Verbatim

     'relative' => True
\layout Verbatim

));
\layout Standard

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
 ().
\layout Standard

Now you're ready for relativity.
\layout Section

Relativity
\begin_inset LatexCommand \label{sec:relativity}

\end_inset 


\layout Standard

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 
\begin_inset LatexCommand \ref[Fakebase directory (changing /home)]{sec:fakebase}

\end_inset 

 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.
 
\emph on 
You should always use $fakebase when making applications.
 
\emph default 
I suggest doing $fakebase = $GLOBALS['phpgw']->vfs->fakebase; right off
 the bat to keep things neater.
\layout Subsection

What is it and how does it work?
\layout Standard

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.
 
\layout Verbatim

$GLOBALS['phpgw']->vfs->mv (array(
\layout Verbatim

    'from' => 'logo.png',
\layout Verbatim

    'to' => 'logo.png',
\layout Verbatim

    'relatives' => array(