[Sommaire] [Imprimer]

   1  #LyX 1.1 created this file. For more info see http://www.lyx.org/
   2  \lyxformat 218
   3  \textclass linuxdoc
   4  \language english
   5  \inputencoding latin1
   6  \fontscheme default
   7  \graphics default
   8  \paperfontsize default
   9  \spacing single 
  10  \papersize Default
  11  \paperpackage a4
  12  \use_geometry 0
  13  \use_amsmath 0
  14  \paperorientation portrait
  15  \secnumdepth 5
  16  \tocdepth 5
  17  \paragraph_separation indent
  18  \defskip medskip
  19  \quotes_language english
  20  \quotes_times 2
  21  \papercolumns 1
  22  \papersides 1
  23  \paperpagestyle default
  24  
  25  \layout Title
  26  \added_space_top vfill \added_space_bottom vfill 
  27  phpgwapi - VFS Class
  28  \layout Author
  29  
  30  Jason Wies
  31  \layout Date
  32  
  33  June 2001, February 2002
  34  \layout Abstract
  35  
  36  The VFS, or Virtual File System, handles all file system activity for phpGroupWa
  37  re.
  38  \layout Section
  39  
  40  Introduction and Purpose
  41  \begin_inset LatexCommand \label{sec:introduction}
  42  
  43  \end_inset 
  44  
  45  
  46  \layout Standard
  47  
  48  The latest version of the VFS for eGoupWare combines actual file system
  49   manipulation with fully integrated database support.
  50   It features nearly transparent handling of files and directories, as well
  51   as files inside and outside the virtual root.
  52   This document is intended to provide API and application developers with
  53   a guide to incorporating the VFS into their work.
  54  \layout Section
  55  
  56  Basics
  57  \begin_inset LatexCommand \label{sec:basics}
  58  
  59  \end_inset 
  60  
  61  
  62  \layout Subsection
  63  
  64  Prerequisites
  65  \begin_inset LatexCommand \label{sec:prerequisites}
  66  
  67  \end_inset 
  68  
  69  
  70  \layout Standard
  71  
  72  You must explicitly enable the VFS class.
  73   To do this, set 'enable_vfs_class' to True in $GLOBALS['phpgw_info']['flags'].
  74   An example:
  75  \layout Verbatim
  76  
  77  $GLOBALS['phpgw_info']['flags'] = array(
  78  \layout Verbatim
  79  
  80       'currentapp' => 'phpwebhosting',
  81  \layout Verbatim
  82  
  83       'noheader' => False,
  84  \layout Verbatim
  85  
  86       'noappheader' => False,
  87  \layout Verbatim
  88  
  89       'enable_vfs_class' => True,
  90  \layout Verbatim
  91  
  92       'enable_browser_class' => True
  93  \layout Verbatim
  94  
  95  );
  96  \layout Subsection
  97  
  98  Concepts
  99  \begin_inset LatexCommand \label{sec:concepts}
 100  
 101  \end_inset 
 102  
 103  
 104  \layout Standard
 105  
 106  The VFS in located in phpgwapi/inc/class.vfs_sql.inc.php.
 107   You can look over it, but I don't suggest trying to understand how it works.
 108   It isn't necessary to know its internals to use it, but you may find the
 109   inline comments helpful.
 110   The basic things to keep in mind:
 111  \layout Itemize
 112  
 113  Files and directories are synonymous in almost all cases
 114  \layout Verbatim
 115  
 116  $GLOBALS['phpgw']->vfs->mv (array(
 117  \layout Verbatim
 118  
 119       'from' => 'file1',
 120  \layout Verbatim
 121  
 122       'to' => 'dir/file2'
 123  \layout Verbatim
 124  
 125  ));
 126  \layout Verbatim
 127  
 128  \layout Verbatim
 129  
 130  $GLOBALS['phpgw']->vfs->mv (array(
 131  \layout Verbatim
 132  
 133       'from' => 'dir1',
 134  \layout Verbatim
 135  
 136       'to' => 'dir/dir1'
 137  \layout Verbatim
 138  
 139  ));
 140  \layout Verbatim
 141  
 142  \layout Verbatim
 143  
 144  $GLOBALS['phpgw']->vfs->rm (array(
 145  \layout Verbatim
 146  
 147       'string' => 'file'
 148  \layout Verbatim
 149  
 150  ));
 151  \layout Verbatim
 152  
 153  \layout Verbatim
 154  
 155  $GLOBALS['phpgw']->vfs->rm (array(
 156  \layout Verbatim
 157  
 158       'string' => 'dir'
 159  \layout Verbatim
 160  
 161  ));
 162  \layout Standard
 163  
 164  All work as you would except them to.
 165   The major exception is:
 166  \layout Verbatim
 167  
 168  $GLOBALS['phpgw']->vfs->touch (array(
 169  \layout Verbatim
 170  
 171       'string' => 'file'
 172  \layout Verbatim
 173  
 174  ));
 175  \layout Standard
 176  
 177  vs.
 178  \layout Verbatim
 179  
 180  $GLOBALS['phpgw']->vfs->mkdir (array(
 181  \layout Verbatim
 182  
 183       'string' => 'dir'
 184  \layout Verbatim
 185  
 186  ));
 187  \layout Verbatim
 188  
 189  \layout Itemize
 190  
 191  Users and groups are synonymous
 192  \layout Standard
 193  
 194  As far as the actual paths are concerned, users and groups are the same.
 195   /home/username works the same as /home/groupname.
 196  \layout Itemize
 197  
 198  You should never have to know the real paths of files
 199  \layout Standard
 200  
 201  One of the VFS's responsibilities is to translate paths for you.
 202   While you certainly 
 203  \emph on 
 204  can
 205  \emph default 
 206   operate using full paths, it is much simpler to use the virtual paths.
 207   For example, instead of using:
 208  \layout Verbatim
 209  
 210  $GLOBALS['phpgw']->vfs->cp (array(
 211  \layout Verbatim
 212  
 213       'from' => '/var/www/egroupware/files/home/user/file1',
 214  \layout Verbatim
 215  
 216       'to' => '/var/www/egroupware/files/home/user/file2',
 217  \layout Verbatim
 218  
 219       'relatives' => array(
 220  \layout Verbatim
 221  
 222            RELATIVE_NONE|VFS_REAL,
 223  \layout Verbatim
 224  
 225            RELATIVE_NONE|VFS_REAL
 226  \layout Verbatim
 227  
 228       )
 229  \layout Verbatim
 230  
 231  ));
 232  \layout Standard
 233  
 234  you might use
 235  \layout Verbatim
 236  
 237  $GLOBALS['phpgw']->vfs->cp (array(
 238  \layout Verbatim
 239  
 240       'from' => '/home/user/file1',
 241  \layout Verbatim
 242  
 243       'to' => '/home/user/file2',
 244  \layout Verbatim
 245  
 246       'relatives' => array(
 247  \layout Verbatim
 248  
 249            RELATIVE_NONE,
 250  \layout Verbatim
 251  
 252            RELATIVE_NONE
 253  \layout Verbatim
 254  
 255       )
 256  \layout Verbatim
 257  
 258  ));
 259  \layout Standard
 260  
 261  (We'll get to the RELATIVE's in a minute.)
 262  \layout Standard
 263  
 264  Site administrators should be able to move their files dir around on their
 265   system and know that everything will continue to work smoothly.
 266  \layout Itemize
 267  
 268  Relativity is 
 269  \emph on 
 270  vital
 271  \layout Standard
 272  
 273  Relativity is a new feature in the VFS, and its importance cannot be stressed
 274   enough.
 275   It will make your life much easier, especially for file system intensive
 276   applications, but it will take some getting used to.
 277   If something doesn't work right the first time, chances are great it has
 278   to do with incorrect relativity settings.
 279   We will deal with relativity in depth in the Relativity section.
 280  \layout Section
 281  
 282  Basic Functions
 283  \begin_inset LatexCommand \label{sec:basic_functions}
 284  
 285  \end_inset 
 286  
 287  
 288  \layout Standard
 289  
 290  These are two functions you'll need to know before we get into relativity.
 291  \layout Subsection
 292  
 293  path_parts ()
 294  \begin_inset LatexCommand \label{sec:path_parts}
 295  
 296  \end_inset 
 297  
 298  
 299  \layout Standard
 300  
 301  The job of path_parts () is to translate any given file location into its
 302   many component parts for any relativity.
 303   The values passed to path_parts () are:
 304  \layout Verbatim
 305  
 306  string
 307  \layout Verbatim
 308  
 309  relatives
 310  \layout Verbatim
 311  
 312  object
 313  \layout Standard
 314  
 315  'string' is the path you want to translate, 'relatives' is the standard
 316   relativity array, and 'object' specifies how you would like the return
 317   value: if 'object' is True, an object will be returned; if 'object' is
 318   False, an array will be returned.
 319   I think you'll find the object easier to deal with, and we'll be using
 320   it throughout this document.
 321   The most important returned values (but not all) for path_parts () are:
 322  \layout Verbatim
 323  
 324  fake_full_path
 325  \layout Verbatim
 326  
 327  fake_leading_dirs
 328  \layout Verbatim
 329  
 330  fake_extra_path
 331  \layout Verbatim
 332  
 333  fake_name
 334  \layout Verbatim
 335  
 336  real_full_path
 337  \layout Verbatim
 338  
 339  real_leading_dirs
 340  \layout Verbatim
 341  
 342  real_extra_path
 343  \layout Verbatim
 344  
 345  real_name
 346  \layout Standard
 347  
 348  Just like you would think, fake_full_path contains the full virtual path
 349   of 'string', and real_full_path contains the full real path of 'string'.
 350   The fake_name and real_name variables should always be the same, and contain
 351   the final file or directory name.
 352   The leading_dirs contain everything except the name, and the extra_path
 353   is everything from the / before 
 354  \begin_inset Quotes eld
 355  \end_inset 
 356  
 357  home
 358  \begin_inset Quotes erd
 359  \end_inset 
 360  
 361   to the end of the leading_dirs.
 362   To better illustrate, here is an example:
 363  \layout Verbatim
 364  
 365  $p = $GLOBALS['phpgw']->vfs->path_parts (array(
 366  \layout Verbatim
 367  
 368       'string' => '/home/jason/dir/file',
 369  \layout Verbatim
 370  
 371       'relatives' => array(
 372  \layout Verbatim
 373  
 374           RELATIVE_NONE
 375  \layout Verbatim
 376  
 377       )
 378  \layout Verbatim
 379  
 380  ));
 381  \layout Itemize
 382  
 383  $p->fake_full_path - /home/jason/dir/file
 384  \layout Itemize
 385  
 386  $p->fake_leading_dirs - /home/jason/dir
 387  \layout Itemize
 388  
 389  $p->fake_extra_path - home/jason/dir
 390  \layout Itemize
 391  
 392  $p->fake_name - file
 393  \layout Itemize
 394  
 395  $p->real_full_path - /var/www/egroupware/files/home/jason/dir/file
 396  \layout Itemize
 397  
 398  $p->real_leading_dirs - /var/www/egroupware/files/home/jason/dir 
 399  \layout Itemize
 400  
 401  $p->real_extra_path - home/jason/dir
 402  \layout Itemize
 403  
 404  $p->real_name - file
 405  \layout Standard
 406  
 407  As you can see, path_parts () is a very useful function and will save you
 408   from doing those darn substr ()'s yourself.
 409   For those of you used to the prior VFS, note that 
 410  \emph on 
 411  getabsolutepath () is depreciated
 412  \emph default 
 413  .
 414   getabsolutepath () still exists (albeit in a much different form), and
 415   is responsible for some of the path translation, but it is an 
 416  \emph on 
 417  internal
 418  \emph default 
 419   function only.
 420   Applications should only use path_parts ().
 421   We have shown you how to use path_parts () so you can experiment with it
 422   using different paths and relativities as we explore relativity.
 423  \layout Subsection
 424  
 425  cd ()
 426  \begin_inset LatexCommand \label{sec:cd}
 427  
 428  \end_inset 
 429  
 430  
 431  \layout Standard
 432  
 433  Part of the overall goal for the VFS in eGoupWare is to give the user
 434   a seamless experience during their session.
 435   For example, if they upload a file using a file manager to the directory
 436   /home/my_group/project1, and then go to download an email attachment, the
 437   default directory will be /home/my_group/project1.
 438   This is accomplished using the cd () function.
 439   Examples: 
 440  \layout Verbatim
 441  
 442  /* cd to their home directory */
 443  \layout Verbatim
 444  
 445  $GLOBALS['phpgw']->vfs->cd (array(
 446  \layout Verbatim
 447  
 448       'string' => '/'
 449  \layout Verbatim
 450  
 451  ));
 452  \layout Verbatim
 453  
 454  \layout Verbatim
 455  
 456  /* cd to /home/jason/dir */
 457  \layout Verbatim
 458  
 459  $GLOBALS['phpgw']->vfs->cd (array(
 460  \layout Verbatim
 461  
 462       'string' => '/home/jason/dir',
 463  \layout Verbatim
 464  
 465       'relative' => False,
 466  \layout Verbatim
 467  
 468       'relatives' => array(
 469  \layout Verbatim
 470  
 471            RELATIVE_NONE
 472  \layout Verbatim
 473  
 474       )
 475  \layout Verbatim
 476  
 477  ));
 478  \layout Verbatim
 479  
 480  \layout Verbatim
 481  
 482  /* When following the above, cd's to /home/jason/dir/dir2 */
 483  \layout Verbatim
 484  
 485  $GLOBALS['phpgw']->vfs->cd (array(
 486  \layout Verbatim
 487  
 488       'string' => 'dir2',
 489  \layout Verbatim
 490  
 491       'relative' => True
 492  \layout Verbatim
 493  
 494  ));
 495  \layout Standard
 496  
 497  If 'relative' is True, the 'string' is simply appended to the current path.
 498   If you want to know what the current path is, use $GLOBALS['phpgw']->vfs->pwd
 499   ().
 500  \layout Standard
 501  
 502  Now you're ready for relativity.
 503  \layout Section
 504  
 505  Relativity
 506  \begin_inset LatexCommand \label{sec:relativity}
 507  
 508  \end_inset 
 509  
 510  
 511  \layout Standard
 512  
 513  Ok, just one last thing before we get into relativity.
 514   You will notice throughout the examples the use of $fakebase.
 515   $GLOBALS['phpgw']->vfs->fakebase is by default '/home'.
 516   The old VFS was hard-coded to use '/home', but the naming choice for this
 517   is now up to administrators.
 518   See the 
 519  \begin_inset LatexCommand \ref[Fakebase directory (changing /home)]{sec:fakebase}
 520  
 521  \end_inset 
 522  
 523   section for more information.
 524   Throughout the rest of this document, you will see $fakebase used in calls
 525   to the VFS, and /home used in actual paths.
 526   
 527  \emph on 
 528  You should always use $fakebase when making applications.
 529   
 530  \emph default 
 531  I suggest doing $fakebase = $GLOBALS['phpgw']->vfs->fakebase; right off
 532   the bat to keep things neater.
 533  \layout Subsection
 534  
 535  What is it and how does it work?
 536  \layout Standard
 537  
 538  One of the design challenges for a Virtual File System is to try to figure
 539   out whether the calling application is referring to a file inside or outside
 540   the virtual root, and if inside, exactly where.
 541   To solve this problem, the eGoupWare VFS uses RELATIVE defines that
 542   are used in bitmasks passed to each function.
 543   The result is that any set of different relativities can be used in combination
 544   with each other.
 545   Let's look at a few examples.
 546   Say you want to move 'logo.png' from the user's home directory to the current
 547   directory.
 548   
 549  \layout Verbatim
 550  
 551  $GLOBALS['phpgw']->vfs->mv (array(
 552  \layout Verbatim
 553  
 554      'from' => 'logo.png',
 555  \layout Verbatim
 556  
 557      'to' => 'logo.png',
 558  \layout Verbatim
 559  
 560      'relatives' => array(
 561  \layout Verbatim
 562  
 563            RELATIVE_USER,
 564  \layout Verbatim
 565  
 566            RELATIVE_ALL
 567  \layout Verbatim
 568  
 569       )
 570  \layout Verbatim
 571  
 572  ));
 573  \layout Standard
 574  
 575  RELATIVE_USER means relative to the user's home directory.
 576   RELATIVE_ALL means relative to the current directory, as set by cd () and
 577   as reported by pwd ().
 578   So if the current directory was 
 579  \begin_inset Quotes eld
 580  \end_inset 
 581  
 582  $fakebase/my_group/project1
 583  \begin_inset Quotes erd
 584  \end_inset 
 585  
 586  , the call to mv () would be processed as:
 587  \layout Verbatim
 588  
 589  MOVE 
 590  \begin_inset Quotes eld
 591  \end_inset 
 592  
 593  $fakebase/jason/logo.png
 594  \begin_inset Quotes erd
 595  \end_inset 
 596  
 597   TO 
 598  \begin_inset Quotes eld
 599  \end_inset 
 600  
 601  $fakebase/my_group/project1/logo.png
 602  \begin_inset Quotes erd
 603  \end_inset 
 604  
 605  
 606  \layout Standard
 607  
 608  and the actual file system call would be:
 609  \layout Verbatim
 610  
 611  rename ('/var/www/egroupware/files/home/jason/logo.php', '/var/www/egroupware
 612  /files/home/my_group/project1/logo.png');
 613  \layout Standard
 614  
 615  Those used to the old VFS will note that you do not have to translate the
 616   path beforehand.
 617   Let's look at another example.
 618   Suppose you were moving an email attachment stored in eGoupWare's temporary
 619   directory to the 'attachments' directory within the user's home directory
 620   (we're assuming the attachments directory exists).
 621   Note that the temporary directory is 
 622  \emph on 
 623  outside
 624  \emph default 
 625   the virtual root.
 626  \layout Verbatim
 627  
 628  $GLOBALS['phpgw']->vfs->mv (array(
 629  \layout Verbatim
 630  
 631       'from' => $GLOBALS['phpgw_info']['server']['temp_dir'] .
 632   '/' .
 633   $randomdir .
 634   '/' .
 635   $randomfile,
 636  \layout Verbatim
 637  
 638       'to' => 'attachments/actual_name.ext',
 639  \layout Verbatim
 640  
 641       'relatives' => array(
 642  \layout Verbatim
 643  
 644            RELATIVE_NONE|VFS_REAL,
 645  \layout Verbatim
 646  
 647            RELATIVE_USER
 648  \layout Verbatim
 649  
 650       )
 651  \layout Verbatim
 652  
 653  ));
 654  \layout Standard
 655  
 656  $randomdir and $randomfile are what the directory and file might be called
 657   before they are given a proper name by the user, which is actual_name.ext
 658   in this example.
 659   RELATIVE_NONE is the define for using full path names.
 660   However, RELATIVE_NONE is still relative to the virtual root, so we pass
 661   along VFS_REAL as well, to say that the file is 
 662  \emph on 
 663  outside
 664  \emph default 
 665   the virtual root, somewhere else in the file system.
 666   Once again, RELATIVE_USER means relative to the user's home directory.
 667   So the actual file system call might look like this (keep in mind that
 668   $randomdir and $randomfile are just random strings):
 669  \layout Verbatim
 670  
 671  rename ('/var/www/egroupware/tmp/0ak5adftgh7/jX42sC9M', '/var/www/egroupware
 672  /files/home/jason/attachments/actual_name.ext');
 673  \layout Standard
 674  
 675  Of course you don't have to know that, nor should you be concerned with
 676   it; you can take it for granted that the VFS will translate the paths correctly.
 677   Let's take a look at one more example, this time using the RELATIVE_USER_APP
 678   define.
 679   RELATIVE_USER_APP is used to store quasi-hidden application files, similar
 680   to the Unix convention of ~/.appname.
 681   It simply appends .appname to the user's home directory.
 682   For example, if you were making an HTML editor application named 'htmledit',
 683   and wanted to keep a backup file in case something goes wrong, you could
 684   use RELATIVE_USER_APP to store it:
 685  \layout Verbatim
 686  
 687  $GLOBALS['phpgw']->vfs->write (array(
 688  \layout Verbatim
 689  
 690       'string' => 'file.name~',
 691  \layout Verbatim
 692  
 693       'relatives' => array(
 694  \layout Verbatim
 695  
 696            RELATIVE_USER_APP
 697  \layout Verbatim
 698  
 699       ),
 700  \layout Verbatim
 701  
 702       'content' => $contents
 703  \layout Verbatim
 704  
 705  ));
 706  \layout Standard
 707  
 708  This assumes that ~/.htmledit exists of course.
 709   The backup file 
 710  \begin_inset Quotes eld
 711  \end_inset 
 712  
 713  file.name~
 714  \begin_inset Quotes erd
 715  \end_inset 
 716  
 717   would then be written in $fakebase/jason/.htmledit/file.name~.
 718   Note that storing files like this might not be as good of a solution as
 719   storing them in the temporary directory or in the database.
 720   But it is there in case you need it.
 721  \layout Subsection
 722  
 723  Complete List
 724  \begin_inset LatexCommand \label{sec:relatives_complete_list}
 725  
 726  \end_inset 
 727  
 728  
 729  \layout Standard
 730  
 731  Here is the complete list of RELATIVE defines, and what they do:
 732  \layout Description
 733  
 734  RELATIVE_ROOT Don't translate the path at all.
 735   Just prepends a /.
 736   You'll probably want to use RELATIVE_NONE though, which handles both virtual
 737   and real files.
 738  \layout Description
 739  
 740  RELATIVE_USER User's home directory
 741  \layout Description
 742  
 743  RELATIVE_CURR_USER Current user's home directory.
 744   If the current directory is $fakebase/my_group/project1, this will return
 745   is $fakebase/my_group
 746  \layout Description
 747  
 748  RELATIVE_USER_APP Append .appname to the user's home directory, where appname
 749   is the current application's appname
 750  \layout Description
 751  
 752  RELATIVE_PATH DO NOT USE.
 753   Relative to the current directory, used in RELATIVE_ALL
 754  \layout Description
 755  
 756  RELATIVE_NONE Not relative to anything.
 757   Use this with VFS_REAL for files outside the virtual root.
 758   Note that using RELATIVE_NONE by itself still means relative to the virtual
 759   root
 760  \layout Description
 761  
 762  RELATIVE_CURRENT An alias for the currently set RELATIVE define, or RELATIVE_ALL
 763   if none is set (see the Defaults section)
 764  \layout Description
 765  
 766  VFS_REAL File is outside of the virtual root.
 767   Usually used with RELATIVE_NONE
 768  \layout Description
 769  
 770  RELATIVE_ALL Relative to the current directory.
 771   Use RELATIVE_ALL
 772  \emph on 
 773   
 774  \emph default 
 775  instead of RELATIVE_PATH
 776  \layout Subsection
 777  
 778  Defaults
 779  \begin_inset LatexCommand \label{sec:relatives_defaults}
 780  
 781  \end_inset 
 782  
 783  
 784  \layout Standard
 785  
 786  You might be thinking to yourself that passing along RELATIVE defines with
 787   every VFS call is overkill, especially if your application always uses
 788   the same relativity.
 789   The default RELATIVE define for all VFS calls is RELATIVE_CURRENT.
 790   RELATIVE_CURRENT itself defaults to RELATIVE_ALL (relative to the current
 791   path), 
 792  \emph on 
 793  unless
 794  \emph default 
 795   your application sets a specific relativity.
 796   If your application requires most of the work to be done outside of the
 797   virtual root, you may wish to set RELATIVE_CURRENT to RELATIVE_NONE|VFS_REAL.
 798   set_relative () is the function to do this.
 799   For example:
 800  \layout Verbatim
 801  
 802  $GLOBALS['phpgw']->vfs->set_relative (array(
 803  \layout Verbatim
 804  
 805       'mask' => RELATIVE_NONE|VFS_REAL
 806  \layout Verbatim
 807  
 808  ));
 809  \layout Verbatim
 810  
 811  \layout Verbatim
 812  
 813  $GLOBALS['phpgw']->vfs->read (array(
 814  \layout Verbatim
 815  
 816       'string' => '/etc/passwd'
 817  \layout Verbatim
 818  
 819  ));
 820  \layout Verbatim
 821  
 822  \layout Verbatim
 823  
 824  $GLOBALS['phpgw']->vfs->cp (array(
 825  \layout Verbatim
 826  
 827       'from' => '/usr/include/stdio.h',
 828  \layout Verbatim
 829  
 830       'to' => '/tmp/stdio.h'
 831  \layout Verbatim
 832  
 833  ));
 834  \layout Verbatim
 835  
 836  \layout Verbatim
 837  
 838  $GLOBALS['phpgw']->vfs->cp (array(
 839  \layout Verbatim
 840  
 841       'from' => '/usr/share/pixmaps/yes.xpm',
 842  \layout Verbatim
 843  
 844       'to' => 'icons/yes.xpm',
 845  \layout Verbatim
 846  
 847       'relatives' => array(
 848  \layout Verbatim
 849  
 850            RELATIVE_CURRENT,
 851  \layout Verbatim
 852  
 853            RELATIVE_USER
 854  \layout Verbatim
 855  
 856       )
 857  \layout Verbatim
 858  
 859  ));
 860  \layout Standard
 861  
 862  You should notice that no relativity array is needed in the other calls
 863   that refer to files outside the virtual root, but one is needed for calls
 864   that include files inside the virtual root.
 865   Any RELATIVE define can be set as the default and works in the same fashion.
 866   To retrieve the currently set define, use get_relative ().
 867   Note that the relativity is reset after each page request; that is, it's
 868   good only for the life of the current page loading, and is not stored in
 869   session management.
 870  \layout Section
 871  
 872  Function reference
 873  \begin_inset LatexCommand \label{sec:function_reference}
 874  
 875  \end_inset 
 876  
 877  
 878  \layout Standard
 879  
 880  To view the function reference for the VFS, use the doc/inlinedocparser.php
 881   script that comes with eGoupWare, ie 
 882  \begin_inset LatexCommand \url[http://localhost/doc/inlinedocparser.php?fn=class.vfs_sql.inc.php]{http://localhost/doc/inlinedocparser.php?fn=class.vfs_sql.inc.php}
 883  
 884  \end_inset 
 885  
 886  .
 887  \layout Section
 888  
 889  Notes
 890  \begin_inset LatexCommand \label{sec:notes}
 891  
 892  \end_inset 
 893  
 894  
 895  \layout Subsection
 896  
 897  Database
 898  \begin_inset LatexCommand \label{sec:database}
 899  
 900  \end_inset 
 901  
 902  
 903  \layout Standard
 904  
 905  Data about the files and directories within the virtual root is kept in
 906   the SQL database.
 907   Currently, this information includes:
 908  \layout Itemize
 909  
 910  File ID (used internally, primary key for table)
 911  \layout Itemize
 912  
 913  Owner ID (phpGW account_id)
 914  \layout Itemize
 915  
 916  Created by ID (phpGW account_id)
 917  \layout Itemize
 918  
 919  Modified by ID (phpGW account_id)
 920  \layout Itemize
 921  
 922  Created (date)
 923  \layout Itemize
 924  
 925  Modified (date)
 926  \layout Itemize
 927  
 928  Size (bytes)
 929  \layout Itemize
 930  
 931  MIME type
 932  \layout Itemize
 933  
 934  Deleteable (Y/N/Other?)
 935  \layout Itemize
 936  
 937  Comment
 938  \layout Itemize
 939  
 940  App (appname of application that created the file)
 941  \layout Itemize
 942  
 943  Directory (directory the file or directory is in)
 944  \layout Itemize
 945  
 946  Name (name of file or directory)
 947  \layout Itemize
 948  
 949  Link directory (if the file or directory is linked, what the actual directory
 950   is)
 951  \layout Itemize
 952  
 953  Link name (if the file or directory is linked, what the actual name is)
 954  \layout Itemize
 955  
 956  Version (numeric version of the file)
 957  \layout Standard
 958  
 959  The internal names of these (the database column names) are stored in the
 960   $GLOBALS['phpgw']->vfs->attributes array, which is useful for loops, and
 961   is guaranteed to be up-to-date.
 962  \layout Standard
 963  
 964  Note that no information is kept about files outside the virtual root.
 965   If a file is moved outside, all records of it are deleted from the database
 966   (other than the journaling records).
 967   If a file is moved into the virtual root, some information, specifically
 968   MIME-type, is not always stored in the database.
 969   The vital information has defaults: owner is based on where the file is
 970   being stored; size is correctly read; deleteable is set to Y.
 971  \layout Subsection
 972  
 973  ACL support
 974  \begin_inset LatexCommand \label{sec:acl_support}
 975  
 976  \end_inset 
 977  
 978  
 979  \layout Standard
 980  
 981  ACL support is built into the VFS.
 982   vfs->acl_check () does the actual checking, and is called from all VFS
 983   functions as needed.
 984   If the file or directory sent to acl_check () doesn't exist, the permissions
 985   for the parent directory are used to determine access.
 986   ACL checking can be overridden at any time by setting vfs->override_acl.
 987   For example:
 988  \layout Verbatim
 989  
 990  $GLOBALS['phpgw']->vfs->override_acl = 1;
 991  \layout Verbatim
 992  
 993  $GLOBALS['phpgw']->vfs->mkdir (array(
 994  \layout Verbatim
 995  
 996       'string' => $GLOBALS['fakebase'].
 997   '/' .
 998   $group_array['account_name'],
 999  \layout Verbatim
1000  
1001       'relatives' => array(
1002  \layout Verbatim
1003  
1004            RELATIVE_NONE
1005  \layout Verbatim
1006  
1007       )
1008  \layout Verbatim
1009  
1010  ));
1011  \layout Verbatim
1012  
1013  $GLOBALS['phpgw']->vfs->override_acl = 0;
1014  \layout Subsection
1015  
1016  Function aliases
1017  \begin_inset LatexCommand \label{sec:function_aliases}
1018  
1019  \end_inset 
1020  
1021  
1022  \layout Standard
1023  
1024  You might have noticed there are some functions that just pass the arguments
1025   on to other functions.
1026   These are provided in part because of legacy and in part for convenience.
1027   You can use either.
1028   Here is the list (alias -> actual):
1029  \layout Itemize
1030  
1031  copy -> cp
1032  \layout Itemize
1033  
1034  move -> rm
1035  \layout Itemize
1036  
1037  delete -> rm
1038  \layout Itemize
1039  
1040  dir -> ls
1041  \layout Subsection
1042  
1043  Fakebase directory (changing /home)
1044  \begin_inset LatexCommand \label{sec:fakebase}
1045  
1046  \end_inset 
1047  
1048  
1049  \layout Standard
1050  
1051  The old VFS was hard-coded to use '/home' as the fake base directory, even
1052   though the user never saw it.
1053   With the new system, crafty administrators may wish to change '/home' to
1054   something else, say '/users' or '/public_html'.
1055   The fake base directory name is stored in $GLOBALS['phpgw']->vfs->fakebase,
1056   and changing it will transparently change it throughout the VFS and all
1057   applications.
1058   However, this must be done 
1059  \emph on 
1060  before
1061  \emph default 
1062   any data is in the VFS database.
1063   If you wish to change it afterwords, you'll have to manually update the
1064   database, replacing the old value with the new value.
1065   
1066  \emph on 
1067  Application programmers need to recognize that /home is not absolute, and
1068   use $GLOBALS['phpgw']->vfs->fakebase instead
1069  \emph default 
1070  .
1071   I suggest setting $fakebase = $GLOBALS['phpgw']->vfs->fakebase; right off
1072   the bat to keep things neater.
1073  \layout Section
1074  
1075  About this Document
1076  \layout Subsection
1077  
1078  Copyright and License
1079  \layout Standard
1080  
1081  Copyright (c) 2001, 2002 Jason Wies
1082  \layout Standard
1083  
1084  Permission is granted to copy, distribute and/or modify this document under
1085   the terms of the GNU Free Documentation License, Version 1.1 or any later
1086   version published by the Free Software Foundation; with no Invarient Sections,
1087   with no Front-Cover Texts, and no Back-Cover Texts.
1088  \layout Standard
1089  
1090  A copy of the license is available at 
1091  \begin_inset LatexCommand \url[http://www.gnu.org/copyleft/fdl.html]{http://www.gnu.org/copyleft/fdl.html}
1092  
1093  \end_inset 
1094  
1095  .
1096  \layout Subsection
1097  
1098  History
1099  \layout Standard
1100  
1101  Original document released in June 2001 by Jason Wies.
1102  \layout Standard
1103  
1104  Updated February 2002 to include arrayized parameters, single quotes, and
1105   GLOBALS.
1106  \layout Subsection
1107  
1108  Contributing
1109  \layout Standard
1110  
1111  Contributions are always welcome.
1112   Please send to the current maintainer, Jason Wies, 
1113  
1114  
1115  \end_inset 
1116  
1117  .
1118  \the_end