forked from extern/egroupware
Initial revision; rough drafts
This commit is contained in:
zone
parent
adeba0e1eb
commit
6fb4f5b369
164
phpgwapi/doc/vfs/inline2lyx.pl
Executable file
164
phpgwapi/doc/vfs/inline2lyx.pl
Executable file
@ -0,0 +1,164 @@
|
||||
#!/usr/bin/perl
|
||||
#Created by Jason Wies (Zone, zone@users.sourceforge.net)
|
||||
#Copyright 2001 Jason Wies
|
||||
#Released under GNU Public License
|
||||
|
||||
#Converts HeaderDoc style inline comments to LyX style LaTeX
|
||||
#Usage: ./inline2lyx.pl file Title Author Date Abstract
|
||||
|
||||
if (!@ARGV[0])
|
||||
{
|
||||
print "Usage: ./inline2lyx.pl file Title Author Date Abstract\n";
|
||||
exit;
|
||||
}
|
||||
|
||||
$output .= '\lyxformat 2.16
|
||||
\textclass linuxdoc
|
||||
\language default
|
||||
\inputencoding latin1
|
||||
\fontscheme default
|
||||
\graphics default
|
||||
\paperfontsize default
|
||||
\spacing single
|
||||
\papersize Default
|
||||
\paperpackage a4
|
||||
\use_geometry 0
|
||||
\use_amsmath 0
|
||||
\paperorientation portrait
|
||||
\secnumdepth 2
|
||||
\tocdepth 2
|
||||
\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
|
||||
' . @ARGV[1] . '
|
||||
\layout Author
|
||||
|
||||
' . @ARGV[2] . '
|
||||
|
||||
\layout Date
|
||||
|
||||
' . @ARGV[3] . '
|
||||
|
||||
\layout Abstract
|
||||
|
||||
' . @ARGV[4] . '
|
||||
|
||||
\layout Section
|
||||
|
||||
' . @ARGV[1];
|
||||
|
||||
$file = `cat @ARGV[0]`;
|
||||
|
||||
@lines = split ('\n', $file);
|
||||
|
||||
foreach $line (@lines)
|
||||
{
|
||||
undef $start;
|
||||
undef $class;
|
||||
undef $function;
|
||||
undef $abstract;
|
||||
undef $param;
|
||||
undef $result;
|
||||
undef $discussion;
|
||||
undef $end;
|
||||
undef $layout;
|
||||
|
||||
if ($line =~ /\/\*\!/)
|
||||
{
|
||||
$in = 1;
|
||||
$start = 1;
|
||||
}
|
||||
|
||||
if ($looking && $line =~ /function/)
|
||||
{
|
||||
$layout = "verbatim";
|
||||
undef $looking;
|
||||
}
|
||||
elsif (!$in)
|
||||
{
|
||||
goto next;
|
||||
}
|
||||
|
||||
if ($line =~ /\@(class)/)
|
||||
{
|
||||
$layout = "subsection";
|
||||
$name = $1;
|
||||
$class = 1;
|
||||
}
|
||||
if ($line =~ /\@(function)/)
|
||||
{
|
||||
$layout = "subsection";
|
||||
$name = $1;
|
||||
$function = 1;
|
||||
}
|
||||
if ($line =~ /\@(abstract)/)
|
||||
{
|
||||
$layout = "standard";
|
||||
$name = $1;
|
||||
$abstract = 1;
|
||||
}
|
||||
if ($line =~ /\@(description)/)
|
||||
{
|
||||
$layout = "standard";
|
||||
$name = $1;
|
||||
$description = 1;
|
||||
}
|
||||
if ($line =~ /\@(param)/)
|
||||
{
|
||||
$layout = "standard";
|
||||
$name = $1;
|
||||
$param = 1;
|
||||
}
|
||||
if ($line =~ /\@(result)/)
|
||||
{
|
||||
$layout = "standard";
|
||||
$name = $1;
|
||||
$result = 1;
|
||||
}
|
||||
if ($line =~ /\@(discussion)/)
|
||||
{
|
||||
$layout = "standard";
|
||||
$name = $1;
|
||||
$discussion = 1;
|
||||
}
|
||||
if ($line =~ /\*\// && $in)
|
||||
{
|
||||
undef $in;
|
||||
$looking = 1;
|
||||
$end = 1;
|
||||
}
|
||||
|
||||
if ($layout)
|
||||
{
|
||||
$output .= "\n\n" . '\layout ' . ucfirst ($layout);
|
||||
$line =~ s/\@function//;
|
||||
$line =~ s/\@//;
|
||||
$data = ucfirst ($line);
|
||||
if (!$function && !$class)
|
||||
{
|
||||
$data =~ s/$name/$name:/;
|
||||
}
|
||||
$output .= "\n$data";
|
||||
if ($function || $class)
|
||||
{
|
||||
$output .= "\n" . '\begin_inset LatexCommand \label{sec:' . "$data" . '}' . "\n\n" . '\end_inset';
|
||||
}
|
||||
}
|
||||
elsif ($in && !$start)
|
||||
{
|
||||
$output .= '\layout Standard' . "\n$line";
|
||||
}
|
||||
|
||||
next:
|
||||
}
|
||||
|
||||
$output .= "\n" . '\the_end';
|
||||
|
||||
print $output;
|
||||
27
phpgwapi/doc/vfs/vfs-1.html
Normal file
27
phpgwapi/doc/vfs/vfs-1.html
Normal file
@ -0,0 +1,27 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.7.4">
|
||||
<TITLE>phpgwapi - VFS Class: Introduction and Purpose</TITLE>
|
||||
<LINK HREF="vfs-2.html" REL=next>
|
||||
|
||||
<LINK HREF="vfs.html#toc1" REL=contents>
|
||||
</HEAD>
|
||||
<BODY>
|
||||
<A HREF="vfs-2.html">Next</A>
|
||||
Previous
|
||||
<A HREF="vfs.html#toc1">Contents</A>
|
||||
<HR>
|
||||
<H2><A NAME="sec:introduction"></A> <A NAME="s1">1.</A> <A HREF="vfs.html#toc1">Introduction and Purpose</A></H2>
|
||||
|
||||
<P>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.</P>
|
||||
<HR>
|
||||
<A HREF="vfs-2.html">Next</A>
|
||||
Previous
|
||||
<A HREF="vfs.html#toc1">Contents</A>
|
||||
</BODY>
|
||||
</HTML>
|
||||
108
phpgwapi/doc/vfs/vfs-2.html
Normal file
108
phpgwapi/doc/vfs/vfs-2.html
Normal file
@ -0,0 +1,108 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.7.4">
|
||||
<TITLE>phpgwapi - VFS Class: Basics</TITLE>
|
||||
<LINK HREF="vfs-3.html" REL=next>
|
||||
<LINK HREF="vfs-1.html" REL=previous>
|
||||
<LINK HREF="vfs.html#toc2" REL=contents>
|
||||
</HEAD>
|
||||
<BODY>
|
||||
<A HREF="vfs-3.html">Next</A>
|
||||
<A HREF="vfs-1.html">Previous</A>
|
||||
<A HREF="vfs.html#toc2">Contents</A>
|
||||
<HR>
|
||||
<H2><A NAME="sec:basics"></A> <A NAME="s2">2.</A> <A HREF="vfs.html#toc2">Basics</A></H2>
|
||||
|
||||
<H2><A NAME="sec:prerequisites"></A> <A NAME="ss2.1">2.1</A> <A HREF="vfs.html#toc2.1">Prerequisites</A>
|
||||
</H2>
|
||||
|
||||
<P>You must explicitly enable the VFS class. To do this, set "enable_vfs_class"
|
||||
to True in $phpgw_info["flags"]. An example:</P>
|
||||
<P>
|
||||
<PRE>
|
||||
$phpgw_info["flags"] = array("currentapp" => "phpwebhosting",
|
||||
"noheader" => False,
|
||||
"noappheader" => False,
|
||||
"enable_vfs_class" => True,
|
||||
"enable_browser_class" => True);
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec:concepts"></A> <A NAME="ss2.2">2.2</A> <A HREF="vfs.html#toc2.2">Concepts</A>
|
||||
</H2>
|
||||
|
||||
<P>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:</P>
|
||||
<P>
|
||||
<UL>
|
||||
<LI>Files and directories are synonymous in almost all cases</LI>
|
||||
</UL>
|
||||
</P>
|
||||
<P>
|
||||
<PRE>
|
||||
$phpgw->vfs->mv ("file1", "dir/file2");
|
||||
$phpgw->vfs->mv ("dir1", "dir/dir1");
|
||||
$phpgw->vfs->rm ("file");
|
||||
$phpgw->vfs->rm ("dir");
|
||||
</PRE>
|
||||
</P>
|
||||
<P>All work as you would except them to. The major exception is:</P>
|
||||
<P>
|
||||
<PRE>
|
||||
$phpgw->vfs->touch ("file");
|
||||
</PRE>
|
||||
</P>
|
||||
<P>vs.</P>
|
||||
<P>
|
||||
<PRE>
|
||||
$phpgw->vfs->mkdir ("dir");
|
||||
</PRE>
|
||||
</P>
|
||||
<P>
|
||||
<UL>
|
||||
<LI>Users and groups and synonymous</LI>
|
||||
</UL>
|
||||
</P>
|
||||
<P>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.</P>
|
||||
<P>
|
||||
<UL>
|
||||
<LI>You should never have to know the real path of files</LI>
|
||||
</UL>
|
||||
</P>
|
||||
<P>One of the VFS's responsibilities is to translate paths for you. While
|
||||
you certainly <EM>can</EM> operate using full paths, it is much simpler to use the virtual
|
||||
paths. For example, instead of using:</P>
|
||||
<P>
|
||||
<PRE>
|
||||
$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));
|
||||
</PRE>
|
||||
</P>
|
||||
<P>you might use</P>
|
||||
<P>
|
||||
<PRE>
|
||||
$phpgw->vfs->cp ("/home/user/file1", "/home/user/file2", array (RELATIVE_NONE, RELATIVE_NONE));
|
||||
</PRE>
|
||||
</P>
|
||||
<P>(We'll get to the RELATIVE's in a minute.)</P>
|
||||
<P>Site administrators should be able to move their files dir around on their
|
||||
system and know that everything will continue to work smoothly.</P>
|
||||
<P>
|
||||
<UL>
|
||||
<LI>Relativity is <EM>vital</EM></LI>
|
||||
</UL>
|
||||
</P>
|
||||
<P>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.</P>
|
||||
<HR>
|
||||
<A HREF="vfs-3.html">Next</A>
|
||||
<A HREF="vfs-1.html">Previous</A>
|
||||
<A HREF="vfs.html#toc2">Contents</A>
|
||||
</BODY>
|
||||
</HTML>
|
||||
106
phpgwapi/doc/vfs/vfs-3.html
Normal file
106
phpgwapi/doc/vfs/vfs-3.html
Normal file
@ -0,0 +1,106 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.7.4">
|
||||
<TITLE>phpgwapi - VFS Class: Basic Functions</TITLE>
|
||||
<LINK HREF="vfs-4.html" REL=next>
|
||||
<LINK HREF="vfs-2.html" REL=previous>
|
||||
<LINK HREF="vfs.html#toc3" REL=contents>
|
||||
</HEAD>
|
||||
<BODY>
|
||||
<A HREF="vfs-4.html">Next</A>
|
||||
<A HREF="vfs-2.html">Previous</A>
|
||||
<A HREF="vfs.html#toc3">Contents</A>
|
||||
<HR>
|
||||
<H2><A NAME="sec:basic_functions"></A> <A NAME="s3">3.</A> <A HREF="vfs.html#toc3">Basic Functions</A></H2>
|
||||
|
||||
<P>These are two functions you'll need to know before we get into relativity.</P>
|
||||
<H2><A NAME="sec:path_parts"></A> <A NAME="ss3.1">3.1</A> <A HREF="vfs.html#toc3.1">path_parts ()</A>
|
||||
</H2>
|
||||
|
||||
<P>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:</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function path_parts ($string, $relatives = array (RELATIVE_CURRENT), $object = True)
|
||||
</PRE>
|
||||
</P>
|
||||
<P>$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>
|
||||
<P>
|
||||
<PRE>
|
||||
fake_full_path
|
||||
fake_leading_dirs
|
||||
fake_extra_path
|
||||
fake_name
|
||||
real_full_path
|
||||
real_leading_dirs
|
||||
real_extra_path
|
||||
real_name
|
||||
</PRE>
|
||||
</P>
|
||||
<P>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>
|
||||
<P>
|
||||
<PRE>
|
||||
$p = $phpgw->vfs->path_parts ("/home/jason/dir/file", array (RELATIVE_NONE));
|
||||
</PRE>
|
||||
</P>
|
||||
<P>
|
||||
<UL>
|
||||
<LI>$p->fake_full_path - /home/jason/dir/file</LI>
|
||||
<LI>$p->fake_leading_dirs - /home/jason/dir</LI>
|
||||
<LI>$p->fake_extra_path - home/jason/dir</LI>
|
||||
<LI>$p->fake_name - file</LI>
|
||||
<LI>$p->real_full_path - /var/www/phpgroupware/files/home/jason/dir/file</LI>
|
||||
<LI>$p->real_leading_dirs - /var/www/phpgroupware/files/home/jason/dir
|
||||
</LI>
|
||||
<LI>$p->real_extra_path - home/jason/dir</LI>
|
||||
<LI>$p->real_name - file</LI>
|
||||
</UL>
|
||||
</P>
|
||||
<P>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 <EM>getabsolutepath () is depreciated</EM>. getabsolutepath () still
|
||||
exists (albeit in a much different form), and is responsible for some of the
|
||||
path translation, but it is an <EM>internal</EM> 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
|
||||
<A HREF="vfs-4.html#sec:relativity"></A>.</P>
|
||||
<H2><A NAME="sec:cd"></A> <A NAME="ss3.2">3.2</A> <A HREF="vfs.html#toc3.2">cd ()</A>
|
||||
</H2>
|
||||
|
||||
<P>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:</P>
|
||||
|
||||
<P>
|
||||
<PRE>
|
||||
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 */
|
||||
</PRE>
|
||||
</P>
|
||||
<P>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
|
||||
().</P>
|
||||
<P>Now you're ready for relativity.</P>
|
||||
<HR>
|
||||
<A HREF="vfs-4.html">Next</A>
|
||||
<A HREF="vfs-2.html">Previous</A>
|
||||
<A HREF="vfs.html#toc3">Contents</A>
|
||||
</BODY>
|
||||
</HTML>
|
||||
155
phpgwapi/doc/vfs/vfs-4.html
Normal file
155
phpgwapi/doc/vfs/vfs-4.html
Normal file
@ -0,0 +1,155 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.7.4">
|
||||
<TITLE>phpgwapi - VFS Class: Relativity</TITLE>
|
||||
<LINK HREF="vfs-5.html" REL=next>
|
||||
<LINK HREF="vfs-3.html" REL=previous>
|
||||
<LINK HREF="vfs.html#toc4" REL=contents>
|
||||
</HEAD>
|
||||
<BODY>
|
||||
<A HREF="vfs-5.html">Next</A>
|
||||
<A HREF="vfs-3.html">Previous</A>
|
||||
<A HREF="vfs.html#toc4">Contents</A>
|
||||
<HR>
|
||||
<H2><A NAME="sec:relativity"></A> <A NAME="s4">4.</A> <A HREF="vfs.html#toc4">Relativity</A></H2>
|
||||
|
||||
<P>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.
|
||||
<EM>You should always use $fakebase when making applications. </EM>I suggest
|
||||
doing $fakebase = $phpgw->vfs->fakebase; right off the
|
||||
bat to keep things neater.</P>
|
||||
<H2><A NAME="ss4.1">4.1</A> <A HREF="vfs.html#toc4.1">What is it and how does it work?</A>
|
||||
</H2>
|
||||
|
||||
<P>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.</P>
|
||||
|
||||
<P>
|
||||
<PRE>
|
||||
$phpgw->vfs->mv ("logo.png", "", array (RELATIVE_USER, RELATIVE_ALL));
|
||||
</PRE>
|
||||
</P>
|
||||
<P>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:</P>
|
||||
<P>
|
||||
<PRE>
|
||||
MOVE "$fakebase/jason/logo.png" TO "$fakebase/my_group/project1/logo.png"
|
||||
</PRE>
|
||||
</P>
|
||||
<P>and the actual file system call would be:</P>
|
||||
<P>
|
||||
<PRE>
|
||||
rename ("/var/www/phpgroupware/files/home/jason/logo.php", "/var/www/phpgroupware/files/home/my_group/project1/logo.png");
|
||||
</PRE>
|
||||
</P>
|
||||
<P>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 <EM>outside</EM> the virtual
|
||||
root.</P>
|
||||
<P>
|
||||
<PRE>
|
||||
$phpgw->vfs->mv ("$phpgw_info[server][temp_dir]/$randomdir/$randomfile", "attachments/actual_name.ext", array (RELATIVE_NONE|VFS_REAL, RELATIVE_USER));
|
||||
</PRE>
|
||||
</P>
|
||||
<P>$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 <EM>outside</EM> 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):</P>
|
||||
<P>
|
||||
<PRE>
|
||||
rename ("/var/www/phpgroupware/tmp/0ak5adftgh7/jX42sC9M", "/var/www/phpgroupware/files/home/users/jason/attachments/actual_name.ext");
|
||||
</PRE>
|
||||
</P>
|
||||
<P>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:</P>
|
||||
<P>
|
||||
<PRE>
|
||||
$phpgw->vfs->write ("file.name~", array (RELATIVE_USER_APP), $contents);
|
||||
</PRE>
|
||||
</P>
|
||||
<P>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.</P>
|
||||
<H2><A NAME="sec:relatives_complete_list"></A> <A NAME="ss4.2">4.2</A> <A HREF="vfs.html#toc4.2">Complete List</A>
|
||||
</H2>
|
||||
|
||||
<P>Here is the complete list of RELATIVE defines, and what they do:</P>
|
||||
<P>
|
||||
<DL>
|
||||
<DT><B>RELATIVE_ROOT</B><DD><P>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.</P>
|
||||
<DT><B>RELATIVE_USER</B><DD><P>User's home directory</P>
|
||||
<DT><B>RELATIVE_CURR_USER</B><DD><P>Current user's home directory. If the current
|
||||
directory is $fakebase/my_group/project1, this will return is $fakebase/my_group</P>
|
||||
<DT><B>RELATIVE_USER_APP</B><DD><P>Append .appname to the user's home directory, where
|
||||
appname is the current application's appname</P>
|
||||
<DT><B>RELATIVE_PATH</B><DD><P>DO NOT USE. Relative to the current directory, used
|
||||
in RELATIVE_ALL</P>
|
||||
<DT><B>RELATIVE_NONE</B><DD><P>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</P>
|
||||
<DT><B>RELATIVE_CURRENT</B><DD><P>An alias for the currently set RELATIVE define,
|
||||
or RELATIVE_ALL if none is set (see the Defaults section)</P>
|
||||
<DT><B>VFS_REAL</B><DD><P>File is outside of the virtual root. Usually used with RELATIVE_NONE</P>
|
||||
<DT><B>RELATIVE_ALL</B><DD><P>Relative to the current directory. Use RELATIVE_ALL<EM></EM>instead of RELATIVE_PATH</P>
|
||||
</DL>
|
||||
</P>
|
||||
<H2><A NAME="sec:relatives_defaults"></A> <A NAME="ss4.3">4.3</A> <A HREF="vfs.html#toc4.3">Defaults</A>
|
||||
</H2>
|
||||
|
||||
<P>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),
|
||||
<EM>unless</EM> 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:</P>
|
||||
<P>
|
||||
<PRE>
|
||||
$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));
|
||||
</PRE>
|
||||
</P>
|
||||
<P>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.</P>
|
||||
<HR>
|
||||
<A HREF="vfs-5.html">Next</A>
|
||||
<A HREF="vfs-3.html">Previous</A>
|
||||
<A HREF="vfs.html#toc4">Contents</A>
|
||||
</BODY>
|
||||
</HTML>
|
||||
411
phpgwapi/doc/vfs/vfs-5.html
Normal file
411
phpgwapi/doc/vfs/vfs-5.html
Normal file
@ -0,0 +1,411 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.7.4">
|
||||
<TITLE>phpgwapi - VFS Class: Function reference</TITLE>
|
||||
<LINK HREF="vfs-6.html" REL=next>
|
||||
<LINK HREF="vfs-4.html" REL=previous>
|
||||
<LINK HREF="vfs.html#toc5" REL=contents>
|
||||
</HEAD>
|
||||
<BODY>
|
||||
<A HREF="vfs-6.html">Next</A>
|
||||
<A HREF="vfs-4.html">Previous</A>
|
||||
<A HREF="vfs.html#toc5">Contents</A>
|
||||
<HR>
|
||||
<H2><A NAME="sec:function_reference"></A> <A NAME="s5">5.</A> <A HREF="vfs.html#toc5">Function reference</A></H2>
|
||||
|
||||
<H2><A NAME="sec:function_reference_about"></A> <A NAME="ss5.1">5.1</A> <A HREF="vfs.html#toc5.1">About</A>
|
||||
</H2>
|
||||
|
||||
<P>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.</P>
|
||||
<H2><A NAME="sec: class vfs"></A> <A NAME="ss5.2">5.2</A> <A HREF="vfs.html#toc5.2">class vfs</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: virtual file system</P>
|
||||
<P>description: Authors: Zone, Seek3r</P>
|
||||
<H2><A NAME="sec: class path_class"></A> <A NAME="ss5.3">5.3</A> <A HREF="vfs.html#toc5.3">class path_class</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: helper class for path_parts</P>
|
||||
<H2><A NAME="sec: vfs"></A> <A NAME="ss5.4">5.4</A> <A HREF="vfs.html#toc5.4">vfs</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: constructor, sets up variables</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function vfs ()
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: set_relative"></A> <A NAME="ss5.5">5.5</A> <A HREF="vfs.html#toc5.5">set_relative</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Set path relativity</P>
|
||||
<P>param: $mask Relative bitmask (see RELATIVE_ defines)</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function set_relative ($mask)
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: get_relative"></A> <A NAME="ss5.6">5.6</A> <A HREF="vfs.html#toc5.6">get_relative</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Return relativity bitmask</P>
|
||||
<P>discussion: Returns relativity bitmask, or the default of "completely
|
||||
relative" if unset</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function get_relative ()
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: sanitize"></A> <A NAME="ss5.7">5.7</A> <A HREF="vfs.html#toc5.7">sanitize</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Removes leading .'s from $string</P>
|
||||
<P>discussion: You should not pass all filenames through sanitize () unless
|
||||
you plan on rejecting</P>
|
||||
<P>.files. Instead, pass the name through securitycheck () first, and if
|
||||
it fails,</P>
|
||||
<P>pass it through sanitize</P>
|
||||
<P>param: $string string to sanitize</P>
|
||||
<P>result: $string without it's leading .'s</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function sanitize ($string)
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: securitycheck"></A> <A NAME="ss5.8">5.8</A> <A HREF="vfs.html#toc5.8">securitycheck</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Security check function</P>
|
||||
<P>discussion: Checks for basic violations such as ..</P>
|
||||
<P>If securitycheck () fails, run your string through vfs->sanitize ()</P>
|
||||
<P>param: $string string to check security of</P>
|
||||
<P>result: Boolean True/False. True means secure, False means insecure</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function securitycheck ($string)
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: db_clean"></A> <A NAME="ss5.9">5.9</A> <A HREF="vfs.html#toc5.9">db_clean</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Clean $string for use in database queries</P>
|
||||
<P>param: $string String to clean</P>
|
||||
<P>result: Cleaned version of $string</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function db_clean ($string)
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: path_parts"></A> <A NAME="ss5.10">5.10</A> <A HREF="vfs.html#toc5.10">path_parts</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: take a real or fake pathname and return an array of its component
|
||||
parts</P>
|
||||
<P>param: $string full real or fake path</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>param: $object True returns an object instead of an array</P>
|
||||
<P>result: $rarray/$robject Array or object containing the fake
|
||||
and real component parts of the path</P>
|
||||
<P>discussion: Returned values are:</P>
|
||||
<P>mask</P>
|
||||
<P>outside</P>
|
||||
<P>fake_full_path</P>
|
||||
<P>fake_leading_dirs</P>
|
||||
<P>fake_extra_path</P>
|
||||
<P>fake_name</P>
|
||||
<P>real_full_path</P>
|
||||
<P>real_leading_dirs</P>
|
||||
<P>real_extra_path</P>
|
||||
<P>real_name</P>
|
||||
<P>fake_full_path_clean</P>
|
||||
<P>fake_leading_dirs_clean</P>
|
||||
<P>fake_extra_path_clean</P>
|
||||
<P>fake_name_clean</P>
|
||||
<P>real_full_path_clean</P>
|
||||
<P>real_leading_dirs_clean</P>
|
||||
<P>real_extra_path_clean</P>
|
||||
<P>real_name_clean</P>
|
||||
<P>"clean" values are run through vfs->db_clean () and</P>
|
||||
<P>are safe for use in SQL queries that use key='value'</P>
|
||||
<P>They should be used ONLY for SQL queries, so are used</P>
|
||||
<P>mostly internally</P>
|
||||
<P>mask is either RELATIVE_NONE or RELATIVE_NONE|VFS_REAL,</P>
|
||||
<P>and is used internally</P>
|
||||
<P>outside is boolean, True if $relatives contains VFS_REAL</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function path_parts ($string, $relatives = array (RELATIVE_CURRENT), $object = True)
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: getabsolutepath"></A> <A NAME="ss5.11">5.11</A> <A HREF="vfs.html#toc5.11">getabsolutepath</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: get the absolute path</P>
|
||||
<P>param: $target defaults to False, directory/file to get path of,
|
||||
relative to $relatives[0]</P>
|
||||
<P>param: $mask Relativity bitmask (see RELATIVE_ defines). RELATIVE_CURRENT
|
||||
means use $this->relative</P>
|
||||
<P>param: $fake Returns the "fake" path, ie /home/user/dir/file
|
||||
(not always possible. use path_parts () instead)</P>
|
||||
<P>result: $basedir Full fake or real path</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function getabsolutepath ($target = False, $relatives = array (RELATIVE_CURRENT), $fake = True)
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: cd"></A> <A NAME="ss5.12">5.12</A> <A HREF="vfs.html#toc5.12">cd</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Change directory</P>
|
||||
<P>discussion: To cd to the files root "/", use cd ("/",
|
||||
False, array (RELATIVE_NONE));</P>
|
||||
<P>param: $target default "/". directory to cd into. if
|
||||
"/" and $relative is True, uses "/home/<working_lid>";</P>
|
||||
<P>param: $relative default True/relative means add target to current
|
||||
path, else pass $relative as mask to getabsolutepath()</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function cd ($target = "/", $relative = True, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: pwd"></A> <A NAME="ss5.13">5.13</A> <A HREF="vfs.html#toc5.13">pwd</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: current working dir</P>
|
||||
<P>param: $full default True returns full fake path, else just the
|
||||
extra dirs (false strips the leading /)</P>
|
||||
<P>result: $currentdir currentdir</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function pwd ($full = True)
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: read"></A> <A NAME="ss5.14">5.14</A> <A HREF="vfs.html#toc5.14">read</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: return file contents</P>
|
||||
<P>param: $file filename</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: $contents Contents of $file, or False if file cannot
|
||||
be read</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function read ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: write"></A> <A NAME="ss5.15">5.15</A> <A HREF="vfs.html#toc5.15">write</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: write to a file</P>
|
||||
<P>param: $file file name</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>param: $contents contents</P>
|
||||
<P>result: Boolean True/False</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function write ($file, $relatives = array (RELATIVE_CURRENT), $contents)
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: touch"></A> <A NAME="ss5.16">5.16</A> <A HREF="vfs.html#toc5.16">touch</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Create blank file $file or set the modification time and
|
||||
modified by of $file to current time and user</P>
|
||||
<P>param: $file File to touch or set modifies</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: Boolean True/False</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function touch ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: cp"></A> <A NAME="ss5.17">5.17</A> <A HREF="vfs.html#toc5.17">cp</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: copy file</P>
|
||||
<P>param: $from from file/directory</P>
|
||||
<P>param: $to to file/directory</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: boolean True/False</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function cp ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: mv"></A> <A NAME="ss5.18">5.18</A> <A HREF="vfs.html#toc5.18">mv</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: move file/directory</P>
|
||||
<P>param: $from from file/directory</P>
|
||||
<P>param: $to to file/directory</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: boolean True/False</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function mv ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: move"></A> <A NAME="ss5.19">5.19</A> <A HREF="vfs.html#toc5.19">move</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: shortcut to mv</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function move ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: rm"></A> <A NAME="ss5.20">5.20</A> <A HREF="vfs.html#toc5.20">rm</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: delete file/directory</P>
|
||||
<P>param: $string file/directory to delete</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: boolean True/False</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function rm ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: delete"></A> <A NAME="ss5.21">5.21</A> <A HREF="vfs.html#toc5.21">delete</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: shortcut to rm</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function delete ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: mkdir"></A> <A NAME="ss5.22">5.22</A> <A HREF="vfs.html#toc5.22">mkdir</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: make a new directory</P>
|
||||
<P>param: $dir Directory name</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: boolean True on success</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function mkdir ($dir, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: set_attributes"></A> <A NAME="ss5.23">5.23</A> <A HREF="vfs.html#toc5.23">set_attributes</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Update database entry for $file with the attributes in
|
||||
$attributes</P>
|
||||
<P>param: $file file/directory to update</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>param: $attributes keyed array of attributes. key is attribute
|
||||
name, value is attribute value</P>
|
||||
<P>result: Boolean True/False</P>
|
||||
<P>discussion: Valid attributes are:</P>
|
||||
<P>owner_id</P>
|
||||
<P>createdby_id</P>
|
||||
<P>modifiedby_id</P>
|
||||
<P>created</P>
|
||||
<P>modified</P>
|
||||
<P>size</P>
|
||||
<P>mime_type</P>
|
||||
<P>deleteable</P>
|
||||
<P>comment</P>
|
||||
<P>app</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function set_attributes ($file, $relatives = array (RELATIVE_CURRENT), $attributes = array ())
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: correct_attributes"></A> <A NAME="ss5.24">5.24</A> <A HREF="vfs.html#toc5.24">correct_attributes</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Set the correct attributes for $string (e.g. owner)</P>
|
||||
<P>param: $string File/directory to correct attributes of</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: Boolean True/False</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function correct_attributes ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: file_type"></A> <A NAME="ss5.25">5.25</A> <A HREF="vfs.html#toc5.25">file_type</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: return file/dir type (MIME or other)</P>
|
||||
<P>param: $file File or directory path (/home/user/dir/dir2/dir3, /home/user/dir/dir2/file)</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: MIME type, "Directory", or nothing if MIME type is not
|
||||
known</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function file_type ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: file_exists"></A> <A NAME="ss5.26">5.26</A> <A HREF="vfs.html#toc5.26">file_exists</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: check if file/directory exists</P>
|
||||
<P>param: $string file/directory to check existance of</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: Boolean True/False</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function file_exists ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: checkperms"></A> <A NAME="ss5.27">5.27</A> <A HREF="vfs.html#toc5.27">checkperms</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: Check if you have write access to create files in $dir</P>
|
||||
<P>discussion: This isn't perfect, because vfs->touch () returns True even</P>
|
||||
<P>if only the database entry worked. ACLs need to be</P>
|
||||
<P>implemented for better permission checking. It's</P>
|
||||
<P>also pretty slow, so I wouldn't recommend using it</P>
|
||||
<P>often</P>
|
||||
<P>param: $dir Directory to check access of</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>result: Boolean True/False</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function checkperms ($dir, $relatives = array (RELATIVE_CURRENT))
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: ls"></A> <A NAME="ss5.28">5.28</A> <A HREF="vfs.html#toc5.28">ls</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: get directory listing</P>
|
||||
<P>discussion: Note: the entries are not guaranteed to be returned in any
|
||||
logical order</P>
|
||||
<P>param: $dir Directory</P>
|
||||
<P>param: $relatives Relativity array</P>
|
||||
<P>param: $checksubdirs Boolean, recursively list all sub directories
|
||||
as well?</P>
|
||||
<P>param: $mime_type Only return entries matching MIME-type $mime_type.
|
||||
Can be "Directory" or "\" for those without MIME
|
||||
types</P>
|
||||
<P>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'</P>
|
||||
<P>result: array of arrays. Subarrays contain full info for each file/dir.</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function ls ($dir = False, $relatives = array (RELATIVE_CURRENT), $checksubdirs = True, $mime_type = False, $nofiles = False)
|
||||
</PRE>
|
||||
</P>
|
||||
<H2><A NAME="sec: dir"></A> <A NAME="ss5.29">5.29</A> <A HREF="vfs.html#toc5.29">dir</A>
|
||||
</H2>
|
||||
|
||||
<P>abstract: shortcut to ls</P>
|
||||
<P>
|
||||
<PRE>
|
||||
function dir ($dir = False, $relatives = array (RELATIVE_CURRENT), $checksubdirs = True, $mime_type = False, $nofiles = False)
|
||||
</PRE>
|
||||
</P>
|
||||
<HR>
|
||||
<A HREF="vfs-6.html">Next</A>
|
||||
<A HREF="vfs-4.html">Previous</A>
|
||||
<A HREF="vfs.html#toc5">Contents</A>
|
||||
</BODY>
|
||||
</HTML>
|
||||
130
phpgwapi/doc/vfs/vfs-6.html
Normal file
130
phpgwapi/doc/vfs/vfs-6.html
Normal file
@ -0,0 +1,130 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.7.4">
|
||||
<TITLE>phpgwapi - VFS Class: Notes</TITLE>
|
||||
<LINK HREF="vfs-5.html" REL=previous>
|
||||
<LINK HREF="vfs.html#toc6" REL=contents>
|
||||
</HEAD>
|
||||
<BODY>
|
||||
Next
|
||||
<A HREF="vfs-5.html">Previous</A>
|
||||
<A HREF="vfs.html#toc6">Contents</A>
|
||||
<HR>
|
||||
<H2><A NAME="sec:notes"></A> <A NAME="s6">6.</A> <A HREF="vfs.html#toc6">Notes</A></H2>
|
||||
|
||||
<H2><A NAME="sec:database"></A> <A NAME="ss6.1">6.1</A> <A HREF="vfs.html#toc6.1">Database</A>
|
||||
</H2>
|
||||
|
||||
<P>Data about the files and directories within the virtual root is kept in
|
||||
the SQL database. Currently, this information includes:</P>
|
||||
<P>
|
||||
<UL>
|
||||
<LI>File ID (used internally, primary key for table)</LI>
|
||||
<LI>Owner ID (phpGW account_id)</LI>
|
||||
<LI>Created by ID (phpGW account_id)</LI>
|
||||
<LI>Modified by ID (phpGW account_id)</LI>
|
||||
<LI>Created (date)</LI>
|
||||
<LI>Modified (date)</LI>
|
||||
<LI>Size (bytes)</LI>
|
||||
<LI>MIME type</LI>
|
||||
<LI>Deleteable (Y/N/Other?)</LI>
|
||||
<LI>Comment</LI>
|
||||
<LI>App (appname of application that created the file)</LI>
|
||||
<LI>Directory (directory the file or directory is in)</LI>
|
||||
<LI>Name (name of file or directory)</LI>
|
||||
</UL>
|
||||
</P>
|
||||
<P>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.</P>
|
||||
|
||||
|
||||
<P>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.</P>
|
||||
<H2><A NAME="sec:acl_support"></A> <A NAME="ss6.2">6.2</A> <A HREF="vfs.html#toc6.2">ACL support</A>
|
||||
</H2>
|
||||
|
||||
<P>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:</P>
|
||||
<P>
|
||||
<PRE>
|
||||
###
|
||||
# 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;
|
||||
}
|
||||
}
|
||||
</PRE>
|
||||
</P>
|
||||
<P>You should also check if the group has access to your appilcation.</P>
|
||||
<H2><A NAME="sec:function_aliases"></A> <A NAME="ss6.3">6.3</A> <A HREF="vfs.html#toc6.3">Function aliases</A>
|
||||
</H2>
|
||||
|
||||
<P>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):</P>
|
||||
<P>
|
||||
<UL>
|
||||
<LI>copy -> cp</LI>
|
||||
<LI>move -> rm</LI>
|
||||
<LI>delete -> rm</LI>
|
||||
<LI>dir -> ls</LI>
|
||||
</UL>
|
||||
</P>
|
||||
<H2><A NAME="sec:fakebase"></A> <A NAME="ss6.4">6.4</A> <A HREF="vfs.html#toc6.4">Fakebase directory (changing /home)</A>
|
||||
</H2>
|
||||
|
||||
<P>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 <EM>before</EM> 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. <EM>Application programmers need to recognize
|
||||
that /home is not absolute, and use $phpgw->vfs->fakebase instead</EM>.
|
||||
I suggest setting $fakebase = $phpgw->vfs->fakebase; right
|
||||
off the bat to keep things neater.</P>
|
||||
<HR>
|
||||
Next
|
||||
<A HREF="vfs-5.html">Previous</A>
|
||||
<A HREF="vfs.html#toc6">Contents</A>
|
||||
</BODY>
|
||||
</HTML>
|
||||
94
phpgwapi/doc/vfs/vfs.html
Normal file
94
phpgwapi/doc/vfs/vfs.html
Normal file
@ -0,0 +1,94 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.7.4">
|
||||
<TITLE>phpgwapi - VFS Class</TITLE>
|
||||
<LINK HREF="vfs-1.html" REL=next>
|
||||
|
||||
|
||||
</HEAD>
|
||||
<BODY>
|
||||
<A HREF="vfs-1.html">Next</A>
|
||||
Previous
|
||||
Contents
|
||||
<HR>
|
||||
<H1>phpgwapi - VFS Class</H1>
|
||||
|
||||
<H2>Jason Wies</H2>June 2001
|
||||
<HR>
|
||||
<EM>The VFS, or Virtual File System, handles all file system activity for phpGroupWare.</EM>
|
||||
<HR>
|
||||
<P>
|
||||
<H2><A NAME="toc1">1.</A> <A HREF="vfs-1.html">Introduction and Purpose</A></H2>
|
||||
|
||||
<P>
|
||||
<H2><A NAME="toc2">2.</A> <A HREF="vfs-2.html">Basics</A></H2>
|
||||
|
||||
<UL>
|
||||
<LI><A NAME="toc2.1">2.1</A> <A HREF="vfs-2.html#ss2.1">Prerequisites</A>
|
||||
<LI><A NAME="toc2.2">2.2</A> <A HREF="vfs-2.html#ss2.2">Concepts</A>
|
||||
</UL>
|
||||
<P>
|
||||
<H2><A NAME="toc3">3.</A> <A HREF="vfs-3.html">Basic Functions</A></H2>
|
||||
|
||||
<UL>
|
||||
<LI><A NAME="toc3.1">3.1</A> <A HREF="vfs-3.html#ss3.1">path_parts ()</A>
|
||||
<LI><A NAME="toc3.2">3.2</A> <A HREF="vfs-3.html#ss3.2">cd ()</A>
|
||||
</UL>
|
||||
<P>
|
||||
<H2><A NAME="toc4">4.</A> <A HREF="vfs-4.html">Relativity</A></H2>
|
||||
|
||||
<UL>
|
||||
<LI><A NAME="toc4.1">4.1</A> <A HREF="vfs-4.html#ss4.1">What is it and how does it work?</A>
|
||||
<LI><A NAME="toc4.2">4.2</A> <A HREF="vfs-4.html#ss4.2">Complete List</A>
|
||||
<LI><A NAME="toc4.3">4.3</A> <A HREF="vfs-4.html#ss4.3">Defaults</A>
|
||||
</UL>
|
||||
<P>
|
||||
<H2><A NAME="toc5">5.</A> <A HREF="vfs-5.html">Function reference</A></H2>
|
||||
|
||||
<UL>
|
||||
<LI><A NAME="toc5.1">5.1</A> <A HREF="vfs-5.html#ss5.1">About</A>
|
||||
<LI><A NAME="toc5.2">5.2</A> <A HREF="vfs-5.html#ss5.2">class vfs</A>
|
||||
<LI><A NAME="toc5.3">5.3</A> <A HREF="vfs-5.html#ss5.3">class path_class</A>
|
||||
<LI><A NAME="toc5.4">5.4</A> <A HREF="vfs-5.html#ss5.4">vfs</A>
|
||||
<LI><A NAME="toc5.5">5.5</A> <A HREF="vfs-5.html#ss5.5">set_relative</A>
|
||||
<LI><A NAME="toc5.6">5.6</A> <A HREF="vfs-5.html#ss5.6">get_relative</A>
|
||||
<LI><A NAME="toc5.7">5.7</A> <A HREF="vfs-5.html#ss5.7">sanitize</A>
|
||||
<LI><A NAME="toc5.8">5.8</A> <A HREF="vfs-5.html#ss5.8">securitycheck</A>
|
||||
<LI><A NAME="toc5.9">5.9</A> <A HREF="vfs-5.html#ss5.9">db_clean</A>
|
||||
<LI><A NAME="toc5.10">5.10</A> <A HREF="vfs-5.html#ss5.10">path_parts</A>
|
||||
<LI><A NAME="toc5.11">5.11</A> <A HREF="vfs-5.html#ss5.11">getabsolutepath</A>
|
||||
<LI><A NAME="toc5.12">5.12</A> <A HREF="vfs-5.html#ss5.12">cd</A>
|
||||
<LI><A NAME="toc5.13">5.13</A> <A HREF="vfs-5.html#ss5.13">pwd</A>
|
||||
<LI><A NAME="toc5.14">5.14</A> <A HREF="vfs-5.html#ss5.14">read</A>
|
||||
<LI><A NAME="toc5.15">5.15</A> <A HREF="vfs-5.html#ss5.15">write</A>
|
||||
<LI><A NAME="toc5.16">5.16</A> <A HREF="vfs-5.html#ss5.16">touch</A>
|
||||
<LI><A NAME="toc5.17">5.17</A> <A HREF="vfs-5.html#ss5.17">cp</A>
|
||||
<LI><A NAME="toc5.18">5.18</A> <A HREF="vfs-5.html#ss5.18">mv</A>
|
||||
<LI><A NAME="toc5.19">5.19</A> <A HREF="vfs-5.html#ss5.19">move</A>
|
||||
<LI><A NAME="toc5.20">5.20</A> <A HREF="vfs-5.html#ss5.20">rm</A>
|
||||
<LI><A NAME="toc5.21">5.21</A> <A HREF="vfs-5.html#ss5.21">delete</A>
|
||||
<LI><A NAME="toc5.22">5.22</A> <A HREF="vfs-5.html#ss5.22">mkdir</A>
|
||||
<LI><A NAME="toc5.23">5.23</A> <A HREF="vfs-5.html#ss5.23">set_attributes</A>
|
||||
<LI><A NAME="toc5.24">5.24</A> <A HREF="vfs-5.html#ss5.24">correct_attributes</A>
|
||||
<LI><A NAME="toc5.25">5.25</A> <A HREF="vfs-5.html#ss5.25">file_type</A>
|
||||
<LI><A NAME="toc5.26">5.26</A> <A HREF="vfs-5.html#ss5.26">file_exists</A>
|
||||
<LI><A NAME="toc5.27">5.27</A> <A HREF="vfs-5.html#ss5.27">checkperms</A>
|
||||
<LI><A NAME="toc5.28">5.28</A> <A HREF="vfs-5.html#ss5.28">ls</A>
|
||||
<LI><A NAME="toc5.29">5.29</A> <A HREF="vfs-5.html#ss5.29">dir</A>
|
||||
</UL>
|
||||
<P>
|
||||
<H2><A NAME="toc6">6.</A> <A HREF="vfs-6.html">Notes</A></H2>
|
||||
|
||||
<UL>
|
||||
<LI><A NAME="toc6.1">6.1</A> <A HREF="vfs-6.html#ss6.1">Database</A>
|
||||
<LI><A NAME="toc6.2">6.2</A> <A HREF="vfs-6.html#ss6.2">ACL support</A>
|
||||
<LI><A NAME="toc6.3">6.3</A> <A HREF="vfs-6.html#ss6.3">Function aliases</A>
|
||||
<LI><A NAME="toc6.4">6.4</A> <A HREF="vfs-6.html#ss6.4">Fakebase directory (changing /home)</A>
|
||||
</UL>
|
||||
<HR>
|
||||
<A HREF="vfs-1.html">Next</A>
|
||||
Previous
|
||||
Contents
|
||||
</BODY>
|
||||
</HTML>
|
||||
1933
phpgwapi/doc/vfs/vfs.lyx
Normal file
1933
phpgwapi/doc/vfs/vfs.lyx
Normal file
File diff suppressed because it is too large
Load Diff
1148
phpgwapi/doc/vfs/vfs.sgml
Normal file
1148
phpgwapi/doc/vfs/vfs.sgml
Normal file
File diff suppressed because it is too large
Load Diff
910
phpgwapi/doc/vfs/vfs.txt
Normal file
910
phpgwapi/doc/vfs/vfs.txt
Normal file
@ -0,0 +1,910 @@
|
||||
|
||||
|
||||
phpgwapi - VFS Class
|
||||
|
||||
Jason Wies
|
||||
|
||||
June 2001
|
||||
|
||||
Abstract
|
||||
|
||||
The VFS, or Virtual File System, handles all file system activity for
|
||||
phpGroupWare.
|
||||
|
||||
1 Introduction and Purpose<sec:introduction>
|
||||
|
||||
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.
|
||||
|
||||
2 Basics<sec:basics>
|
||||
|
||||
2.1 Prerequisites<sec:prerequisites>
|
||||
|
||||
You must explicitly enable the VFS class. To do this, set "enable_vfs_class"
|
||||
to True in $phpgw_info["flags"]. An example:
|
||||
|
||||
$phpgw_info["flags"] = array("currentapp" => "phpwebhosting",
|
||||
|
||||
"noheader" => False,
|
||||
|
||||
"noappheader" => False,
|
||||
|
||||
"enable_vfs_class" => True,
|
||||
|
||||
"enable_browser_class" => True);
|
||||
|
||||
2.2 Concepts<sec: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
|
||||
|
||||
$phpgw->vfs->mv ("file1", "dir/file2");
|
||||
|
||||
$phpgw->vfs->mv ("dir1", "dir/dir1");
|
||||
|
||||
$phpgw->vfs->rm ("file");
|
||||
|
||||
$phpgw->vfs->rm ("dir");
|
||||
|
||||
All work as you would except them to. The major exception is:
|
||||
|
||||
$phpgw->vfs->touch ("file");
|
||||
|
||||
vs.
|
||||
|
||||
$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.
|
||||
|
||||
* You should never have to know the real path of files
|
||||
|
||||
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));
|
||||
|
||||
you might use
|
||||
|
||||
$phpgw->vfs->cp ("/home/user/file1", "/home/user/file2", array (RELATIVE_NONE,
|
||||
RELATIVE_NONE));
|
||||
|
||||
(We'll get to the RELATIVE's in a minute.)
|
||||
|
||||
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.
|
||||
|
||||
3 Basic Functions<sec:basic_functions>
|
||||
|
||||
These are two functions you'll need to know before we get into relativity.
|
||||
|
||||
3.1 path_parts ()<sec: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)
|
||||
|
||||
$string is the path you want to translate, $relatives is the standard
|
||||
relativity array, and $object specifies how you would like the return
|
||||
value: if $object is True, an object will be returned; if $object
|
||||
is False, an array will be returned. I think you'll find the object
|
||||
easier to deal with, and we'll be using it throughout this document.
|
||||
The most important returned values (but not all) for path_parts ()
|
||||
are:
|
||||
|
||||
fake_full_path
|
||||
|
||||
fake_leading_dirs
|
||||
|
||||
fake_extra_path
|
||||
|
||||
fake_name
|
||||
|
||||
real_full_path
|
||||
|
||||
real_leading_dirs
|
||||
|
||||
real_extra_path
|
||||
|
||||
real_name
|
||||
|
||||
Just like you would think, fake_full_path contains the full virtual
|
||||
path of $string, and real_full_path contains the full real path of
|
||||
$string. The fake_name and real_name variables should always be the
|
||||
same, and contain the final file or directory name. The leading_dirs
|
||||
contain everything except the name, and the extra_path is everything
|
||||
from the / before "home" to the end of the leading_dirs. To better
|
||||
illustrate, here is an example:
|
||||
|
||||
$p = $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
|
||||
|
||||
* $p->fake_extra_path - home/jason/dir
|
||||
|
||||
* $p->fake_name - file
|
||||
|
||||
* $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
|
||||
|
||||
* $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].
|
||||
|
||||
3.2 cd ()<sec: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))
|
||||
|
||||
$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 */
|
||||
|
||||
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
|
||||
().
|
||||
|
||||
Now you're ready for relativity.
|
||||
|
||||
4 Relativity<sec: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.
|
||||
|
||||
4.1 What is it and how does it work?
|
||||
|
||||
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.
|
||||
|
||||
$phpgw->vfs->mv ("logo.png", "", array (RELATIVE_USER, 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:
|
||||
|
||||
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");
|
||||
|
||||
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):
|
||||
|
||||
rename ("/var/www/phpgroupware/tmp/0ak5adftgh7/jX42sC9M", "/var/www/phpgroupware/files/home/users/jason/attachments/actual_name.ext");
|
||||
|
||||
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:
|
||||
|
||||
$phpgw->vfs->write ("file.name~", array (RELATIVE_USER_APP), $contents);
|
||||
|
||||
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.
|
||||
|
||||
4.2 Complete List<sec:relatives_complete_list>
|
||||
|
||||
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
|
||||
|
||||
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_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)
|
||||
|
||||
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<sec:relatives_defaults>
|
||||
|
||||
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);
|
||||
|
||||
$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));
|
||||
|
||||
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<sec:function_reference>
|
||||
|
||||
5.1 About<sec:function_reference_about>
|
||||
|
||||
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<sec: class vfs>
|
||||
|
||||
abstract: virtual file system
|
||||
|
||||
description: Authors: Zone, Seek3r
|
||||
|
||||
5.3 class path_class<sec: class path_class>
|
||||
|
||||
abstract: helper class for path_parts
|
||||
|
||||
5.4 vfs<sec: vfs>
|
||||
|
||||
abstract: constructor, sets up variables
|
||||
|
||||
function vfs ()
|
||||
|
||||
5.5 set_relative<sec: set_relative>
|
||||
|
||||
abstract: Set path relativity
|
||||
|
||||
param: $mask Relative bitmask (see RELATIVE_ defines)
|
||||
|
||||
function set_relative ($mask)
|
||||
|
||||
5.6 get_relative<sec: get_relative>
|
||||
|
||||
abstract: Return relativity bitmask
|
||||
|
||||
discussion: Returns relativity bitmask, or the default of "completely
|
||||
relative" if unset
|
||||
|
||||
function get_relative ()
|
||||
|
||||
5.7 sanitize<sec: sanitize>
|
||||
|
||||
abstract: Removes leading .'s from $string
|
||||
|
||||
discussion: You should not pass all filenames through sanitize () unless
|
||||
you plan on rejecting
|
||||
|
||||
.files. Instead, pass the name through securitycheck () first, and
|
||||
if it fails,
|
||||
|
||||
pass it through sanitize
|
||||
|
||||
param: $string string to sanitize
|
||||
|
||||
result: $string without it's leading .'s
|
||||
|
||||
function sanitize ($string)
|
||||
|
||||
5.8 securitycheck<sec: securitycheck>
|
||||
|
||||
abstract: Security check function
|
||||
|
||||
discussion: Checks for basic violations such as ..
|
||||
|
||||
If securitycheck () fails, run your string through vfs->sanitize ()
|
||||
|
||||
param: $string string to check security of
|
||||
|
||||
result: Boolean True/False. True means secure, False means insecure
|
||||
|
||||
function securitycheck ($string)
|
||||
|
||||
5.9 db_clean<sec: db_clean>
|
||||
|
||||
abstract: Clean $string for use in database queries
|
||||
|
||||
param: $string String to clean
|
||||
|
||||
result: Cleaned version of $string
|
||||
|
||||
function db_clean ($string)
|
||||
|
||||
5.10 path_parts<sec: path_parts>
|
||||
|
||||
abstract: take a real or fake pathname and return an array of its component
|
||||
parts
|
||||
|
||||
param: $string full real or fake path
|
||||
|
||||
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
|
||||
|
||||
discussion: Returned values are:
|
||||
|
||||
mask
|
||||
|
||||
outside
|
||||
|
||||
fake_full_path
|
||||
|
||||
fake_leading_dirs
|
||||
|
||||
fake_extra_path
|
||||
|
||||
fake_name
|
||||
|
||||
real_full_path
|
||||
|
||||
real_leading_dirs
|
||||
|
||||
real_extra_path
|
||||
|
||||
real_name
|
||||
|
||||
fake_full_path_clean
|
||||
|
||||
fake_leading_dirs_clean
|
||||
|
||||
fake_extra_path_clean
|
||||
|
||||
fake_name_clean
|
||||
|
||||
real_full_path_clean
|
||||
|
||||
real_leading_dirs_clean
|
||||
|
||||
real_extra_path_clean
|
||||
|
||||
real_name_clean
|
||||
|
||||
"clean" values are run through vfs->db_clean () and
|
||||
|
||||
are safe for use in SQL queries that use key='value'
|
||||
|
||||
They should be used ONLY for SQL queries, so are used
|
||||
|
||||
mostly internally
|
||||
|
||||
mask is either RELATIVE_NONE or RELATIVE_NONE|VFS_REAL,
|
||||
|
||||
and is used internally
|
||||
|
||||
outside is boolean, True if $relatives contains VFS_REAL
|
||||
|
||||
function path_parts ($string, $relatives = array (RELATIVE_CURRENT),
|
||||
$object = True)
|
||||
|
||||
5.11 getabsolutepath<sec: getabsolutepath>
|
||||
|
||||
abstract: get the absolute path
|
||||
|
||||
param: $target defaults to False, directory/file to get path of, relative
|
||||
to $relatives[0]
|
||||
|
||||
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)
|
||||
|
||||
result: $basedir Full fake or real path
|
||||
|
||||
function getabsolutepath ($target = False, $relatives = array (RELATIVE_CURRENT),
|
||||
$fake = True)
|
||||
|
||||
5.12 cd<sec: cd>
|
||||
|
||||
abstract: Change directory
|
||||
|
||||
discussion: To cd to the files root "/", use cd ("/", False, array
|
||||
(RELATIVE_NONE));
|
||||
|
||||
param: $target default "/". directory to cd into. if "/" and $relative
|
||||
is True, uses "/home/<working_lid>";
|
||||
|
||||
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))
|
||||
|
||||
5.13 pwd<sec: pwd>
|
||||
|
||||
abstract: current working dir
|
||||
|
||||
param: $full default True returns full fake path, else just the extra
|
||||
dirs (false strips the leading /)
|
||||
|
||||
result: $currentdir currentdir
|
||||
|
||||
function pwd ($full = True)
|
||||
|
||||
5.14 read<sec: read>
|
||||
|
||||
abstract: return file contents
|
||||
|
||||
param: $file filename
|
||||
|
||||
param: $relatives Relativity array
|
||||
|
||||
result: $contents Contents of $file, or False if file cannot be read
|
||||
|
||||
function read ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
5.15 write<sec: write>
|
||||
|
||||
abstract: write to a file
|
||||
|
||||
param: $file file name
|
||||
|
||||
param: $relatives Relativity array
|
||||
|
||||
param: $contents contents
|
||||
|
||||
result: Boolean True/False
|
||||
|
||||
function write ($file, $relatives = array (RELATIVE_CURRENT), $contents)
|
||||
|
||||
5.16 touch<sec: touch>
|
||||
|
||||
abstract: Create blank file $file or set the modification time and
|
||||
modified by of $file to current time and user
|
||||
|
||||
param: $file File to touch or set modifies
|
||||
|
||||
param: $relatives Relativity array
|
||||
|
||||
result: Boolean True/False
|
||||
|
||||
function touch ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
5.17 cp<sec: cp>
|
||||
|
||||
abstract: copy file
|
||||
|
||||
param: $from from file/directory
|
||||
|
||||
param: $to to file/directory
|
||||
|
||||
param: $relatives Relativity array
|
||||
|
||||
result: boolean True/False
|
||||
|
||||
function cp ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
|
||||
5.18 mv<sec: mv>
|
||||
|
||||
abstract: move file/directory
|
||||
|
||||
param: $from from file/directory
|
||||
|
||||
param: $to to file/directory
|
||||
|
||||
param: $relatives Relativity array
|
||||
|
||||
result: boolean True/False
|
||||
|
||||
function mv ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
|
||||
5.19 move<sec: move>
|
||||
|
||||
abstract: shortcut to mv
|
||||
|
||||
function move ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
|
||||
5.20 rm<sec: rm>
|
||||
|
||||
abstract: delete file/directory
|
||||
|
||||
param: $string file/directory to delete
|
||||
|
||||
param: $relatives Relativity array
|
||||
|
||||
result: boolean True/False
|
||||
|
||||
function rm ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
5.21 delete<sec: delete>
|
||||
|
||||
abstract: shortcut to rm
|
||||
|
||||
function delete ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
5.22 mkdir<sec: mkdir>
|
||||
|
||||
abstract: make a new directory
|
||||
|
||||
param: $dir Directory name
|
||||
|
||||
param: $relatives Relativity array
|
||||
|
||||
result: boolean True on success
|
||||
|
||||
function mkdir ($dir, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
5.23 set_attributes<sec: set_attributes>
|
||||
|
||||
abstract: Update database entry for $file with the attributes in $attributes
|
||||
|
||||
param: $file file/directory to update
|
||||
|
||||
param: $relatives Relativity array
|
||||
|
||||
param: $attributes keyed array of attributes. key is attribute name,
|
||||
value is attribute value
|
||||
|
||||
result: Boolean True/False
|
||||
|
||||
discussion: Valid attributes are:
|
||||
|
||||
owner_id
|
||||
|
||||
createdby_id
|
||||
|
||||
modifiedby_id
|
||||
|
||||
created
|
||||
|
||||
modified
|
||||
|
||||
size
|
||||
|
||||
mime_type
|
||||
|
||||
deleteable
|
||||
|
||||
comment
|
||||
|
||||
app
|
||||
|
||||
function set_attributes ($file, $relatives = array (RELATIVE_CURRENT),
|
||||
$attributes = array ())
|
||||
|
||||
5.24 correct_attributes<sec: correct_attributes>
|
||||
|
||||
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))
|
||||
|
||||
5.25 file_type<sec: file_type>
|
||||
|
||||
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))
|
||||
|
||||
5.26 file_exists<sec: file_exists>
|
||||
|
||||
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))
|
||||
|
||||
5.27 checkperms<sec: checkperms>
|
||||
|
||||
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))
|
||||
|
||||
5.28 ls<sec: ls>
|
||||
|
||||
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)
|
||||
|
||||
5.29 dir<sec: dir>
|
||||
|
||||
abstract: shortcut to ls
|
||||
|
||||
function dir ($dir = False, $relatives = array (RELATIVE_CURRENT),
|
||||
$checksubdirs = True, $mime_type = False, $nofiles = False)
|
||||
|
||||
6 Notes<sec:notes>
|
||||
|
||||
6.1 Database<sec:database>
|
||||
|
||||
Data about the files and directories within the virtual root is kept
|
||||
in the SQL database. Currently, this information includes:
|
||||
|
||||
* File ID (used internally, primary key for table)
|
||||
|
||||
* Owner ID (phpGW account_id)
|
||||
|
||||
* Created by ID (phpGW account_id)
|
||||
|
||||
* Modified by ID (phpGW account_id)
|
||||
|
||||
* Created (date)
|
||||
|
||||
* Modified (date)
|
||||
|
||||
* Size (bytes)
|
||||
|
||||
* MIME type
|
||||
|
||||
* Deleteable (Y/N/Other?)
|
||||
|
||||
* Comment
|
||||
|
||||
* App (appname of application that created the file)
|
||||
|
||||
* Directory (directory the file or directory is in)
|
||||
|
||||
* 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.
|
||||
|
||||
6.2 ACL support<sec: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:
|
||||
|
||||
###
|
||||
|
||||
# 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.
|
||||
|
||||
6.3 Function aliases<sec:function_aliases>
|
||||
|
||||
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
|
||||
|
||||
* delete -> rm
|
||||
|
||||
* dir -> ls
|
||||
|
||||
6.4 Fakebase directory (changing /home)<sec:fakebase>
|
||||
|
||||
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.
|
||||
636
phpgwapi/doc/vfs/vfs_functions.lyx
Normal file
636
phpgwapi/doc/vfs/vfs_functions.lyx
Normal file
@ -0,0 +1,636 @@
|
||||
\lyxformat 2.16
|
||||
\textclass linuxdoc
|
||||
\language default
|
||||
\inputencoding latin1
|
||||
\fontscheme default
|
||||
\graphics default
|
||||
\paperfontsize default
|
||||
\spacing single
|
||||
\papersize Default
|
||||
\paperpackage a4
|
||||
\use_geometry 0
|
||||
\use_amsmath 0
|
||||
\paperorientation portrait
|
||||
\secnumdepth 2
|
||||
\tocdepth 2
|
||||
\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
|
||||
VFS class functions
|
||||
\layout Author
|
||||
|
||||
Jason Wies
|
||||
|
||||
\layout Date
|
||||
|
||||
June 2001
|
||||
|
||||
\layout Abstract
|
||||
|
||||
|
||||
|
||||
\layout Section
|
||||
|
||||
VFS class functions
|
||||
|
||||
\layout Subsection
|
||||
class vfs
|
||||
\begin_inset LatexCommand \label{sec: class vfs}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: virtual file system
|
||||
|
||||
\layout Standard
|
||||
description: Authors: Zone, Seek3r
|
||||
|
||||
\layout Subsection
|
||||
class path_class
|
||||
\begin_inset LatexCommand \label{sec: class path_class}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: helper class for path_parts
|
||||
|
||||
\layout Subsection
|
||||
vfs
|
||||
\begin_inset LatexCommand \label{sec: vfs}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: constructor, sets up variables
|
||||
|
||||
\layout Verbatim
|
||||
function vfs ()
|
||||
|
||||
\layout Subsection
|
||||
set_relative
|
||||
\begin_inset LatexCommand \label{sec: set_relative}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Set path relativity
|
||||
|
||||
\layout Standard
|
||||
param: $mask Relative bitmask (see RELATIVE_ defines)
|
||||
|
||||
\layout Verbatim
|
||||
function set_relative ($mask)
|
||||
|
||||
\layout Subsection
|
||||
get_relative
|
||||
\begin_inset LatexCommand \label{sec: get_relative}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Return relativity bitmask
|
||||
|
||||
\layout Standard
|
||||
discussion: Returns relativity bitmask, or the default of "completely relative" if unset
|
||||
|
||||
\layout Verbatim
|
||||
function get_relative ()
|
||||
|
||||
\layout Subsection
|
||||
sanitize
|
||||
\begin_inset LatexCommand \label{sec: sanitize}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Removes leading .'s from $string
|
||||
|
||||
\layout Standard
|
||||
discussion: You should not pass all filenames through sanitize () unless you plan on rejecting\layout Standard
|
||||
.files. Instead, pass the name through securitycheck () first, and if it fails,\layout Standard
|
||||
pass it through sanitize
|
||||
|
||||
\layout Standard
|
||||
param: $string string to sanitize
|
||||
|
||||
\layout Standard
|
||||
result: $string without it's leading .'s
|
||||
|
||||
\layout Verbatim
|
||||
function sanitize ($string)
|
||||
|
||||
\layout Subsection
|
||||
securitycheck
|
||||
\begin_inset LatexCommand \label{sec: securitycheck}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Security check function
|
||||
|
||||
\layout Standard
|
||||
discussion: Checks for basic violations such as ..\layout Standard
|
||||
If securitycheck () fails, run your string through vfs->sanitize ()
|
||||
|
||||
\layout Standard
|
||||
param: $string string to check security of
|
||||
|
||||
\layout Standard
|
||||
result: Boolean True/False. True means secure, False means insecure
|
||||
|
||||
\layout Verbatim
|
||||
function securitycheck ($string)
|
||||
|
||||
\layout Subsection
|
||||
db_clean
|
||||
\begin_inset LatexCommand \label{sec: db_clean}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Clean $string for use in database queries
|
||||
|
||||
\layout Standard
|
||||
param: $string String to clean
|
||||
|
||||
\layout Standard
|
||||
result: Cleaned version of $string
|
||||
|
||||
\layout Verbatim
|
||||
function db_clean ($string)
|
||||
|
||||
\layout Subsection
|
||||
path_parts
|
||||
\begin_inset LatexCommand \label{sec: path_parts}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: take a real or fake pathname and return an array of its component parts
|
||||
|
||||
\layout Standard
|
||||
param: $string full real or fake path
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
param: $object True returns an object instead of an array
|
||||
|
||||
\layout Standard
|
||||
result: $rarray/$robject Array or object containing the fake and real component parts of the path
|
||||
|
||||
\layout Standard
|
||||
discussion: Returned values are:\layout Standard
|
||||
mask\layout Standard
|
||||
outside\layout Standard
|
||||
fake_full_path\layout Standard
|
||||
fake_leading_dirs\layout Standard
|
||||
fake_extra_path\layout Standard
|
||||
fake_name\layout Standard
|
||||
real_full_path\layout Standard
|
||||
real_leading_dirs\layout Standard
|
||||
real_extra_path\layout Standard
|
||||
real_name\layout Standard
|
||||
fake_full_path_clean\layout Standard
|
||||
fake_leading_dirs_clean\layout Standard
|
||||
fake_extra_path_clean\layout Standard
|
||||
fake_name_clean\layout Standard
|
||||
real_full_path_clean\layout Standard
|
||||
real_leading_dirs_clean\layout Standard
|
||||
real_extra_path_clean\layout Standard
|
||||
real_name_clean\layout Standard
|
||||
"clean" values are run through vfs->db_clean () and\layout Standard
|
||||
are safe for use in SQL queries that use key='value'\layout Standard
|
||||
They should be used ONLY for SQL queries, so are used\layout Standard
|
||||
mostly internally\layout Standard
|
||||
mask is either RELATIVE_NONE or RELATIVE_NONE|VFS_REAL,\layout Standard
|
||||
and is used internally\layout Standard
|
||||
outside is boolean, True if $relatives contains VFS_REAL
|
||||
|
||||
\layout Verbatim
|
||||
function path_parts ($string, $relatives = array (RELATIVE_CURRENT), $object = True)
|
||||
|
||||
\layout Subsection
|
||||
getabsolutepath
|
||||
\begin_inset LatexCommand \label{sec: getabsolutepath}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: get the absolute path
|
||||
|
||||
\layout Standard
|
||||
param: $target defaults to False, directory/file to get path of, relative to $relatives[0]
|
||||
|
||||
\layout Standard
|
||||
param: $mask Relativity bitmask (see RELATIVE_ defines). RELATIVE_CURRENT means use $this->relative
|
||||
|
||||
\layout Standard
|
||||
param: $fake Returns the "fake" path, ie /home/user/dir/file (not always possible. use path_parts () instead)
|
||||
|
||||
\layout Standard
|
||||
result: $basedir Full fake or real path
|
||||
|
||||
\layout Verbatim
|
||||
function getabsolutepath ($target = False, $relatives = array (RELATIVE_CURRENT), $fake = True)
|
||||
|
||||
\layout Subsection
|
||||
cd
|
||||
\begin_inset LatexCommand \label{sec: cd}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Change directory
|
||||
|
||||
\layout Standard
|
||||
discussion: To cd to the files root "/", use cd ("/", False, array (RELATIVE_NONE));
|
||||
|
||||
\layout Standard
|
||||
param: $target default "/". directory to cd into. if "/" and $relative is True, uses "/home/<working_lid>";
|
||||
|
||||
\layout Standard
|
||||
param: $relative default True/relative means add target to current path, else pass $relative as mask to getabsolutepath()
|
||||
|
||||
\layout Verbatim
|
||||
function cd ($target = "/", $relative = True, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
pwd
|
||||
\begin_inset LatexCommand \label{sec: pwd}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: current working dir
|
||||
|
||||
\layout Standard
|
||||
param: $full default True returns full fake path, else just the extra dirs (false strips the leading /)
|
||||
|
||||
\layout Standard
|
||||
result: $currentdir currentdir
|
||||
|
||||
\layout Verbatim
|
||||
function pwd ($full = True)
|
||||
|
||||
\layout Subsection
|
||||
read
|
||||
\begin_inset LatexCommand \label{sec: read}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: return file contents
|
||||
|
||||
\layout Standard
|
||||
param: $file filename
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: $contents Contents of $file, or False if file cannot be read
|
||||
|
||||
\layout Verbatim
|
||||
function read ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
write
|
||||
\begin_inset LatexCommand \label{sec: write}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: write to a file
|
||||
|
||||
\layout Standard
|
||||
param: $file file name
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
param: $contents contents
|
||||
|
||||
\layout Standard
|
||||
result: Boolean True/False
|
||||
|
||||
\layout Verbatim
|
||||
function write ($file, $relatives = array (RELATIVE_CURRENT), $contents)
|
||||
|
||||
\layout Subsection
|
||||
touch
|
||||
\begin_inset LatexCommand \label{sec: touch}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Create blank file $file or set the modification time and modified by of $file to current time and user
|
||||
|
||||
\layout Standard
|
||||
param: $file File to touch or set modifies
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: Boolean True/False
|
||||
|
||||
\layout Verbatim
|
||||
function touch ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
cp
|
||||
\begin_inset LatexCommand \label{sec: cp}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: copy file
|
||||
|
||||
\layout Standard
|
||||
param: $from from file/directory
|
||||
|
||||
\layout Standard
|
||||
param: $to to file/directory
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: boolean True/False
|
||||
|
||||
\layout Verbatim
|
||||
function cp ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
mv
|
||||
\begin_inset LatexCommand \label{sec: mv}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: move file/directory
|
||||
|
||||
\layout Standard
|
||||
param: $from from file/directory
|
||||
|
||||
\layout Standard
|
||||
param: $to to file/directory
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: boolean True/False
|
||||
|
||||
\layout Verbatim
|
||||
function mv ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
move
|
||||
\begin_inset LatexCommand \label{sec: move}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: shortcut to mv
|
||||
|
||||
\layout Verbatim
|
||||
function move ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
rm
|
||||
\begin_inset LatexCommand \label{sec: rm}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: delete file/directory
|
||||
|
||||
\layout Standard
|
||||
param: $string file/directory to delete
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: boolean True/False
|
||||
|
||||
\layout Verbatim
|
||||
function rm ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
delete
|
||||
\begin_inset LatexCommand \label{sec: delete}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: shortcut to rm
|
||||
|
||||
\layout Verbatim
|
||||
function delete ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
mkdir
|
||||
\begin_inset LatexCommand \label{sec: mkdir}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: make a new directory
|
||||
|
||||
\layout Standard
|
||||
param: $dir Directory name
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: boolean True on success
|
||||
|
||||
\layout Verbatim
|
||||
function mkdir ($dir, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
set_attributes
|
||||
\begin_inset LatexCommand \label{sec: set_attributes}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Update database entry for $file with the attributes in $attributes
|
||||
|
||||
\layout Standard
|
||||
param: $file file/directory to update
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
param: $attributes keyed array of attributes. key is attribute name, value is attribute value
|
||||
|
||||
\layout Standard
|
||||
result: Boolean True/False
|
||||
|
||||
\layout Standard
|
||||
discussion: Valid attributes are:\layout Standard
|
||||
owner_id\layout Standard
|
||||
createdby_id\layout Standard
|
||||
modifiedby_id\layout Standard
|
||||
created\layout Standard
|
||||
modified\layout Standard
|
||||
size\layout Standard
|
||||
mime_type\layout Standard
|
||||
deleteable\layout Standard
|
||||
comment\layout Standard
|
||||
app
|
||||
|
||||
\layout Verbatim
|
||||
function set_attributes ($file, $relatives = array (RELATIVE_CURRENT), $attributes = array ())
|
||||
|
||||
\layout Subsection
|
||||
correct_attributes
|
||||
\begin_inset LatexCommand \label{sec: correct_attributes}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Set the correct attributes for $string (e.g. owner)
|
||||
|
||||
\layout Standard
|
||||
param: $string File/directory to correct attributes of
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: Boolean True/False
|
||||
|
||||
\layout Verbatim
|
||||
function correct_attributes ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
file_type
|
||||
\begin_inset LatexCommand \label{sec: file_type}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: return file/dir type (MIME or other)
|
||||
|
||||
\layout Standard
|
||||
param: $file File or directory path (/home/user/dir/dir2/dir3, /home/user/dir/dir2/file)
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: MIME type, "Directory", or nothing if MIME type is not known
|
||||
|
||||
\layout Verbatim
|
||||
function file_type ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
file_exists
|
||||
\begin_inset LatexCommand \label{sec: file_exists}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: check if file/directory exists
|
||||
|
||||
\layout Standard
|
||||
param: $string file/directory to check existance of
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: Boolean True/False
|
||||
|
||||
\layout Verbatim
|
||||
function file_exists ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
checkperms
|
||||
\begin_inset LatexCommand \label{sec: checkperms}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: Check if you have write access to create files in $dir
|
||||
|
||||
\layout Standard
|
||||
discussion: This isn't perfect, because vfs->touch () returns True even\layout Standard
|
||||
if only the database entry worked. ACLs need to be\layout Standard
|
||||
implemented for better permission checking. It's\layout Standard
|
||||
also pretty slow, so I wouldn't recommend using it\layout Standard
|
||||
often
|
||||
|
||||
\layout Standard
|
||||
param: $dir Directory to check access of
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
result: Boolean True/False
|
||||
|
||||
\layout Verbatim
|
||||
function checkperms ($dir, $relatives = array (RELATIVE_CURRENT))
|
||||
|
||||
\layout Subsection
|
||||
ls
|
||||
\begin_inset LatexCommand \label{sec: ls}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: get directory listing
|
||||
|
||||
\layout Standard
|
||||
discussion: Note: the entries are not guaranteed to be returned in any logical order
|
||||
|
||||
\layout Standard
|
||||
param: $dir Directory
|
||||
|
||||
\layout Standard
|
||||
param: $relatives Relativity array
|
||||
|
||||
\layout Standard
|
||||
param: $checksubdirs Boolean, recursively list all sub directories as well?
|
||||
|
||||
\layout Standard
|
||||
param: $mime_type Only return entries matching MIME-type $mime_type. Can be "Directory" or "\ " for those without MIME types
|
||||
|
||||
\layout Standard
|
||||
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'
|
||||
|
||||
\layout Standard
|
||||
result: array of arrays. Subarrays contain full info for each file/dir.
|
||||
|
||||
\layout Verbatim
|
||||
function ls ($dir = False, $relatives = array (RELATIVE_CURRENT), $checksubdirs = True, $mime_type = False, $nofiles = False)
|
||||
|
||||
\layout Subsection
|
||||
dir
|
||||
\begin_inset LatexCommand \label{sec: dir}
|
||||
|
||||
\end_inset
|
||||
|
||||
\layout Standard
|
||||
abstract: shortcut to ls
|
||||
|
||||
\layout Verbatim
|
||||
function dir ($dir = False, $relatives = array (RELATIVE_CURRENT), $checksubdirs = True, $mime_type = False, $nofiles = False)
|
||||
\the_end
|
||||
636
phpgwapi/doc/vfs/vfs_functions.sgml
Normal file
636
phpgwapi/doc/vfs/vfs_functions.sgml
Normal file
@ -0,0 +1,636 @@
|
||||
<!doctype linuxdoc system>
|
||||
|
||||
<!-- LyX 1.1 created this file. For more info see http://www.lyx.org/ -->
|
||||
<article>
|
||||
<title>
|
||||
VFS class functions
|
||||
</title>
|
||||
<author>
|
||||
Jason Wies
|
||||
</author>
|
||||
<date>
|
||||
June 2001
|
||||
</date>
|
||||
<abstract>
|
||||
|
||||
</abstract>
|
||||
<sect>
|
||||
VFS class functions
|
||||
<sect1>
|
||||
class vfs<label id="sec: class vfs" >
|
||||
<p>
|
||||
abstract: virtual file system
|
||||
</p>
|
||||
<p>
|
||||
description: Authors: Zone, Seek3r
|
||||
</p>
|
||||
<sect1>
|
||||
class path_class<label id="sec: class path_class" >
|
||||
<p>
|
||||
abstract: helper class for path_parts
|
||||
</p>
|
||||
<sect1>
|
||||
vfs<label id="sec: vfs" >
|
||||
<p>
|
||||
abstract: constructor, sets up variables
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function vfs ()
|
||||
</verb>
|
||||
</p><sect1>
|
||||
set_relative<label id="sec: set_relative" >
|
||||
<p>
|
||||
abstract: Set path relativity
|
||||
</p>
|
||||
<p>
|
||||
param: $mask Relative bitmask (see RELATIVE_ defines)
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function set_relative ($mask)
|
||||
</verb>
|
||||
</p><sect1>
|
||||
get_relative<label id="sec: get_relative" >
|
||||
<p>
|
||||
abstract: Return relativity bitmask
|
||||
</p>
|
||||
<p>
|
||||
discussion: Returns relativity bitmask, or the default of "completely
|
||||
relative" if unset
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function get_relative ()
|
||||
</verb>
|
||||
</p><sect1>
|
||||
sanitize<label id="sec: sanitize" >
|
||||
<p>
|
||||
abstract: Removes leading .'s from $string
|
||||
</p>
|
||||
<p>
|
||||
discussion: You should not pass all filenames through sanitize () unless
|
||||
you plan on rejecting
|
||||
</p>
|
||||
<p>
|
||||
.files. Instead, pass the name through securitycheck () first, and if
|
||||
it fails,
|
||||
</p>
|
||||
<p>
|
||||
pass it through sanitize
|
||||
</p>
|
||||
<p>
|
||||
param: $string string to sanitize
|
||||
</p>
|
||||
<p>
|
||||
result: $string without it's leading .'s
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function sanitize ($string)
|
||||
</verb>
|
||||
</p><sect1>
|
||||
securitycheck<label id="sec: securitycheck" >
|
||||
<p>
|
||||
abstract: Security check function
|
||||
</p>
|
||||
<p>
|
||||
discussion: Checks for basic violations such as ..
|
||||
</p>
|
||||
<p>
|
||||
If securitycheck () fails, run your string through vfs->sanitize ()
|
||||
</p>
|
||||
<p>
|
||||
param: $string string to check security of
|
||||
</p>
|
||||
<p>
|
||||
result: Boolean True/False. True means secure, False means insecure
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function securitycheck ($string)
|
||||
</verb>
|
||||
</p><sect1>
|
||||
db_clean<label id="sec: db_clean" >
|
||||
<p>
|
||||
abstract: Clean $string for use in database queries
|
||||
</p>
|
||||
<p>
|
||||
param: $string String to clean
|
||||
</p>
|
||||
<p>
|
||||
result: Cleaned version of $string
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function db_clean ($string)
|
||||
</verb>
|
||||
</p><sect1>
|
||||
path_parts<label id="sec: path_parts" >
|
||||
<p>
|
||||
abstract: take a real or fake pathname and return an array of its component
|
||||
parts
|
||||
</p>
|
||||
<p>
|
||||
param: $string full real or fake path
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
param: $object True returns an object instead of an array
|
||||
</p>
|
||||
<p>
|
||||
result: $rarray/$robject Array or object containing the fake
|
||||
and real component parts of the path
|
||||
</p>
|
||||
<p>
|
||||
discussion: Returned values are:
|
||||
</p>
|
||||
<p>
|
||||
mask
|
||||
</p>
|
||||
<p>
|
||||
outside
|
||||
</p>
|
||||
<p>
|
||||
fake_full_path
|
||||
</p>
|
||||
<p>
|
||||
fake_leading_dirs
|
||||
</p>
|
||||
<p>
|
||||
fake_extra_path
|
||||
</p>
|
||||
<p>
|
||||
fake_name
|
||||
</p>
|
||||
<p>
|
||||
real_full_path
|
||||
</p>
|
||||
<p>
|
||||
real_leading_dirs
|
||||
</p>
|
||||
<p>
|
||||
real_extra_path
|
||||
</p>
|
||||
<p>
|
||||
real_name
|
||||
</p>
|
||||
<p>
|
||||
fake_full_path_clean
|
||||
</p>
|
||||
<p>
|
||||
fake_leading_dirs_clean
|
||||
</p>
|
||||
<p>
|
||||
fake_extra_path_clean
|
||||
</p>
|
||||
<p>
|
||||
fake_name_clean
|
||||
</p>
|
||||
<p>
|
||||
real_full_path_clean
|
||||
</p>
|
||||
<p>
|
||||
real_leading_dirs_clean
|
||||
</p>
|
||||
<p>
|
||||
real_extra_path_clean
|
||||
</p>
|
||||
<p>
|
||||
real_name_clean
|
||||
</p>
|
||||
<p>
|
||||
"clean" values are run through vfs->db_clean () and
|
||||
</p>
|
||||
<p>
|
||||
are safe for use in SQL queries that use key='value'
|
||||
</p>
|
||||
<p>
|
||||
They should be used ONLY for SQL queries, so are used
|
||||
</p>
|
||||
<p>
|
||||
mostly internally
|
||||
</p>
|
||||
<p>
|
||||
mask is either RELATIVE_NONE or RELATIVE_NONE|VFS_REAL,
|
||||
</p>
|
||||
<p>
|
||||
and is used internally
|
||||
</p>
|
||||
<p>
|
||||
outside is boolean, True if $relatives contains VFS_REAL
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function path_parts ($string, $relatives = array (RELATIVE_CURRENT), $object = True)
|
||||
</verb>
|
||||
</p><sect1>
|
||||
getabsolutepath<label id="sec: getabsolutepath" >
|
||||
<p>
|
||||
abstract: get the absolute path
|
||||
</p>
|
||||
<p>
|
||||
param: $target defaults to False, directory/file to get path of,
|
||||
relative to $relatives[0]
|
||||
</p>
|
||||
<p>
|
||||
param: $mask Relativity bitmask (see RELATIVE_ defines). RELATIVE_CURRENT
|
||||
means use $this->relative
|
||||
</p>
|
||||
<p>
|
||||
param: $fake Returns the "fake" path, ie /home/user/dir/file
|
||||
(not always possible. use path_parts () instead)
|
||||
</p>
|
||||
<p>
|
||||
result: $basedir Full fake or real path
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function getabsolutepath ($target = False, $relatives = array (RELATIVE_CURRENT), $fake = True)
|
||||
</verb>
|
||||
</p><sect1>
|
||||
cd<label id="sec: cd" >
|
||||
<p>
|
||||
abstract: Change directory
|
||||
</p>
|
||||
<p>
|
||||
discussion: To cd to the files root "/", use cd ("/",
|
||||
False, array (RELATIVE_NONE));
|
||||
</p>
|
||||
<p>
|
||||
param: $target default "/". directory to cd into. if
|
||||
"/" and $relative is True, uses "/home/<working_lid>";
|
||||
</p>
|
||||
<p>
|
||||
param: $relative default True/relative means add target to current
|
||||
path, else pass $relative as mask to getabsolutepath()
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function cd ($target = "/", $relative = True, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
pwd<label id="sec: pwd" >
|
||||
<p>
|
||||
abstract: current working dir
|
||||
</p>
|
||||
<p>
|
||||
param: $full default True returns full fake path, else just the
|
||||
extra dirs (false strips the leading /)
|
||||
</p>
|
||||
<p>
|
||||
result: $currentdir currentdir
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function pwd ($full = True)
|
||||
</verb>
|
||||
</p><sect1>
|
||||
read<label id="sec: read" >
|
||||
<p>
|
||||
abstract: return file contents
|
||||
</p>
|
||||
<p>
|
||||
param: $file filename
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: $contents Contents of $file, or False if file cannot
|
||||
be read
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function read ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
write<label id="sec: write" >
|
||||
<p>
|
||||
abstract: write to a file
|
||||
</p>
|
||||
<p>
|
||||
param: $file file name
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
param: $contents contents
|
||||
</p>
|
||||
<p>
|
||||
result: Boolean True/False
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function write ($file, $relatives = array (RELATIVE_CURRENT), $contents)
|
||||
</verb>
|
||||
</p><sect1>
|
||||
touch<label id="sec: touch" >
|
||||
<p>
|
||||
abstract: Create blank file $file or set the modification time and
|
||||
modified by of $file to current time and user
|
||||
</p>
|
||||
<p>
|
||||
param: $file File to touch or set modifies
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: Boolean True/False
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function touch ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
cp<label id="sec: cp" >
|
||||
<p>
|
||||
abstract: copy file
|
||||
</p>
|
||||
<p>
|
||||
param: $from from file/directory
|
||||
</p>
|
||||
<p>
|
||||
param: $to to file/directory
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: boolean True/False
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function cp ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
mv<label id="sec: mv" >
|
||||
<p>
|
||||
abstract: move file/directory
|
||||
</p>
|
||||
<p>
|
||||
param: $from from file/directory
|
||||
</p>
|
||||
<p>
|
||||
param: $to to file/directory
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: boolean True/False
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function mv ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
move<label id="sec: move" >
|
||||
<p>
|
||||
abstract: shortcut to mv
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function move ($from, $to, $relatives = array (RELATIVE_CURRENT, RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
rm<label id="sec: rm" >
|
||||
<p>
|
||||
abstract: delete file/directory
|
||||
</p>
|
||||
<p>
|
||||
param: $string file/directory to delete
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: boolean True/False
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function rm ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
delete<label id="sec: delete" >
|
||||
<p>
|
||||
abstract: shortcut to rm
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function delete ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
mkdir<label id="sec: mkdir" >
|
||||
<p>
|
||||
abstract: make a new directory
|
||||
</p>
|
||||
<p>
|
||||
param: $dir Directory name
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: boolean True on success
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function mkdir ($dir, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
set_attributes<label id="sec: set_attributes" >
|
||||
<p>
|
||||
abstract: Update database entry for $file with the attributes in
|
||||
$attributes
|
||||
</p>
|
||||
<p>
|
||||
param: $file file/directory to update
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
param: $attributes keyed array of attributes. key is attribute
|
||||
name, value is attribute value
|
||||
</p>
|
||||
<p>
|
||||
result: Boolean True/False
|
||||
</p>
|
||||
<p>
|
||||
discussion: Valid attributes are:
|
||||
</p>
|
||||
<p>
|
||||
owner_id
|
||||
</p>
|
||||
<p>
|
||||
createdby_id
|
||||
</p>
|
||||
<p>
|
||||
modifiedby_id
|
||||
</p>
|
||||
<p>
|
||||
created
|
||||
</p>
|
||||
<p>
|
||||
modified
|
||||
</p>
|
||||
<p>
|
||||
size
|
||||
</p>
|
||||
<p>
|
||||
mime_type
|
||||
</p>
|
||||
<p>
|
||||
deleteable
|
||||
</p>
|
||||
<p>
|
||||
comment
|
||||
</p>
|
||||
<p>
|
||||
app
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function set_attributes ($file, $relatives = array (RELATIVE_CURRENT), $attributes = array ())
|
||||
</verb>
|
||||
</p><sect1>
|
||||
correct_attributes<label id="sec: correct_attributes" >
|
||||
<p>
|
||||
abstract: Set the correct attributes for $string (e.g. owner)
|
||||
</p>
|
||||
<p>
|
||||
param: $string File/directory to correct attributes of
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: Boolean True/False
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function correct_attributes ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
file_type<label id="sec: file_type" >
|
||||
<p>
|
||||
abstract: return file/dir type (MIME or other)
|
||||
</p>
|
||||
<p>
|
||||
param: $file File or directory path (/home/user/dir/dir2/dir3, /home/user/dir/dir2/file)
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: MIME type, "Directory", or nothing if MIME type is not
|
||||
known
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function file_type ($file, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
file_exists<label id="sec: file_exists" >
|
||||
<p>
|
||||
abstract: check if file/directory exists
|
||||
</p>
|
||||
<p>
|
||||
param: $string file/directory to check existance of
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: Boolean True/False
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function file_exists ($string, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
checkperms<label id="sec: checkperms" >
|
||||
<p>
|
||||
abstract: Check if you have write access to create files in $dir
|
||||
</p>
|
||||
<p>
|
||||
discussion: This isn't perfect, because vfs->touch () returns True even
|
||||
</p>
|
||||
<p>
|
||||
if only the database entry worked. ACLs need to be
|
||||
</p>
|
||||
<p>
|
||||
implemented for better permission checking. It's
|
||||
</p>
|
||||
<p>
|
||||
also pretty slow, so I wouldn't recommend using it
|
||||
</p>
|
||||
<p>
|
||||
often
|
||||
</p>
|
||||
<p>
|
||||
param: $dir Directory to check access of
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
result: Boolean True/False
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function checkperms ($dir, $relatives = array (RELATIVE_CURRENT))
|
||||
</verb>
|
||||
</p><sect1>
|
||||
ls<label id="sec: ls" >
|
||||
<p>
|
||||
abstract: get directory listing
|
||||
</p>
|
||||
<p>
|
||||
discussion: Note: the entries are not guaranteed to be returned in any
|
||||
logical order
|
||||
</p>
|
||||
<p>
|
||||
param: $dir Directory
|
||||
</p>
|
||||
<p>
|
||||
param: $relatives Relativity array
|
||||
</p>
|
||||
<p>
|
||||
param: $checksubdirs Boolean, recursively list all sub directories
|
||||
as well?
|
||||
</p>
|
||||
<p>
|
||||
param: $mime_type Only return entries matching MIME-type $mime_type.
|
||||
Can be "Directory" or "\" for those without MIME
|
||||
types
|
||||
</p>
|
||||
<p>
|
||||
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'
|
||||
</p>
|
||||
<p>
|
||||
result: array of arrays. Subarrays contain full info for each file/dir.
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function ls ($dir = False, $relatives = array (RELATIVE_CURRENT), $checksubdirs = True, $mime_type = False, $nofiles = False)
|
||||
</verb>
|
||||
</p><sect1>
|
||||
dir<label id="sec: dir" >
|
||||
<p>
|
||||
abstract: shortcut to ls
|
||||
</p>
|
||||
<p>
|
||||
<verb>
|
||||
function dir ($dir = False, $relatives = array (RELATIVE_CURRENT), $checksubdirs = True, $mime_type = False, $nofiles = False)
|
||||
</verb>
|
||||
|
||||
|
||||
</article>
|
||||
Loading…
Reference in New Issue
Block a user