[pLog-svn] r1538 - in plog/trunk/class: database file file/finder
file/unpacker
oscar at devel.plogworld.net
oscar at devel.plogworld.net
Thu Mar 17 22:27:51 GMT 2005
Author: oscar
Date: 2005-03-17 22:27:51 +0000 (Thu, 17 Mar 2005)
New Revision: 1538
Modified:
plog/trunk/class/database/db.class.php
plog/trunk/class/database/dbobject.class.php
plog/trunk/class/file/file.class.php
plog/trunk/class/file/fileproperties.class.php
plog/trunk/class/file/fileupload.class.php
plog/trunk/class/file/fileuploads.class.php
plog/trunk/class/file/finder/filefinder.class.php
plog/trunk/class/file/unpacker/baseunpacker.class.php
plog/trunk/class/file/unpacker/pclzip.lib.php
plog/trunk/class/file/unpacker/rarunpacker.class.php
plog/trunk/class/file/unpacker/tarbz2unpacker.class.php
plog/trunk/class/file/unpacker/targzunpacker.class.php
plog/trunk/class/file/unpacker/unpacker.class.php
plog/trunk/class/file/unpacker/zipunpacker.class.php
Log:
more stuff documented
Modified: plog/trunk/class/database/db.class.php
===================================================================
--- plog/trunk/class/database/db.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/database/db.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,16 +1,19 @@
<?php
- /**
- * @package database
- */
+ /**
+ * \defgroup Database
+ *
+ * Database-related objects
+ */
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/config/configfilestorage.class.php" );
include_once( PLOG_CLASS_PATH."class/database/adodb/adodb.inc.php" );
/**
- * Provides a singleton for accessing the db.
+ * \ingroup Database
+ *
+ * Provides a singleton for accessing the db and interfaces with ADOdb
*/
class Db extends Object
{
Modified: plog/trunk/class/database/dbobject.class.php
===================================================================
--- plog/trunk/class/database/dbobject.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/database/dbobject.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,17 +1,13 @@
<?php
- /**
- * @package database
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
/**
- * this object gives all the objects that extend it the possibility of
- * having custom parameters. In plog this is used to give all database
- * rows a set of custom fields that can be used to extend them without needing
- * to make changes to the database
+ * \ingroup Database
+ *
+ * The DbObject is the object that ideally all object representing one database row should
+ * extend. It doesn't provide too many features yet but it is planned to provide them in the
+ * future.
*/
class DbObject extends Object
{
Modified: plog/trunk/class/file/file.class.php
===================================================================
--- plog/trunk/class/file/file.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/file.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,7 +1,10 @@
<?php
/**
- * @package file
+ * \defgroup File
+ *
+ * The File module provides some classes to deal with files. The File class is the most
+ * useful once, since provides OOP wrappers around some PHP functions that work with files.
*/
@@ -11,6 +14,8 @@
define( "FILE_DEFAULT_DIRECTORY_CREATION_MODE", 0700 );
/**
+ * \ingroup File
+ *
* Encapsulation of a class to manage files. It is basically a wrapper
* to some of the php functions.
* http://www.php.net/manual/en/ref.filesystem.php
@@ -22,6 +27,11 @@
var $_handler;
var $_mode;
+ /**
+ * Creates an object of this type, but the file is not automaticaly opened
+ *
+ * @param fileName The name of the file
+ */
function File( $fileName )
{
$this->Object();
@@ -30,10 +40,13 @@
}
/**
- * Opens the file in the specified mode
+ * Opens the file in the specified mode
* http://www.php.net/manual/en/function.fopen.php
* Mode by default is 'r' (read only)
* Returns 'false' if operation failed
+ *
+ * @param mode The mode in which the file is opened
+ * @return false if the operation failed
*/
function open( $mode = "r" )
{
@@ -45,7 +58,9 @@
}
/**
- * Closes the stream
+ * Closes the stream currently being held by this object
+ *
+ * @return nothing
*/
function close()
{
@@ -53,8 +68,10 @@
}
/**
- * Read the whole file and put it into an array, where every position
+ * Reads the whole file and put it into an array, where every position
* of the array is a line of the file (new-line characters not included)
+ *
+ * @return An array where every position is a line from the file.
*/
function readFile()
{
@@ -69,10 +86,11 @@
}
/**
- * Reads a line from the file
+ * Reads bytes from the currently opened file
*
* @param size Amount of bytes we'd like to read from the file. It is set
* to 4096 by default.
+ * @return Returns the read contents
*/
function read( $size = 4096 )
{
@@ -80,7 +98,9 @@
}
/**
- * Returns true if we reached the end of the file
+ * checks whether we've reached the end of file
+ *
+ * @return True if we reached the end of the file or false otherwise
*/
function eof()
{
@@ -88,20 +108,29 @@
}
/**
- * Writes data to disk
+ * Writes data to disk
+ *
+ * @param data The data that we'd like to write to disk
+ * @return returns the number of bytes written, or false otherwise
*/
function write( $data )
{
return fwrite( $this->_handler, $data );
}
+ /**
+ * truncates the currently opened file to a given length
+ *
+ * @param length Lenght at which we'd like to truncate the file
+ * @return true if successful or false otherwise
+ */
function truncate( $length = 0 )
{
return ftruncate( $this->_handler, $length );
}
/**
- * Writes an array of text lines to the file.
+ * Writes an array of text lines to the file.
*
* @param lines The array with the text.
* @return Returns true if successful or false otherwise.
@@ -124,12 +153,12 @@
}
/**
- * Returns true wether the file is a directory. See
+ * Returns true wether the file is a directory. See
* http://fi.php.net/manual/en/function.is-dir.php for more details.
*
* @param file The filename we're trying to check. If omitted, the current file
* will be used (note that this function can be used as static as long as the
- * file parameter is provided)
+ * file parameter is provided)
* @return Returns true if the file is a directory.
*/
function isDir( $file = null )
@@ -141,12 +170,12 @@
}
/**
- * Returns true if the file is writable by the current user.
+ * Returns true if the file is writable by the current user.
* See http://fi.php.net/manual/en/function.is-writable.php for more details.
*
* @param file The filename we're trying to check. If omitted, the current file
* will be used (note that this function can be used as static as long as the
- * file parameter is provided)
+ * file parameter is provided)
* @return Returns true if the file is writable, or false otherwise.
*/
function isWritable( $file = null )
@@ -160,6 +189,8 @@
/**
* returns true if the file is readable. Can be used as static if a filename is provided
*
+ * @param if provided, this method can be used as an static method and it will check for
+ * the readability status of the file
* @return true if readable or false otherwise
*/
function isReadable( $file = null )
@@ -173,9 +204,10 @@
}
/**
- * removes a file. Can be used as static if a filename is provided
+ * removes a file. Can be used as static if a filename is provided. Otherwise it will
+ * remove the file that was given in the constructor
*
- * @param file
+ * @param optionally, name of the file to delete
* @return True if successful or false otherwise
*/
function delete( $file = null )
@@ -243,10 +275,12 @@
}
/**
- * Creates a new folder
+ * Creates a new folder. If the folder name is /a/b/c and neither /a or /a/b exist, this
+ * method will take care of creating the whole folder structure automatically.
*
* @static
* @param dirName The name of the new folder
+ * @param mode Attributes that will be given to the folder
* @return Returns true if no problem or false otherwise.
*/
function createDir( $dirName, $mode = FILE_DEFAULT_DIRECTORY_CREATION_MODE )
@@ -285,7 +319,7 @@
}
/**
- * Returns the size of the file.
+ * Returns the size of the file.
*
* @param string fileName An optional parameter specifying the name of the file. If omitted,
* we will use the file that we have currently opened. Please note that this function can
@@ -331,7 +365,7 @@
}
/**
- * copies a file from one place to another.
+ * copies a file from one place to another.
* This method is always static
*
* @param inFile
@@ -345,7 +379,12 @@
}
/**
- * changes the permissions of a file
+ * changes the permissions of a file, via PHP's chmod() function
+ *
+ * @param inFile The name of the file whose mode we'd like to change
+ * @param mode The new mode, or if none provided, it will default to 0644
+ * @return true if successful or false otherwise
+ * @static
*/
function chMod( $inFile, $mode = 0644 )
{
@@ -353,7 +392,11 @@
}
/**
- * returns true if the file exists.
+ * returns true if the file exists.
+ *
+ * Can be used as an static method if a file name is provided as a parameter
+ * @param fileName optinally, name of the file whose existance we'd like to check
+ * @return true if successful or false otherwise
*/
function exists( $fileName = null )
{
Modified: plog/trunk/class/file/fileproperties.class.php
===================================================================
--- plog/trunk/class/file/fileproperties.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/fileproperties.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,18 +1,17 @@
<?php
- /**
- * @package file
- */
-
-
include_once( PLOG_CLASS_PATH."class/config/properties.class.php" );
include_once( PLOG_CLASS_PATH."class/file/file.class.php" );
/**
+ * \ingroup File
+ *
* Extends the class Properties so that it can read the values
- * from a file, which has the format 'name = value'
+ * from a file, which has the format 'name = value'. This class is not used
+ * anywhere anymore but has been left for compatibility reasons.
*/
- class FileProperties extends Properties {
+ class FileProperties extends Properties
+ {
var $_file;
var $_contents;
@@ -36,6 +35,8 @@
/**
* Loads the contents from the file, parses them and puts them
* into values
+ *
+ * @private
*/
function _load()
{
@@ -59,6 +60,8 @@
/**
* Returns true if the specified line is a comment or not
+ *
+ * @private
*/
function _isComment( $line )
{
@@ -70,6 +73,9 @@
return false;
}
+ /**
+ * @private
+ */
function _isNumber( $string )
{
return is_numeric( $string );
@@ -83,6 +89,8 @@
*
* The rest of the lines must either be empty or have the format
* key = value
+ *
+ * @private
*/
function _process()
{
Modified: plog/trunk/class/file/fileupload.class.php
===================================================================
--- plog/trunk/class/file/fileupload.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/fileupload.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,15 +1,13 @@
<?php
- /**
- * @package file
- */
-
-
/**
+ * \ingroup File
+ *
* Object representation of a file upload.
* Wraps around the values in the $_FILES or $HTTP_POST_FILES array.
*/
- class FileUpload extends Object {
+ class FileUpload extends Object
+ {
var $_name;
var $_mimeType;
@@ -33,41 +31,76 @@
$this->_folder = null;
}
+ /**
+ * returns the real name of the file uploaded
+ *
+ * @return the file name
+ */
function getFileName()
{
return $this->_name;
}
+ /**
+ * returns the MIME type of the file
+ *
+ * @return a MIME type
+ */
function getMimeType()
{
return $this->_mimeType;
}
+ /**
+ * @return returns the name of this file in the temporary folder
+ */
function getTmpName()
{
return $this->_tmpName;
}
+ /**
+ * @returns an error code if there was a problem uploading the file
+ *
+ * @see http://www.php.net/manual/en/features.file-upload.errors.php
+ */
function getError()
{
return $this->_error;
}
+ /**
+ * sets the error code. This method will be rarely needed
+ *
+ * @param error A valid PHP upload error code
+ * @see http://www.php.net/manual/en/features.file-upload.errors.php
+ */
function setError( $error )
{
$this->_error = $error;
}
+ /**
+ * @return returns the size of the uploaded file
+ */
function getSize()
{
return $this->_size;
}
+ /**
+ * sets the folder
+ *
+ * @param folder
+ */
function setFolder( $folder )
{
$this->_folder = $folder;
}
+ /**
+ * @returns the folder
+ */
function getFolder()
{
return $this->_folder;
Modified: plog/trunk/class/file/fileuploads.class.php
===================================================================
--- plog/trunk/class/file/fileuploads.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/fileuploads.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,19 +1,18 @@
<?php
- /**
- * @package file
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/file/fileupload.class.php" );
define( "FILE_UPLOADS_NOT_ENABLED", -200 );
/**
+ * \ingroup File
+ *
* Handles file uploads in pLog.
+ * @see FileUpload
*/
- class FileUploads extends Object {
+ class FileUploads extends Object
+ {
var $_files;
var $_blogInfo;
Modified: plog/trunk/class/file/finder/filefinder.class.php
===================================================================
--- plog/trunk/class/file/finder/filefinder.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/finder/filefinder.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -5,6 +5,8 @@
/**
+ * \ingroup File
+ *
* given an array with strings and a folder on disk, this class will scan the folder and compare
* them with the ones in the array and return which ones from disk do NOT exist in the given array.
* In order to get the array with the elements that are new according to our first array, please
Modified: plog/trunk/class/file/unpacker/baseunpacker.class.php
===================================================================
--- plog/trunk/class/file/unpacker/baseunpacker.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/unpacker/baseunpacker.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,13 +1,10 @@
<?php
- /**
- * @package file
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
/**
+ * \ingroup File_Unpacker
+ *
* this is the interface that classes wishing to provide additional methods
* for unpacking files must implement. Of course PHP4 does not support native
* interface and so we have to resort to this kind of tricks but probably you
@@ -21,6 +18,13 @@
$this->Object();
}
+ /**
+ * method that implements the logic for unpacking files ofa certain type
+ *
+ * @param file The file that we'd like to unpack
+ * @param destFolder the destination folder
+ * @return true if successful or false otherwise
+ */
function unpack( $file, $destFolder )
{
throw( new Exception( "This method must be implemented by child classes!" ));
Modified: plog/trunk/class/file/unpacker/pclzip.lib.php
===================================================================
--- plog/trunk/class/file/unpacker/pclzip.lib.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/unpacker/pclzip.lib.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,9 +1,5 @@
<?php
-
- /**
- * @package file
- */
-
+
// --------------------------------------------------------------------------------
// PhpConcept Library - Zip Module 2.1
// --------------------------------------------------------------------------------
@@ -147,6 +143,9 @@
// extract() : Extract the content of the archive
// properties() : List the properties of the archive
// --------------------------------------------------------------------------------
+ /**
+ * \ingroup File_Unpacker
+ */
class PclZip
{
// ----- Filename of the zip file
Modified: plog/trunk/class/file/unpacker/rarunpacker.class.php
===================================================================
--- plog/trunk/class/file/unpacker/rarunpacker.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/unpacker/rarunpacker.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,17 +1,17 @@
<?php
- /**
- * @package unpacker
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/file/unpacker/baseunpacker.class.php" );
define( "DEFAULT_UNRAR_PATH", "/usr/bin/unrar" );
/**
- * unpacks files packed with RAR
+ * \ingroup File_Unpacker
+ *
+ * extends the BaseUnpacker class to implement support for RAR files
+ *
+ * It users the binary "unrar" and "gzip" to unpack the files. The location of these binaries
+ * is obtained from the config parameter "path_to_unrar" (or /usr/bin/unrar)
*/
class RarUnpacker extends BaseUnpacker
{
@@ -21,6 +21,9 @@
$this->BaseUnpacker();
}
+ /**
+ * @see BaseUnpacker::unpack()
+ */
function unpack( $file, $destFolder )
{
// get the paths where tar and gz are
Modified: plog/trunk/class/file/unpacker/tarbz2unpacker.class.php
===================================================================
--- plog/trunk/class/file/unpacker/tarbz2unpacker.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/unpacker/tarbz2unpacker.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package unpacker
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/file/unpacker/baseunpacker.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
@@ -16,7 +11,14 @@
define( "DEFAULT_BZIP2_PATH", "/bin/bzip2" );
/**
+ * \ingroup File_Unpacker
+ *
* Unpacks .tar.gz files.
+ *
+ * It users the binaries "tar" and "gzip" to unpack the files. The location of these binaries
+ * is obtained from the config parameter "path_to_tar" (or /bin/tar if it does not exist) and
+ * "path_to_gzip" (or /bin/gzip if it does not exist)
+ *
*/
class TarBz2Unpacker extends BaseUnpacker
{
Modified: plog/trunk/class/file/unpacker/targzunpacker.class.php
===================================================================
--- plog/trunk/class/file/unpacker/targzunpacker.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/unpacker/targzunpacker.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package file
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/file/unpacker/baseunpacker.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
@@ -16,6 +11,12 @@
define( "DEFAULT_GZIP_PATH", "/bin/gzip" );
/**
+ * \ingroup File_Unpacker
+ *
+ * It users the binaries "tar" and "gzip" to unpack the files. The location of these binaries
+ * is obtained from the config parameter "path_to_tar" (or /bin/tar if it does not exist) and
+ * "path_to_gzip" (or /bin/gzip if it does not exist)
+ *
* Unpacks .tar.gz files.
*/
class TarGzUnpacker extends BaseUnpacker
Modified: plog/trunk/class/file/unpacker/unpacker.class.php
===================================================================
--- plog/trunk/class/file/unpacker/unpacker.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/unpacker/unpacker.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,10 +1,15 @@
<?php
- /**
- * @package unpacker
- */
+ /**
+ * \defgroup File_Unpacker
+ *
+ * This module implements support for easily unpacking files compressed with
+ * .zip, .tar.gz, .tar.bz2 and .rar provided that all the binary tools are available.
+ *
+ * The main Unpacker class is a proxy class that will take care of finding the right
+ * subclass according to the package type.
+ */
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/file/unpacker/baseunpacker.class.php" );
include_once( PLOG_CLASS_PATH."class/file/unpacker/targzunpacker.class.php" );
@@ -20,10 +25,22 @@
define( "UNPACKER_UNSUPPORTED", false );
/**
+ * \ingroup File_Unpacker
+ *
* Class that implements an object capable of unpacking several different
* kinds of compressed files. It will take care of finding the right unpacker class for the
- * job, call it and return a result from it.
+ * job, call it and return a result from it, so <b>there is no need to create instances of
+ * the other unpacker classes</b>.
+ *
+ * Example of usage:
*
+ * <pre>
+ * $unpacker = new Unpacker();
+ * $unpacker->unpack( "/tmp/my_uploaded_file.tar.gz", "/tmp/results" );
+ * </pre>
+ *
+ * More unpacker classes can be added if needed.
+ *
* @see BaseUnpacker
* @see TarGzUnpacker
* @see ZipUnpacker
Modified: plog/trunk/class/file/unpacker/zipunpacker.class.php
===================================================================
--- plog/trunk/class/file/unpacker/zipunpacker.class.php 2005-03-17 22:22:58 UTC (rev 1537)
+++ plog/trunk/class/file/unpacker/zipunpacker.class.php 2005-03-17 22:27:51 UTC (rev 1538)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package unpacker
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/file/unpacker/baseunpacker.class.php" );
include_once( PLOG_CLASS_PATH."class/file/unpacker/pclzip.lib.php" );
@@ -12,10 +7,15 @@
define( "DEFAULT_UNZIP_PATH", "/usr/bin/unzip" );
/**
+ * \ingroup File_Unpacker
+ *
* unpacks files with ZIP. It can also use native PHP code with the
* PclZip library, set "unzip_use_native_version" to true if the configuration table
* for enabling that option.
*
+ * It users the binary "zip" to unpack the files. Its location is obtained from the
+ * config parameter "path_to_unzip" or /usr/bin/unzip if it does not exist
+ *
* @see Unpacker
* @see BaseUnpacker
*/
@@ -30,6 +30,10 @@
/**
* uses a native php library that is capable of dealing with .zip
* files without needing to call external commands
+ *
+ * @param file
+ * @param destFolder
+ * @return true if successful or false otherwise
*/
function unpackNative( $file, $destFolder )
{
@@ -37,6 +41,9 @@
return $z->extract( $destFolder );
}
+ /**
+ * @see BaseUnpacker::unpack()
+ */
function unpack( $file, $destFolder )
{
// get the paths where tar and gz are
More information about the pLog-svn
mailing list