[Sommaire] [Imprimer]

   1  
   2  Next Previous Contents
   3  ===============================================================================
   4  *****  1. Introduction_and_Purpose *****
   5  The latest version of the VFS for eGoupWare combines actual file system
   6  manipulation with fully integrated database support. It features nearly
   7  transparent handling of files and directories, as well as files inside and
   8  outside the virtual root. This document is intended to provide API and
   9  application developers with a guide to incorporating the VFS into their work.
  10  ===============================================================================
  11  Next Previous Contents
  12  
  13  
  14  Next Previous Contents
  15  ===============================================================================
  16  *****  2. Basics *****
  17  *****  2.1 Prerequisites *****
  18  You must explicitly enable the VFS class. To do this, set 'enable_vfs_class' to
  19  True in $GLOBALS['phpgw_info']['flags']. An example:
  20  $GLOBALS['phpgw_info']['flags'] = array(
  21       'currentapp' => 'phpwebhosting',
  22       'noheader' => False,
  23       'noappheader' => False,
  24       'enable_vfs_class' => True,
  25       'enable_browser_class' => True
  26  );
  27  *****  2.2 Concepts *****
  28  The VFS in located in phpgwapi/inc/class.vfs_sql.inc.php. You can look over it,
  29  but I don't suggest trying to understand how it works. It isn't necessary to
  30  know its internals to use it, but you may find the inline comments helpful. The
  31  basic things to keep in mind:
  32      * Files and directories are synonymous in almost all cases
  33  $GLOBALS['phpgw']->vfs->mv (array(
  34       'from' => 'file1',
  35       'to' => 'dir/file2'
  36  ));
  37  
  38  $GLOBALS['phpgw']->vfs->mv (array(
  39       'from' => 'dir1',
  40       'to' => 'dir/dir1'
  41  ));
  42  
  43  $GLOBALS['phpgw']->vfs->rm (array(
  44       'string' => 'file'
  45  ));
  46  
  47  $GLOBALS['phpgw']->vfs->rm (array(
  48       'string' => 'dir'
  49  ));
  50  All work as you would except them to. The major exception is:
  51  $GLOBALS['phpgw']->vfs->touch (array(
  52       'string' => 'file'
  53  ));
  54  vs.
  55  $GLOBALS['phpgw']->vfs->mkdir (array(
  56       'string' => 'dir'
  57  ));
  58      * Users and groups are synonymous
  59  As far as the actual paths are concerned, users and groups are the same. /home/
  60  username works the same as /home/groupname.
  61      * You should never have to know the real paths of files
  62  One of the VFS's responsibilities is to translate paths for you. While you
  63  certainly can operate using full paths, it is much simpler to use the virtual
  64  paths. For example, instead of using:
  65  $GLOBALS['phpgw']->vfs->cp (array(
  66       'from' => '/var/www/egroupware/files/home/user/file1',
  67       'to' => '/var/www/egroupware/files/home/user/file2',
  68       'relatives' => array(
  69            RELATIVE_NONE|VFS_REAL,
  70            RELATIVE_NONE|VFS_REAL
  71       )
  72  ));
  73  you might use
  74  $GLOBALS['phpgw']->vfs->cp (array(
  75       'from' => '/home/user/file1',
  76       'to' => '/home/user/file2',
  77       'relatives' => array(
  78            RELATIVE_NONE,
  79            RELATIVE_NONE
  80       )
  81  ));
  82  (We'll get to the RELATIVE's in a minute.)
  83  Site administrators should be able to move their files dir around on their
  84  system and know that everything will continue to work smoothly.
  85      * Relativity is vital
  86  Relativity is a new feature in the VFS, and its importance cannot be stressed
  87  enough. It will make your life much easier, especially for file system
  88  intensive applications, but it will take some getting used to. If something
  89  doesn't work right the first time, chances are great it has to do with
  90  incorrect relativity settings. We will deal with relativity in depth in the
  91  Relativity section.
  92  ===============================================================================
  93  Next Previous Contents
  94  
  95  
  96  Next Previous Contents
  97  ===============================================================================
  98  *****  3. Basic_Functions *****
  99  These are two functions you'll need to know before we get into relativity.
 100  *****  3.1 path_parts_() *****
 101  The job of path_parts () is to translate any given file location into its many
 102  component parts for any relativity. The values passed to path_parts () are:
 103  string
 104  relatives
 105  object
 106  'string' is the path you want to translate, 'relatives' is the standard
 107  relativity array, and 'object' specifies how you would like the return value:
 108  if 'object' is True, an object will be returned; if 'object' is False, an array
 109  will be returned. I think you'll find the object easier to deal with, and we'll
 110  be using it throughout this document. The most important returned values (but
 111  not all) for path_parts () are:
 112  fake_full_path
 113  fake_leading_dirs
 114  fake_extra_path
 115  fake_name
 116  real_full_path
 117  real_leading_dirs
 118  real_extra_path
 119  real_name
 120  Just like you would think, fake_full_path contains the full virtual path of
 121  'string', and real_full_path contains the full real path of 'string'. The
 122  fake_name and real_name variables should always be the same, and contain the
 123  final file or directory name. The leading_dirs contain everything except the
 124  name, and the extra_path is everything from the / before "home" to the end of
 125  the leading_dirs. To better illustrate, here is an example:
 126  $p = $GLOBALS['phpgw']->vfs->path_parts (array(
 127       'string' => '/home/jason/dir/file',
 128       'relatives' => array(
 129           RELATIVE_NONE
 130       )
 131  ));
 132      * $p->fake_full_path - /home/jason/dir/file
 133      * $p->fake_leading_dirs - /home/jason/dir
 134      * $p->fake_extra_path - home/jason/dir
 135      * $p->fake_name - file
 136      * $p->real_full_path - /var/www/egroupware/files/home/jason/dir/file
 137      * $p->real_leading_dirs - /var/www/egroupware/files/home/jason/dir
 138      * $p->real_extra_path - home/jason/dir
 139      * $p->real_name - file
 140  As you can see, path_parts () is a very useful function and will save you from
 141  doing those darn substr ()'s yourself. For those of you used to the prior VFS,
 142  note that getabsolutepath () is depreciated. getabsolutepath () still exists
 143  (albeit in a much different form), and is responsible for some of the path
 144  translation, but it is an internal function only. Applications should only use
 145  path_parts (). We have shown you how to use path_parts () so you can experiment
 146  with it using different paths and relativities as we explore relativity.
 147  *****  3.2 cd_() *****
 148  Part of the overall goal for the VFS in eGoupWare is to give the user a
 149  seamless experience during their session. For example, if they upload a file
 150  using a file manager to the directory /home/my_group/project1, and then go to
 151  download an email attachment, the default directory will be /home/my_group/
 152  project1. This is accomplished using the cd () function. Examples:
 153  /* cd to their home directory */
 154  $GLOBALS['phpgw']->vfs->cd (array(
 155       'string' => '/'
 156  ));
 157  
 158  /* cd to /home/jason/dir */
 159  $GLOBALS['phpgw']->vfs->cd (array(
 160       'string' => '/home/jason/dir',
 161       'relative' => False,
 162       'relatives' => array(
 163            RELATIVE_NONE
 164       )
 165  ));
 166  
 167  /* When following the above, cd's to /home/jason/dir/dir2 */
 168  $GLOBALS['phpgw']->vfs->cd (array(
 169       'string' => 'dir2',
 170       'relative' => True
 171  ));
 172  If 'relative' is True, the 'string' is simply appended to the current path. If
 173  you want to know what the current path is, use $GLOBALS['phpgw']->vfs->pwd ().
 174  Now you're ready for relativity.
 175  ===============================================================================
 176  Next Previous Contents
 177  
 178  
 179  Next Previous Contents
 180  ===============================================================================
 181  *****  4. Relativity *****
 182  Ok, just one last thing before we get into relativity. You will notice
 183  throughout the examples the use of $fakebase. $GLOBALS['phpgw']->vfs->fakebase
 184  is by default '/home'. The old VFS was hard-coded to use '/home', but the
 185  naming choice for this is now up to administrators. See the Fakebase_directory_
 186  (changing_/home) section for more information. Throughout the rest of this
 187  document, you will see $fakebase used in calls to the VFS, and /home used in
 188  actual paths. You should always use $fakebase when making applications.I
 189  suggest doing $fakebase = $GLOBALS['phpgw']->vfs->fakebase; right off the bat
 190  to keep things neater.
 191  ***** 4.1 What_is_it_and_how_does_it_work? *****
 192  One of the design challenges for a Virtual File System is to try to figure out
 193  whether the calling application is referring to a file inside or outside the
 194  virtual root, and if inside, exactly where. To solve this problem, the
 195  eGoupWare VFS uses RELATIVE defines that are used in bitmasks passed to each
 196  function. The result is that any set of different relativities can be used in
 197  combination with each other. Let's look at a few examples. Say you want to move
 198  'logo.png' from the user's home directory to the current directory.
 199  $GLOBALS['phpgw']->vfs->mv (array(
 200      'from' => 'logo.png',
 201      'to' => 'logo.png',
 202      'relatives' => array(
 203            RELATIVE_USER,
 204            RELATIVE_ALL
 205       )
 206  ));
 207  RELATIVE_USER means relative to the user's home directory. RELATIVE_ALL means
 208  relative to the current directory, as set by cd () and as reported by pwd ().
 209  So if the current directory was "$fakebase/my_group/project1", the call to mv
 210  () would be processed as:
 211  MOVE "$fakebase/jason/logo.png" TO "$fakebase/my_group/project1/logo.png"
 212  and the actual file system call would be:
 213  rename ('/var/www/egroupware/files/home/jason/logo.php', '/var/www/
 214  egroupware/files/home/my_group/project1/logo.png');
 215  Those used to the old VFS will note that you do not have to translate the path
 216  beforehand. Let's look at another example. Suppose you were moving an email
 217  attachment stored in eGoupWare's temporary directory to the 'attachments'
 218  directory within the user's home directory (we're assuming the attachments
 219  directory exists). Note that the temporary directory is outside the virtual
 220  root.
 221  $GLOBALS['phpgw']->vfs->mv (array(
 222       'from' => $GLOBALS['phpgw_info']['server']['temp_dir'] . '/' . $randomdir
 223  . '/' . $randomfile,
 224       'to' => 'attachments/actual_name.ext',
 225       'relatives' => array(
 226            RELATIVE_NONE|VFS_REAL,
 227            RELATIVE_USER
 228       )
 229  ));
 230  $randomdir and $randomfile are what the directory and file might be called
 231  before they are given a proper name by the user, which is actual_name.ext in
 232  this example. RELATIVE_NONE is the define for using full path names. However,
 233  RELATIVE_NONE is still relative to the virtual root, so we pass along VFS_REAL
 234  as well, to say that the file is outside the virtual root, somewhere else in
 235  the file system. Once again, RELATIVE_USER means relative to the user's home
 236  directory. So the actual file system call might look like this (keep in mind
 237  that $randomdir and $randomfile are just random strings):
 238  rename ('/var/www/egroupware/tmp/0ak5adftgh7/jX42sC9M', '/var/www/
 239  egroupware/files/home/jason/attachments/actual_name.ext');
 240  Of course you don't have to know that, nor should you be concerned with it; you
 241  can take it for granted that the VFS will translate the paths correctly. Let's
 242  take a look at one more example, this time using the RELATIVE_USER_APP define.
 243  RELATIVE_USER_APP is used to store quasi-hidden application files, similar to
 244  the Unix convention of ~/.appname. It simply appends .appname to the user's
 245  home directory. For example, if you were making an HTML editor application
 246  named 'htmledit', and wanted to keep a backup file in case something goes
 247  wrong, you could use RELATIVE_USER_APP to store it:
 248  $GLOBALS['phpgw']->vfs->write (array(
 249       'string' => 'file.name~',
 250       'relatives' => array(
 251            RELATIVE_USER_APP
 252       ),
 253       'content' => $contents
 254  ));
 255  This assumes that ~/.htmledit exists of course. The backup file "file.name~"
 256  would then be written in $fakebase/jason/.htmledit/file.name~. Note that
 257  storing files like this might not be as good of a solution as storing them in
 258  the temporary directory or in the database. But it is there in case you need
 259  it.
 260  *****  4.2 Complete_List *****
 261  Here is the complete list of RELATIVE defines, and what they do:
 262    RELATIVE_ROOT
 263        Don't translate the path at all. Just prepends a /. You'll probably want
 264        to use RELATIVE_NONE though, which handles both virtual and real files.
 265    RELATIVE_USER
 266        User's home directory
 267    RELATIVE_CURR_USER
 268        Current user's home directory. If the current directory is $fakebase/
 269        my_group/project1, this will return is $fakebase/my_group
 270    RELATIVE_USER_APP
 271        Append .appname to the user's home directory, where appname is the
 272        current application's appname
 273    RELATIVE_PATH
 274        DO NOT USE. Relative to the current directory, used in RELATIVE_ALL
 275    RELATIVE_NONE
 276        Not relative to anything. Use this with VFS_REAL for files outside the
 277        virtual root. Note that using RELATIVE_NONE by itself still means
 278        relative to the virtual root
 279    RELATIVE_CURRENT
 280        An alias for the currently set RELATIVE define, or RELATIVE_ALL if none
 281        is set (see the Defaults section)
 282    VFS_REAL
 283        File is outside of the virtual root. Usually used with RELATIVE_NONE
 284    RELATIVE_ALL
 285        Relative to the current directory. Use RELATIVE_ALLinstead of
 286        RELATIVE_PATH
 287  *****  4.3 Defaults *****
 288  You might be thinking to yourself that passing along RELATIVE defines with
 289  every VFS call is overkill, especially if your application always uses the same
 290  relativity. The default RELATIVE define for all VFS calls is RELATIVE_CURRENT.
 291  RELATIVE_CURRENT itself defaults to RELATIVE_ALL (relative to the current
 292  path), unless your application sets a specific relativity. If your application
 293  requires most of the work to be done outside of the virtual root, you may wish
 294  to set RELATIVE_CURRENT to RELATIVE_NONE|VFS_REAL. set_relative () is the
 295  function to do this. For example:
 296  $GLOBALS['phpgw']->vfs->set_relative (array(
 297       'mask' => RELATIVE_NONE|VFS_REAL
 298  ));
 299  
 300  $GLOBALS['phpgw']->vfs->read (array(
 301       'string' => '/etc/passwd'
 302  ));
 303  
 304  $GLOBALS['phpgw']->vfs->cp (array(
 305       'from' => '/usr/include/stdio.h',
 306       'to' => '/tmp/stdio.h'
 307  ));
 308  
 309  $GLOBALS['phpgw']->vfs->cp (array(
 310       'from' => '/usr/share/pixmaps/yes.xpm',
 311       'to' => 'icons/yes.xpm',
 312       'relatives' => array(
 313            RELATIVE_CURRENT,
 314            RELATIVE_USER
 315       )
 316  ));
 317  You should notice that no relativity array is needed in the other calls that
 318  refer to files outside the virtual root, but one is needed for calls that
 319  include files inside the virtual root. Any RELATIVE define can be set as the
 320  default and works in the same fashion. To retrieve the currently set define,
 321  use get_relative (). Note that the relativity is reset after each page request;
 322  that is, it's good only for the life of the current page loading, and is not
 323  stored in session management.
 324  ===============================================================================
 325  Next Previous Contents
 326  
 327  
 328  Next Previous Contents
 329  ===============================================================================
 330  *****  5. Function_reference *****
 331  To view the function reference for the VFS, use the doc/inlinedocparser.php
 332  script that comes with eGoupWare, ie http://localhost/doc/
 333  inlinedocparser.php?fn=class.vfs_sql.inc.php.
 334  ===============================================================================
 335  Next Previous Contents
 336  
 337  
 338  Next Previous Contents
 339  ===============================================================================
 340  *****  6. Notes *****
 341  *****  6.1 Database *****
 342  Data about the files and directories within the virtual root is kept in the SQL
 343  database. Currently, this information includes:
 344      * File ID (used internally, primary key for table)
 345      * Owner ID (phpGW account_id)
 346      * Created by ID (phpGW account_id)
 347      * Modified by ID (phpGW account_id)
 348      * Created (date)
 349      * Modified (date)
 350      * Size (bytes)
 351      * MIME type
 352      * Deleteable (Y/N/Other?)
 353      * Comment
 354      * App (appname of application that created the file)
 355      * Directory (directory the file or directory is in)
 356      * Name (name of file or directory)
 357      * Link directory (if the file or directory is linked, what the actual
 358        directory is)
 359      * Link name (if the file or directory is linked, what the actual name is)
 360      * Version (numeric version of the file)
 361  The internal names of these (the database column names) are stored in the
 362  $GLOBALS['phpgw']->vfs->attributes array, which is useful for loops, and is
 363  guaranteed to be up-to-date.
 364  Note that no information is kept about files outside the virtual root. If a
 365  file is moved outside, all records of it are deleted from the database (other
 366  than the journaling records). If a file is moved into the virtual root, some
 367  information, specifically MIME-type, is not always stored in the database. The
 368  vital information has defaults: owner is based on where the file is being
 369  stored; size is correctly read; deleteable is set to Y.
 370  *****  6.2 ACL_support *****
 371  ACL support is built into the VFS. vfs->acl_check () does the actual checking,
 372  and is called from all VFS functions as needed. If the file or directory sent
 373  to acl_check () doesn't exist, the permissions for the parent directory are
 374  used to determine access. ACL checking can be overridden at any time by setting
 375  vfs->override_acl. For example:
 376  $GLOBALS['phpgw']->vfs->override_acl = 1;
 377  $GLOBALS['phpgw']->vfs->mkdir (array(
 378       'string' => $GLOBALS['fakebase']. '/' . $group_array['account_name'],
 379       'relatives' => array(
 380            RELATIVE_NONE
 381       )
 382  ));
 383  $GLOBALS['phpgw']->vfs->override_acl = 0;
 384  *****  6.3 Function_aliases *****
 385  You might have noticed there are some functions that just pass the arguments on
 386  to other functions. These are provided in part because of legacy and in part
 387  for convenience. You can use either. Here is the list (alias -> actual):
 388      * copy -> cp
 389      * move -> rm
 390      * delete -> rm
 391      * dir -> ls
 392  *****  6.4 Fakebase_directory_(changing_/home) *****
 393  The old VFS was hard-coded to use '/home' as the fake base directory, even
 394  though the user never saw it. With the new system, crafty administrators may
 395  wish to change '/home' to something else, say '/users' or '/public_html'. The
 396  fake base directory name is stored in $GLOBALS['phpgw']->vfs->fakebase, and
 397  changing it will transparently change it throughout the VFS and all
 398  applications. However, this must be done before any data is in the VFS
 399  database. If you wish to change it afterwords, you'll have to manually update
 400  the database, replacing the old value with the new value. Application
 401  programmers need to recognize that /home is not absolute, and use $GLOBALS
 402  ['phpgw']->vfs->fakebase instead. I suggest setting $fakebase = $GLOBALS
 403  ['phpgw']->vfs->fakebase; right off the bat to keep things neater.
 404  ===============================================================================
 405  Next Previous Contents
 406  
 407  Next Previous Contents
 408  ===============================================================================
 409  ***** 7. About_this_Document *****
 410  ***** 7.1 Copyright_and_License *****
 411  Copyright (c) 2001, 2002 Jason Wies
 412  Permission is granted to copy, distribute and/or modify this document under the
 413  terms of the GNU Free Documentation License, Version 1.1 or any later version
 414  published by the Free Software Foundation; with no Invarient Sections, with no
 415  Front-Cover Texts, and no Back-Cover Texts.
 416  A copy of the license is available at http://www.gnu.org/copyleft/fdl.html.
 417  ***** 7.2 History *****
 418  Original document released in June 2001 by Jason Wies.
 419  Updated February 2002 to include arrayized parameters, single quotes, and
 420  GLOBALS.
 421  ***** 7.3 Contributing *****
 422  Contributions are always welcome. Please send to the current maintainer, Jason
 423  Wies, 
 424  ===============================================================================
 425  Next Previous Contents