file.3

使用PHP+MySQL编写的一个图片上传共享系统.

.Vb 1
\&    exit;
.Ve
.SH "DESCRIPTION"
File is a wrapper class to common PHP file functions. It encapsulates error
checking during file operations, reducing the amount of code in your own
programs and avoiding redundancy.  I basically got tired of re-writing these
methods over and over again in every new program I wrote, so I threw them
all into a single class.
.SH "METHODS"
.Sh "new \fIFile()\fR"
To create a new File object, simply call new File without arguments.
.Sh "\fIclear_cache\fR\|( void )"
Any time a \fIstat()\fR is performed on a file (usually during an \fIis_owner()\fR or
\fIis_inGroup()\fR call, the \fIstat()\fR results are stored in the \fB\s-1STATCACHE\s0\fR
variable.  Calling \fIclear_cache()\fR forces the class to clear the cached data.
.Sh "\fIis_sane\fR\|( \f(CW$fileName\fR,$must_exist=0,$noSymLinks=0,$noDirs=0 )"
The \fIis_sane()\fR method performs several checks on a given file.  The checks
are performed based upon the values given in the \fBmust_exist\fR,
\fBnoSymLinks\fR, and \fBnoDirs\fR flags.  If all three flags are set to zero, the
method automatically assumes the file is sane and returns true.  If any of
the flags are set to a value other than zero, that check must be true for
\fIis_sane()\fR to return true.  Here's an example;
.PP
.Vb 3
\&    $File->is_sane($fileName,1,0,0)
\&        // will return true if a file, directory,
\&        // or symlink exists with that name.
.Ve
.Vb 4
\&    $File->is_sane($fileName,1,0,1)
\&        // will return true if a file or symlink with that
\&        // name exists, but will return false of the filename
\&        // is a directory or doesn't exist
.Ve
.Vb 3
\&    $File->is_sane($fileName,1,1,1)
\&        // will return true if the file exists, but will return
\&        // false if the file is a symlink or a directory.
.Ve
.Vb 4
\&    $File->is_sane($fileName,0,1,1)
\&        // will return true so long as the name does not point
\&        // to a symlink or a directory, regardless if a file
\&        // exists by that name.
.Ve
\fIis_sane()\fR will set the \fB\s-1ERROR\s0\fR variable if any of the checks fail, so be
sure to check it if \fIis_sane()\fR fails.
.Sh "\fIread_file\fR\|( \f(CW$fileName\fR )"
This method returns the raw file contents, or null on failure.  It will not
read directories but symlinks are considered \*(L"ok\*(R".
.Sh "\fIstrip_read\fR\|( \f(CW$fileName\fR )"
This reads the file and performs an \fIfgetss()\fR on the file contents, stripping
any \s-1HTML\s0 and \s-1PHP\s0 tags from the file, leaving (for the most part) plain text. 
Returns the results or null on failure.
.Sh "\fIwrite_file\fR\|( \f(CW$fileName\fR, \f(CW$data\fR )"
Saves the contents of \f(CW$data\fR to the file specified.  Returns true on success,
false on failure.  If the file pointed to by \f(CW$fileName\fR already exists, the
class first copies that file to a temporary file, \fBappends\fR the data to the
temporary file, and then tries to copy the temporary file over the original.
This is the best method I can think of to preserve the original file's
integrity should a conflict or error occur.  This method should be
relatively safe from process conflicts. (more than one process trying to
write the file at one time.)
.Sh "\fIcopy_file\fR\|( \f(CW$oldFile\fR, \f(CW$newFile\fR )"
Saves the contents of \f(CW$oldFile\fR as \f(CW$newFile\fR.  If the old file does not exist
or if the new file already exists, this method will abort and return false.
.Sh "\fIget_files\fR\|( \f(CW$path\fR, \f(CW$fileExt\fR = \*(M'\s-1ALL_FILES\s0')"
This method will gather a listing of all files matching \fB$fileExt\fR and
return the results as an array, where each element in the array will be a
file name. (sans path).  If \fB$fileExt\fR is not specified, returns all files
found.  This method, in order to prevent infinite loops, will \fB\s-1IGNORE\s0\fR sub
and parent directories.  Only the directory pointed to by \fB$path\fR will be
read.  Returns null if unable to read the contents of the directory.
.Sh "\fIis_owner\fR\|( \f(CW$fileName\fR, \f(CW$uid\fR = """" )"
Given a user \s-1ID\s0, will return true if that user id owns the specified file. 
If \s-1UID\s0 is not specified, the method assumes itself. (ie, it will check to
see if the \s-1PHP\s0 process \s-1UID\s0 owns the filename) This is very usefull, since
the built in \s-1PHP\s0 methods \fIis_readable()\fR and \fIis_writeable()\fR routinely lie
about read and write capabilities.  (They return true if the read and write
bits on the file are set, \fBregardless\fR of whether the process can actually
read or write to those files.  (Which make \fIis_readble()\fR and \fIis_writeable()\fR
completely useless \s-1IMHO\s0).  If the \s-1UID\s0 is specified, will return true of that
\s-1UID\s0 is the owner of the specified file, false otherwise.  See also
\fIget_real_uid()\fR since this method uses that.
.Sh "\fIis_inGroup\fR\|( \f(CW$fileName\fR, \f(CW$gid\fR = """" )"
Identical to \fIis_owner()\fR except that it works on the \s-1GID\s0 instead of the \s-1UID\s0.
.Sh "\fIget_real_uid()\fR"
This method will return the user \s-1ID\s0 of the \s-1PHP\s0 process itself.  It does
\fBnot\fR use the built in php method \fIgetmyuid()\fR, which is 99% of the time a
lieing sack of puss that is best ignored.  This method determines it's user
id by creating a temporary file, and then performing a \fIstat()\fR check on the
file.  The results of this method are cached by the class for more efficient
results. (So if you call this method right after a \fInew()\fR, the class will
perform a teensy-bit faster)
.Sh "\fIget_real_gid()\fR"
Identical (literally) to a \fIget_real_uid()\fR call.  It returns the group \s-1ID\s0 of
the process that's running.  I cheated here.  When \fIget_real_uid()\fR is called,
it sets two global variables \fB\s-1REALUID\s0\fR and \fB\s-1REALGID\s0\fR.  You can save
yourself a function call here.  If \fIget_real_uid()\fR has already been called in
your program, just grab the contents of \fB\s-1REALGID\s0\fR instead of calling this
method.
.SH "VARIABLES"
.Sh "\s-1ERROR\s0 (string)"
This variable contains the text of the last test \s-1ERROR\s0 encountered.  If a
test fails, the text description of why the test failed can be retrieved by
grabbing this variable.
.Sh "\s-1BUFFER\s0 (integer, default \-1 )"
This is the \s-1BUFFER\s0 used when performing an \fIstrip_read()\fR call.  It defaults
to the size of the file unless you override it.  For the most part you
shouldn't need to change the buffer size.
.Sh "\s-1STATCACHE\s0 ( array, default \s-1NULL\s0 )"
After any call to \fIis_owner()\fR or \fIis_inGroup()\fR, this variable will contain the
returned \fIstat()\fR array.  You can clear this variable on the fly by calling
the \fIclear_cache()\fR method.
.Sh "\s-1TEMPDIR\s0 ( string, default \*(M'/tmp\*(S' )"
The temporary directory used by the class when making temp files.  The class
needs to be able to create temporary files.  By default it will create those
files in \*(L'/tmp\*(R' unless you specify otherwise by overriding this variable,
for example;
.PP
.Vb 3
\&    include("class.File.php3");
\&    $File = new File;
\&    $File->TEMPDIR = 'C:\eWINDOWS\eTEMP';
.Ve
.Sh "\s-1REALUID\s0 ( integer, default = \-1 )"
This variable will contain the cached results of a \fIget_real_uid()\fR or
\fIget_real_gid()\fR call.  The \s-1UID\s0 of the process is stored in this variable.
.Sh "\s-1REALGID\s0 ( integer, default = \-1 )"
Identical to \s-1REALUID\s0, except of course this is the group \s-1ID\s0 of the current
process.
.SH "EXAMPLES"
see SYNOPSIS
.SH "DOCUMENTATION"
This is it.
.SH "INSTALLATION"
Copy the class file to the location specified in your PHP3.INI file. 
Failing that, use the full path to the class file's location in your
\fIinclude()\fR directive.
.SH "BUGS"
No bugs that I know if, I've been using this class in my own programs for
several months.
.SH "VERSION"
Version 1.0 April 03, 1999  CDI, [e-mail]
.SH "AUTHOR"
Copyright (c) 1999, CDI \- [e-mail].  All Rights Reserved.
.SH "LICENSE"
This program is free software; you can redistribute it and/or modify it
under the GNU General Artistic License, with the following stipulations;
.PP
Changes or modifications must retain these Copyright statements. Changes or
modifications \fBmust\fR be submitted to the AUTHOR, [e-mail].
.PP
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the Artistic License for more
details. This software is distributed \fBAS\-IS\fR.
.SH "AVAILABILITY"
http://www.thewebmasters.net/php/
.SH "HISTORY"
Version 1.0, initial public release

.rn }` ''
.IX Title "FILE 1"
.IX Name "File_1.0 - A wrapper class to common PHP file operations"

.IX Header "NAME"

.IX Header "SYNOPSIS"

.IX Header "DESCRIPTION"

.IX Header "METHODS"

.IX Subsection "new \fIFile()\fR"

.IX Subsection "\fIclear_cache\fR\|( void )"

.IX Subsection "\fIis_sane\fR\|( \f(CW$fileName\fR,$must_exist=0,$noSymLinks=0,$noDirs=0 )"

.IX Subsection "\fIread_file\fR\|( \f(CW$fileName\fR )"

.IX Subsection "\fIstrip_read\fR\|( \f(CW$fileName\fR )"

.IX Subsection "\fIwrite_file\fR\|( \f(CW$fileName\fR, \f(CW$data\fR )"

.IX Subsection "\fIcopy_file\fR\|( \f(CW$oldFile\fR, \f(CW$newFile\fR )"

.IX Subsection "\fIget_files\fR\|( \f(CW$path\fR, \f(CW$fileExt\fR = \*(M'\s-1ALL_FILES\s0')"

.IX Subsection "\fIis_owner\fR\|( \f(CW$fileName\fR, \f(CW$uid\fR = """" )"

.IX Subsection "\fIis_inGroup\fR\|( \f(CW$fileName\fR, \f(CW$gid\fR = """" )"

.IX Subsection "\fIget_real_uid()\fR"

.IX Subsection "\fIget_real_gid()\fR"

.IX Header "VARIABLES"

.IX Subsection "\s-1ERROR\s0 (string)"

.IX Subsection "\s-1BUFFER\s0 (integer, default \-1 )"

.IX Subsection "\s-1STATCACHE\s0 ( array, default \s-1NULL\s0 )"

.IX Subsection "\s-1TEMPDIR\s0 ( string, default \*(M'/tmp\*(S' )"

.IX Subsection "\s-1REALUID\s0 ( integer, default = \-1 )"

.IX Subsection "\s-1REALGID\s0 ( integer, default = \-1 )"

.IX Header "EXAMPLES"

.IX Header "DOCUMENTATION"

.IX Header "INSTALLATION"

.IX Header "BUGS"

.IX Header "VERSION"

.IX Header "AUTHOR"

.IX Header "LICENSE"

.IX Header "AVAILABILITY"

.IX Header "HISTORY"