[pLog-svn] r3647 - in plog/trunk/class: . cache cache/Cache_Lite
dao data data/captcha data/validator database database/pdb
database/pdb/datadict object summary/action
oscar at devel.lifetype.net
oscar at devel.lifetype.net
Fri Jun 23 22:46:04 GMT 2006
Author: oscar
Date: 2006-06-23 22:46:04 +0000 (Fri, 23 Jun 2006)
New Revision: 3647
Modified:
plog/trunk/class/Doxyfile
plog/trunk/class/bootstrap.php
plog/trunk/class/cache/Cache_Lite/Lite.php
plog/trunk/class/cache/cache.class.php
plog/trunk/class/cache/cachemanager.class.php
plog/trunk/class/dao/articles.class.php
plog/trunk/class/data/captcha/captcha.class.php
plog/trunk/class/data/jalalicalendar.class.php
plog/trunk/class/data/plogcalendar.class.php
plog/trunk/class/data/validator/templatesetvalidator.class.php
plog/trunk/class/database/db.class.php
plog/trunk/class/database/pdb/datadict/pdbbasedatadict.class.php
plog/trunk/class/database/pdb/datadict/pdbmysqldatadict.class.php
plog/trunk/class/database/pdb/pdb.class.php
plog/trunk/class/object/loggable.class.php
plog/trunk/class/object/object.class.php
plog/trunk/class/summary/action/summaryaction.class.php
Log:
added documentation to some of the code
Modified: plog/trunk/class/Doxyfile
===================================================================
--- plog/trunk/class/Doxyfile 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/Doxyfile 2006-06-23 22:46:04 UTC (rev 3647)
@@ -416,7 +416,7 @@
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/ mail/ bayesian/ misc/ net/ data/ view/ plugin/ template/ action/ summary/dao/
+INPUT = class/ object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/ mail/ bayesian/ misc/ net/ data/ view/ plugin/ template/ action/ summary/dao/
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
Modified: plog/trunk/class/bootstrap.php
===================================================================
--- plog/trunk/class/bootstrap.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/bootstrap.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -1,5 +1,18 @@
<?php
+/**
+
+\mainpage
+
+<b>Welcome to the LifeType API!</b>
+
+<p>This is the starting point of the LifeType API. The API provides an a group of classes that go from
+database abstraction and data representation to templating and data validation.</p>
+<p>This documentation is not an in-depth introduction to the LifeType API but instead it should only be used
+as a reference when developing plugins or customizing LifeType. Additionally, the most recent version of this
+documentation can be found at http://www.lifetype.net/api
+ */
+
/**
* This file provides all the code needed for bootstraping an application
* based on the LT framework such as setting error handles, loading base
Modified: plog/trunk/class/cache/Cache_Lite/Lite.php
===================================================================
--- plog/trunk/class/cache/Cache_Lite/Lite.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/cache/Cache_Lite/Lite.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -1,31 +1,32 @@
<?php
-/**
-* Fast, light and safe Cache Class
-*
-* Cache_Lite is a fast, light and safe cache system. It's optimized
-* for file containers. It is fast and safe (because it uses file
-* locking and/or anti-corruption tests).
-*
-* There are some examples in the 'docs/examples' file
-* Technical choices are described in the 'docs/technical' file
-*
-* Memory Caching is from an original idea of
-* Mike BENOIT <ipso at snappymail.ca>
-*
-* Nota : A chinese documentation (thanks to RainX <china_1982 at 163.com>) is
-* available at :
-* http://rainx.phpmore.com/manual/cache_lite.html
-*
-* @package Cache_Lite
-* @category Caching
-* @version $Id: Lite.php,v 1.37 2005/11/24 20:10:01 fab Exp $
-* @author Fabien MARTY <fab at php.net>
-*/
-
define('CACHE_LITE_ERROR_RETURN', 1);
define('CACHE_LITE_ERROR_DIE', 8);
+/**
+ * \ingroup Cache
+ *
+ * Fast, light and safe Cache Class
+ *
+ * Cache_Lite is a fast, light and safe cache system. It's optimized
+ * for file containers. It is fast and safe (because it uses file
+ * locking and/or anti-corruption tests).
+ *
+ * There are some examples in the 'docs/examples' file
+ * Technical choices are described in the 'docs/technical' file
+ *
+ * Memory Caching is from an original idea of
+ * Mike BENOIT <ipso at snappymail.ca>
+ *
+ * Nota : A chinese documentation (thanks to RainX <china_1982 at 163.com>) is
+ * available at :
+ * http://rainx.phpmore.com/manual/cache_lite.html
+ *
+ * @package Cache_Lite
+ * @category Caching
+ * @version $Id: Lite.php,v 1.37 2005/11/24 20:10:01 fab Exp $
+ * @author Fabien MARTY <fab at php.net>
+ */
class Cache_Lite
{
Modified: plog/trunk/class/cache/cache.class.php
===================================================================
--- plog/trunk/class/cache/cache.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/cache/cache.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -1,21 +1,43 @@
<?php
+ /**
+ * \defgroup Cache
+ *
+ * The Cache group is made up of the Cache class, which provides the basic methods to store and
+ * retrieve data based on keys, and the CacheManager class which provides a singleton to access to
+ * the global.
+ */
+
include_once( PLOG_CLASS_PATH . "class/object/loggable.class.php" );
- /**
- * Provides a singleton for storing and retrieving data from a global cache.
- */
-
$__cache_hits = 0;
$__cache_misses = 0;
$__cache_queries = 0;
+ /**
+ * \ingroup Cache
+ *
+ * <p>This class wraps around the Cache_Lite class and provides a set of basic methods for storing
+ * and retrieving data from the cache. As of LifeType 1.1, this class is only used by the DAO layer as its
+ * caching mechanism but it can only be used by any other class if necessary.</p>
+ *
+ * <p>You probably don't want to create objects of this class, but instead use the CacheManager class
+ * that provides a singleton to access one global instance of this class</p>
+ *
+ * @see CacheManager
+ * @see Cache_Lite
+ */
class Cache extends Loggable
{
var $cache;
var $_disabledCacheCategories = array();
+ /**
+ * Constructor of the class.
+ *
+ * @param cacheProperties An array with parameters as required by Cache_Lite
+ */
function Cache( $cacheProperties )
{
require_once( PLOG_CLASS_PATH . "class/cache/Cache_Lite/Lite.php" );
@@ -24,6 +46,17 @@
$this->cache = new Cache_Lite( $cacheProperties );
}
+ /**
+ * Saves data to the cache. Data is identified by an id and a group. Any data
+ * can be saved to the cache but please check that you are using unique keys for
+ * different data or else data will be overwritten. If you have data that you know
+ * beforehand is not going to be unique, please use the setMultipleData method.
+ *
+ * @param id Unique identifier for the data.
+ * @param group The cache group
+ * @param data Data that is going to be cached
+ * @return Returns true if successful or false otherwise
+ */
function setData( $id, $group, $data )
{
if( $this->_cacheCategoryEnabled($group) ) {
@@ -37,7 +70,14 @@
/**
* Works in the same way as Cache::setData does, but instead of setting single values,
* it assumes that the value we're setting for the given key is part of an array of values. This
- * method is useful for data which we know is not unique.
+ * method is useful for data which we know is not unique, since it will store the data
+ * identified by data in an array identified by $id, alongside with any other values
+ * that are sharing the same key.
+ *
+ * @param id Unique identifier for the data.
+ * @param group The cache group
+ * @param data Data that is going to be cached
+ * @return Returns true if successful or false otherwise
*/
function setMultipleData( $id, $group, $data )
{
@@ -62,6 +102,13 @@
}
+ /**
+ * Retrieves previously stored data given its key.
+ *
+ * @param id Unique identifier under which the data was cached
+ * @param group Cache group where data was stored
+ * @return Returns the cached data if found or false otherwise
+ */
function getData( $id, $group )
{
global $__cache_hits;
@@ -90,6 +137,13 @@
}
+ /**
+ * Removes cached data from the cache, given its key and cache group.
+ *
+ * @param id Unique identifier under which the data was cached
+ * @param group Cache group where data was stored
+ * @return Returns the cached data if found or false otherwise
+ */
function removeData( $id, $group )
{
if( $this->_cacheCategoryEnabled($group) ) {
@@ -100,6 +154,12 @@
return true;
}
+ /**
+ * Clears the data of a whole cache group.
+ *
+ * @param group The group identifer whose data we'd like to cleanup
+ * @return
+ */
function clearCacheByGroup( $group )
{
if( $this->_cacheCategoryEnabled($group) ) {
@@ -110,6 +170,11 @@
return true;
}
+ /**
+ * Clears the entire cache, use with care.
+ *
+ * @return Returns true if successful or false otherwise
+ */
function clearCache()
{
$this->log->debug("Cleaning the cache", LOGGER_PRIO_WARN );
@@ -117,11 +182,24 @@
return $this->cache->clean();
}
+ /**
+ * Sets the directory where Cache_Lite will store its data. By default this is set to
+ * ./tmp.
+ *
+ * @param temp_folder Folder where cache data will be stored
+ * @return Always true
+ */
function setCacheDir( $temp_folder )
{
$this->cache->cacheDir = $temp_folder;
}
+ /**
+ * Disables caching for one whole category
+ *
+ * @param category The category for which we're disabling caching
+ * @return Always true
+ */
function disableCacheForCategory( $category )
{
$this->_disabledCacheCategories = array_merge( $this->_disabledCacheCategories,
@@ -129,6 +207,13 @@
return true;
}
+ /**
+ * Returns true if the given caching category is enabled
+ *
+ * @param category The cache category we'd like to check
+ * @return True if it is enabled or false otherwise
+ * @private
+ */
function _cacheCategoryEnabled( $category )
{
if( in_array($category, $this->_disabledCacheCategories) ) {
@@ -139,7 +224,7 @@
}
/**
- * returns the total count of cache hits, miss and total queries over the lifetime of the
+ * Returns the total count of cache hits, miss and total queries over the lifetime of the
* script so far.
*
* @return An array with 3 keys: "hits", "total" and "miss"
Modified: plog/trunk/class/cache/cachemanager.class.php
===================================================================
--- plog/trunk/class/cache/cachemanager.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/cache/cachemanager.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -1,29 +1,24 @@
<?php
- // :TODO: implement a cache-lifetime per cache-category, so e.g. blogInfo or
- // locales have a lifetime of several days, whereas articles, comments,
- // etc will only be cached for an hour.
-
/**
- * Provides a singleton for storing and retrieving data from a global cache.
+ * \ingroup Cache
+ *
+ * Provides a singleton for storing and retrieving data from a global cache. You probably
+ * want to use the getCache() method in this class instead of creating objects of the Cache
+ * class.
+ *
+ * @see Cache
*/
-
class CacheManager
{
var $cache;
- function clearCache()
- {
- $cacheInstance =& CacheManager::getCache();
- $cacheInstance->clearCache();
- }
-
/**
* Returns an instance of the cache.
*
* @param cacheEnabled Set this to false if you wish this class to always return no data,
* meaning that it will have to be loaded every time.
- * @return The global instance of the Cache_Lite class
+ * @return The current global instance of the Cache class
*/
function &getCache( $cacheEnabled = true )
{
@@ -49,11 +44,5 @@
}
return $cache;
}
-
- function disableCache( $category )
- {
- $cache =& CacheManager::getCache();
- $cache->disableCacheForCategory( $category );
- }
}
?>
\ No newline at end of file
Modified: plog/trunk/class/dao/articles.class.php
===================================================================
--- plog/trunk/class/dao/articles.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/dao/articles.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -1229,6 +1229,7 @@
$blogs = new Blogs();
$blogId = $query_result['blog_id'];
+ print("blog id = $blogId" );
$blogInfo = $blogs->getBlogInfo( $blogId );
$blogSettings = $blogInfo->getSettings();
Modified: plog/trunk/class/data/captcha/captcha.class.php
===================================================================
--- plog/trunk/class/data/captcha/captcha.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/data/captcha/captcha.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -24,6 +24,8 @@
define( "CAPTCHA_DEFAULT_CODE_LENGTH", 6 );
/**
+ * \ingroup Data
+ *
* Class to generate CAPTCHA images, based on Mark Wu's AuthImage plugin.
*
* Usage:
Modified: plog/trunk/class/data/jalalicalendar.class.php
===================================================================
--- plog/trunk/class/data/jalalicalendar.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/data/jalalicalendar.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -1,5 +1,7 @@
<?php
-/*
+/**
+\ingroup data
+
Jalali Date function by Milad Rastian (miladmovie AT yahoo DOT com)
//The main function which convert Gregorian to Jalali calendars is:
@@ -10,19 +12,6 @@
this function is simillar than date function in PHP
you can find more about it in http://jdf.farsiprojects.com
Copyright (C)2003 FARSI PROJECTS GROUP
-
- // //\\ // //\\ // //////
- // // \\ // // \\ // //
- // // \\ // // \\ // //
- \\ // /////\\\\\ // /////\\\\\ // //
- \\// // \\ /////// // \\ ////////// /////
-
- /////// //\\ ////// ////////
- // // // \\ // //
- // // // \\ // ///////
- // // /////\\\\\ // //
-//////// // \\ // /////////
-
*/
// lang file must be at the same directory
Modified: plog/trunk/class/data/plogcalendar.class.php
===================================================================
--- plog/trunk/class/data/plogcalendar.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/data/plogcalendar.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -18,7 +18,8 @@
*
* User classes will rarely need to use this class.
*/
- class PlogCalendar extends Calendar {
+ class PlogCalendar extends Calendar
+ {
var $_dayPosts;
var $_blogInfo;
Modified: plog/trunk/class/data/validator/templatesetvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/templatesetvalidator.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/data/validator/templatesetvalidator.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -7,6 +7,8 @@
define( 'ERROR_MISSING_BASE_FILES', -2 );
/**
+ * \ingroup Validator
+ *
* This is a more complex Validator (and a very specific one) that will validate whether
* the contents of a given folder are the same of a valid template set. In order to be valid
* a template folder must contain the following template files:
Modified: plog/trunk/class/database/db.class.php
===================================================================
--- plog/trunk/class/database/db.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/database/db.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -3,9 +3,23 @@
/**
* \defgroup Database
*
- * Database-related objects
+ * <p>This module includes all database-related objects.</p>
+ *
+ * <p>The most important one is the Db object, which provides one centralized way to get
+ * access to the current database connection. In fact, there is no reason for classes that require
+ * database access to use the PDb framework directly, as the Db::getDb() singleton method will
+ * transparently load the database information from the configuration file, connect to it and return
+ * a working connection.</p>
+ *
+ * <p>In order to get a working database connection, this is all you need to do:</p>
+ *
+ * <pre>
+ * $db =& Db::getDb();
+ * </pre>
+ *
+ * <p>For those classes that extend the Model base class, the private attribute Model::_db is a database
+ * connection so there is no need to initialize a new one.</p>
*/
-
include_once( PLOG_CLASS_PATH."class/config/configfilestorage.class.php" );
include_once( PLOG_CLASS_PATH."class/database/pdb/pdb.class.php" );
@@ -13,17 +27,31 @@
/**
* \ingroup Database
*
- * Provides a singleton for accessing the db and interfaces with ADOdb
+ * Provides a singleton for accessing the db and interfaces with PDb. Please use the
+ * getDb() singleton method to get access to the global database object instead of creating
+ * new objects every time.
*/
class Db
{
var $_prefix;
+ /**
+ * Constructor of the class
+ */
function Db()
{
}
+ /**
+ * Singleto method that should be used to get access to the global database connection. This method
+ * will load the database information from the database configuration file (config/config.properties.php) and
+ * will initialize a connection based on its information. If it is unable to start a new database connection, this
+ * method wil stop all processing and display an error message.
+ *
+ * @return Returns a reference to a PDb driver, with a working connection to the database.
+ * @see PDb::getDriver()
+ */
function &getDb()
{
static $db;
@@ -66,6 +94,15 @@
return $db;
}
+ /**
+ * Creates a new database instance based on the information provided
+ *
+ * @param host The database host where to connect
+ * @param username The username used for the connection
+ * @param password The password used for the connection
+ * @param dbname The name of the database
+ * @param returns a reference to a PDb driver or dies if there was an error connecting
+ */
function &getNewDb( $host, $username, $password, $dbname )
{
static $dbs;
@@ -90,17 +127,6 @@
return( $dbs[$key] );
}
- function &getDbCache()
- {
- static $dbcache;
-
- if( !isset( $dbcache )) {
- $dbcache=Array();
- }
-
- return $dbcache;
- }
-
/**
* returns the prefix as configured for this database connection
*
@@ -121,6 +147,19 @@
}
+ /**
+ * Builds a SELECT query
+ *
+ * @param tableName The table from where we want to build the SELECT query
+ * @param fieldsToFetch An array with the list of fields we'd like to fetch
+ * @param whereColumn Column used in the WHERE clause
+ * @param whereValue Value used in the WHERE clause
+ * @param orderColumn Column used to sort the data
+ * @param limit Number of records to return
+ * @param whereGlue Logical operator used to glue the different WHERE conditions, 'AND'
+ * by default.
+ * @return Returns the SELECT query defined by the provided parameters
+ */
function buildSelectQuery( $tableName,
$fieldsToFetch = array(),
$whereColumn = null,
@@ -146,6 +185,14 @@
return $query;
}
+ /**
+ * Builds an INSERT query
+ *
+ * @param tableName Name of the table where data is to be inserted
+ * @param keyValuePairs An associative array where the key is the name of the column and the
+ * value is the value of the column in the query
+ * @return Returns the INSERT query
+ */
function buildInsertQuery( $tableName,
$keyValuePairs )
{
@@ -165,6 +212,16 @@
return $query;
}
+ /**
+ * Builds an UPDATE query
+ *
+ * @param tableName Name of the table where data is to be inserted
+ * @param keyValuePairs An associative array where the key is the name of the column and the
+ * value is the value of the column in the query
+ * @param whereColumn Column used in the WHERE clause
+ * @param whereValue Value used in the WHERE clause
+ * @return Returns the UPDATE query
+ */
function buildUpdateQuery( $tableName,
$keyValuePairs,
$whereColumn = null,
@@ -189,6 +246,15 @@
return $query;
}
+ /**
+ * Builds a DELETE query
+ *
+ * @param tableName Name of the table where data is to be inserted
+ * @param whereColumn Column used in the WHERE clause
+ * @param whereValue Value used in the WHERE clause
+ * @param whereGlue Logical operator used to glue the different WHERE conditions, 'AND'
+ * by default.
+ */
function buildDeleteQuery( $tableName,
$whereColumn = null,
$whereValue = null,
@@ -204,6 +270,15 @@
return $query;
}
+ /**
+ * @private
+ * Adds the current database prefix to the given table name. If the table name does not have
+ * the prefix yet, it will be added in front of the table name but if it's already there, the table
+ * name will not be modified
+ *
+ * @param tableName Name of the table, without prefix.
+ * @return The table name with the prefix
+ */
function addTablePrefixToTableName( $tableName ) {
if ( !preg_match( "/^" . Db::getPrefix() . "/", $tableName) ) {
$tableName = Db::getPrefix() . $tableName;
@@ -211,7 +286,16 @@
return $tableName;
}
-
+ /**
+ * Builds a WHERE clause for SELECT and DELETE queries
+ *
+ * @param whereColumn The column, it can either be a single column or an array of columns. If it
+ * is an array of columns, it should be an associative array where the key is the name of the column
+ * and the value is the value assigned to this column.
+ * @param whereValue The value assigned to the column, in case $whereColumn is only one column
+ * @param whereGlue The glue used to link the different conditions
+ * @return A string that can be used as a WHERE clause in a query
+ */
function buildWhereConditions( $whereColumn, $whereValue, $whereGlue )
{
$queryPart = ' WHERE ';
@@ -233,12 +317,22 @@
return $queryPart;
}
+ /**
+ * Builds one single condition for a WHERE clause
+ *
+ * @param columnName the column name
+ * @param columnValue the value for the column
+ * @return A string as part of a WHERE clause
+ */
function buildWhereCondition( $columnName, $columnValue )
{
$db =& Db::getDb();
return $db->buildWhereCondition( $columnName, $columnValue );
}
+ /**
+ * @private
+ */
function _buildOrderCondition( $orderColumn )
{
preg_match( '/^(.)(.*)$/', $orderColumn, $matches );
@@ -274,7 +368,6 @@
* @return string the correctly quoted value
* @access public
*/
-
function quoteValue( $value )
{
if( is_numeric($value) )
@@ -321,4 +414,4 @@
return $string;
}
}
-?>
+?>
\ No newline at end of file
Modified: plog/trunk/class/database/pdb/datadict/pdbbasedatadict.class.php
===================================================================
--- plog/trunk/class/database/pdb/datadict/pdbbasedatadict.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/database/pdb/datadict/pdbbasedatadict.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -18,8 +18,13 @@
/**
- * Base class for data dictionaries. Implements most of the functionality.
+ * Base class for data dictionaries. Data dictionaries allow to use a meta-language to describe a database schema, which
+ * will be processed by the data dictionary and which will allow to automatically modify a database. This meta-language
+ * is independent of the database being used, so it can be used in different database environments.
*
+ * Data dictionaries in PDb work in exactly the same way as in ADOdb, please see more details about data dictionaries here:
+ * http://phplens.com/lens/adodb/docs-datadict.htm.
+ *
* \ingroup PDb
*/
class PDbBaseDataDict
@@ -45,17 +50,17 @@
/**
- Parse arguments, treat "text" (text) and 'text' as quotation marks.
- To escape, use "" or '' or ))
-
- Will read in "abc def" sans quotes, as: abc def
- Same with 'abc def'.
- However if `abc def`, then will read in as `abc def`
-
- @param endstmtchar Character that indicates end of statement
- @param tokenchars Include the following characters in tokens apart from A-Z and 0-9
- @returns 2 dimensional array containing parsed tokens.
- */
+ * Parse arguments, treat "text" (text) and 'text' as quotation marks.
+ * To escape, use "" or '' or ))
+ *
+ * Will read in "abc def" sans quotes, as: abc def
+ * Same with 'abc def'.
+ * However if `abc def`, then will read in as `abc def`
+ *
+ * @param endstmtchar Character that indicates end of statement
+ * @param tokenchars Include the following characters in tokens apart from A-Z and 0-9
+ * @returns 2 dimensional array containing parsed tokens.
+ */
function Lens_ParseArgs($args,$endstmtchar=',',$tokenchars='_.-')
{
$pos = 0;
@@ -164,31 +169,92 @@
return $tokens;
}
+
+ /**
+ * Given a field, return its metatype based on its real type, i.e. 'VARCHAR' would return 'C',
+ * 'TIMESTAMP' would return 'T' and so on. This method must be implemented by child classes as each
+ * database has its own data types.
+ *
+ * @param t The type
+ * @param len the field length
+ * @param fieldobj
+ * @return Returns a string with the meta type
+ */
+ function MetaType($t,$len=-1,$fieldobj=false)
+ {
+ // to be implemented by child classes
+ }
+
+ /**
+ * Given a metatype, return its equivalent database type
+ *
+ * @param meta The meta-type
+ * @return Returns a string with the real type
+ */
+ function ActualType($meta)
+ {
+ // to be implemented by child classes
+ }
+ /**
+ * Returns information about the tables in the current connection (a list of them)
+ *
+ * @return An array with the tables
+ */
function &MetaTables()
{
if (!$this->connection->IsConnected()) return array();
return $this->connection->MetaTables();
}
-
+
+ /**
+ * Returns information (the table schema) about the given table
+ *
+ * @param tab Name of the table
+ * @param upper
+ * @param schema
+ * @return An array with the table schema
+ */
function &MetaColumns($tab, $upper=true, $schema=false)
{
if (!$this->connection->IsConnected()) return array();
return $this->connection->MetaColumns($this->TableName($tab), $upper, $schema);
}
+ /**
+ * Returns information about primary keys in the given table
+ *
+ * @param tab Name of the table
+ * @param upper
+ * @param schema
+ * @return An array with information about the primary keys
+ */
function &MetaPrimaryKeys($tab,$owner=false,$intkey=false)
{
if (!$this->connection->IsConnected()) return array();
return $this->connection->MetaPrimaryKeys($this->TableName($tab), $owner, $intkey);
}
-
+
+ /**
+ * Returns information about indexes in the given table
+ *
+ * @param tab Name of the table
+ * @param upper
+ * @param schema
+ * @return An array with information about the indexes
+ */
function &MetaIndexes($table, $primary = false, $owner = false)
{
if (!$this->connection->IsConnected()) return array();
return $this->connection->MetaIndexes($this->TableName($table), $primary, $owner);
}
+ /**
+ * Adds quotes around a name if necessary
+ *
+ * @param name The name that should be quoted
+ * @return The quoted name if it needed any quotes, or unquoted if it didn't
+ */
function NameQuote($name = NULL)
{
if (!is_string($name)) {
@@ -216,6 +282,9 @@
return $name;
}
+ /**
+ * tbd
+ */
function TableName($name)
{
if ( $this->schema ) {
@@ -224,7 +293,13 @@
return $this->NameQuote($name);
}
- // Executes the sql array returned by GetTableSQL and GetIndexSQL
+ /**
+ * Executes the sql array returned by GetTableSQL and GetIndexSQL
+ *
+ * @param sql The SQL code to be executed, passed as an array of queries
+ * @param continueOnError Whether to stop after an error or not
+ * @return True if successful or false otherwise
+ */
function ExecuteSQLArray($sql, $continueOnError = true)
{
$rez = 2;
@@ -244,29 +319,33 @@
return $rez;
}
- /*
- Returns the actual type given a character code.
-
- C: varchar
- X: CLOB (character large object) or largest varchar size if CLOB is not supported
- C2: Multibyte varchar
- X2: Multibyte CLOB
-
- B: BLOB (binary large object)
-
- D: Date
- T: Date-time
- L: Integer field suitable for storing booleans (0 or 1)
- I: Integer
- F: Floating point number
- N: Numeric or decimal number
- */
-
+ /**
+ * Returns the actual type given a character code.
+ *
+ * - C: varchar
+ * - X: CLOB (character large object) or largest varchar size if CLOB is not supported
+ * - C2: Multibyte varchar
+ * - X2: Multibyte CLOB
+ * - B: BLOB (binary large object)
+ * - D: Date
+ * - T: Date-time
+ * - L: Integer field suitable for storing booleans (0 or 1)
+ * - I: Integer
+ * - F: Floating point number
+ * - N: Numeric or decimal number
+ */
function ActualType($meta)
{
return $meta;
}
+ /**
+ * Returns the SQL code necessary to create the given database
+ *
+ * @param dbname Name of the new database
+ * @param options Any additional options needed to create the database, or empty as default
+ * @return An array with SQL code needed to create the database
+ */
function CreateDatabase($dbname,$options=false)
{
$options = $this->_Options($options);
@@ -280,9 +359,15 @@
return $sql;
}
- /*
- Generates the SQL to create index. Returns an array of sql strings.
- */
+ /**
+ * Generates the SQL to create index.
+ *
+ * @param idxname Name of the index
+ * @param tabname Name of the table where the index will be created
+ * @param flds Names of the fields on which the index will work
+ * @param idxoptions Options needed to create the index
+ * @return Returns an array of sql strings.
+ */
function CreateIndexSQL($idxname, $tabname, $flds, $idxoptions = false)
{
if (!is_array($flds)) {
@@ -296,16 +381,32 @@
return $this->_IndexSQL($this->NameQuote($idxname), $this->TableName($tabname), $flds, $this->_Options($idxoptions));
}
+ /**
+ * Removes an index from a table
+ *
+ * @param idxname Name of the index
+ * @param tabname Name of the table in which the index exists
+ * @return Returns an array of SQL strings needed to remove an index
+ */
function DropIndexSQL ($idxname, $tabname = NULL)
{
return array(sprintf($this->dropIndex, $this->NameQuote($idxname), $this->TableName($tabname)));
}
+ /**
+ * tbd
+ */
function SetSchema($schema)
{
$this->schema = $schema;
}
+ /**
+ * Returns SQL code needed to add a colum to the database table
+ *
+ * @param tabname Name of the table
+ * @param flds An array with all the fields that will be added to the database
+ * @return An array with SQL code
function AddColumnSQL($tabname, $flds)
{
$tabname = $this->TableName ($tabname);
@@ -384,20 +485,37 @@
}
return $sql;
}
-
+
+ /**
+ * Generate the SQL to drop a table
+ *
+ * @param tabname Name of the table
+ * @return An array with SQL code to drop the table.
+ */
function DropTableSQL($tabname)
{
return array (sprintf($this->dropTable, $this->TableName($tabname)));
}
-
+
+ /**
+ * Generate the SQL to rename a table
+ *
+ * @param tabname Name of the table
+ * @return An array with SQL code to rename the table.
+ */
function RenameTableSQL($tabname,$newname)
{
return array (sprintf($this->renameTable, $this->TableName($tabname),$this->TableName($newname)));
}
- /*
- Generate the SQL to create table. Returns an array of sql strings.
- */
+ /**
+ * Generate the SQL to create table. Returns an array of sql strings.
+ *
+ * @param tabname Name of the table
+ * @param flds Table schema
+ * @param tableoptions Any extra options needed to create the table
+ * @return An array with SQL code to create the table according to the schema
+ */
function CreateTableSQL($tabname, $flds, $tableoptions=false)
{
if (!$tableoptions) $tableoptions = array();
@@ -416,11 +534,17 @@
return $sql;
}
+ /**
+ * @private
+ */
function _Triggers($tabname,$taboptions)
{
return array();
}
+ /**
+ * @private
+ */
function _array_change_key_case($an_array)
{
if (is_array($an_array)) {
@@ -434,6 +558,9 @@
return $an_array;
}
+ /**
+ * @private
+ */
function _GenFields($flds,$widespacing=false)
{
if (is_string($flds)) {
@@ -583,6 +710,9 @@
return array($lines,$pkey);
}
+ /**
+ * @private
+ */
function _IndexesSQL($tabname,$flds)
{
if (is_string($flds)) {
@@ -617,13 +747,10 @@
return($lines);
}
-
-
- /*
- GENERATE THE SIZE PART OF THE DATATYPE
- $ftype is the actual type
- $ty is the type defined originally in the DDL
- */
+
+ /**
+ * @private
+ */
function _GetSize($ftype, $ty, $fsize, $fprec)
{
if (strlen($fsize) && $ty != 'X' && $ty != 'B' && strpos($ftype,'(') === false) {
@@ -644,7 +771,10 @@
if ($fconstraint) $suffix .= ' '.$fconstraint;
return $suffix;
}
-
+
+ /**
+ * @private
+ */
function _IndexSQL($idxname, $tabname, $flds, $idxoptions)
{
$sql = array();
@@ -673,12 +803,18 @@
return $sql;
}
-
+
+ /**
+ * @private
+ */
function _DropAutoIncrement($tabname)
{
return false;
}
+ /**
+ * @private
+ */
function _TableSQL($tabname,$lines,$pkey,$tableoptions)
{
$sql = array();
@@ -712,9 +848,11 @@
return $sql;
}
- /*
- Sanitize options, so that array elements with no keys are promoted to keys
- */
+ /**
+ * Sanitize options, so that array elements with no keys are promoted to keys
+ *
+ * @private
+ */
function _Options($opts)
{
if (!is_array($opts)) return array();
@@ -726,12 +864,14 @@
return $newopts;
}
- /*
- "Florian Buzin [ easywe ]" <florian.buzin#easywe.de>
-
- This function changes/adds new fields to your table. You don't
- have to know if the col is new or not. It will check on its own.
- */
+ /**
+ * Generate the SQL to modify the schema of a table
+ *
+ * @param tabname Name of the table
+ * @param flds The new table schema
+ * @param tableoptions Any extra options needed
+ * @return An array with SQL code to modify the schema of the given table
+ */
function ChangeTableSQL($tablename, $flds, $tableoptions = false)
{
// check table exists
Modified: plog/trunk/class/database/pdb/datadict/pdbmysqldatadict.class.php
===================================================================
--- plog/trunk/class/database/pdb/datadict/pdbmysqldatadict.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/database/pdb/datadict/pdbmysqldatadict.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -9,6 +9,12 @@
include_once( PLOG_CLASS_PATH."class/database/pdb/datadict/pdbbasedatadict.class.php" );
+ /**
+ * Data dictionary for MySQL, used by PDb to be able to convert a table meta-definition
+ * into SQL executable code for altering the db schema, adding new fields, etc.
+ *
+ * \ingroup PDb
+ */
class PDbMysqlDataDict extends PDbBaseDataDict
{
var $databaseType = 'mysql';
@@ -18,7 +24,10 @@
var $dropIndex = 'DROP INDEX %s ON %s';
var $renameColumn = 'ALTER TABLE %s CHANGE COLUMN %s %s %s'; // needs column-definition!
-
+
+ /**
+ * @see PdbBaseDataDict::MetaType
+ */
function MetaType($t,$len=-1,$fieldobj=false)
{
if (is_object($t)) {
@@ -73,6 +82,9 @@
}
}
+ /**
+ * @see PdbBaseDataDict::ActualType
+ */
function ActualType($meta)
{
switch(strtoupper($meta)) {
@@ -103,7 +115,9 @@
}
}
- // return string must begin with space
+ /**
+ * @private
+ */
function _CreateSuffix($fname,$ftype,$fnotnull,$fdefault,$fautoinc,$fconstraint,$funsigned)
{
$suffix = '';
@@ -115,6 +129,9 @@
return $suffix;
}
+ /**
+ * @private
+ */
function _IndexSQL($idxname, $tabname, $flds, $idxoptions)
{
$sql = array();
Modified: plog/trunk/class/database/pdb/pdb.class.php
===================================================================
--- plog/trunk/class/database/pdb/pdb.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/database/pdb/pdb.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -1,6 +1,10 @@
<?php
/**
* \defgroup PDb
+ *
+ * Since LifeType 1.1, ADOdb is no longer part of LifeType and now all database interaction is handled via PDb
+ * a much tighter implementation of a database abstraction layer inspired on ADOdb (PDb is like ADOdb, with the
+ * only difference that only those methods from ADOdb that were used by LifeType's code were implemented)
*/
define( "PDB_DRIVER_FOLDER", PLOG_CLASS_PATH."class/database/pdb/drivers/" );
@@ -8,21 +12,24 @@
/**
* PDb
*
- * Plog's own lightweight database abstraction layer
+ * LifeType's own lightweight database abstraction layer modelled after ADOdb but only implementing
+ * those methods that are really needed.
*
* \ingroup PDb
*/
class PDb
{
+ /**
+ * Constructor of the class
+ */
function PDb()
- {
-
+ {
}
/**
* return the right driver type
*
- * @param driver the driver name. Supported types are
+ * @param driver the driver name. Supported types in LifeType 1.1 are:
*
* - mysql
*
@@ -48,15 +55,28 @@
}
}
- function getValidDrivers() {
- $_drivers = Array( "mysql" => "PDbMySQLDriver",
- "postgres" => "PDbPostgresDriver",
- "dbx" => "PDbDbxDriver" );
+ /**
+ * Returns an array containing the names of the drivers available
+ *
+ * @return An associative array, where the key is the name of the driver and the
+ * value is the name of the class implementing the driver
+ */
+ function getValidDrivers()
+ {
+ $_drivers = Array( "mysql" => "PDbMySQLDriver" );
return $_drivers;
}
- function listDrivers() {
+ /**
+ * Returns an array with only the driver names, which are the only suitable names for the call
+ * to PDb::getDriver
+ *
+ * @return An array with the driver names
+ * @see PDb::getDriver()
+ */
+ function listDrivers()
+ {
return array_keys( PDb::getValidDrivers() );
}
}
Modified: plog/trunk/class/object/loggable.class.php
===================================================================
--- plog/trunk/class/object/loggable.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/object/loggable.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -1,8 +1,13 @@
<?php
/**
- * Please extend this class if you wish to allow your class to log
- * data to the logging streams
+ * \ingroup Core
+ *
+ * Please extend this class if you wish to provide a basic loggin channel for your classes via the
+ * <b>$this->log</b> public attribute. The "default" logger will be used, make sure it is configured
+ * properly in the file config/logging.properties.php.
+ *
+ * @see LoggerManager
*/
class Loggable
{
Modified: plog/trunk/class/object/object.class.php
===================================================================
--- plog/trunk/class/object/object.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/object/object.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -1,21 +1,5 @@
<?php
-/**
-
-\mainpage
-
-<b>Welcome to the pLog API!</b>
-
-<p>This is the starting point of the pLog API. The API provides an abstraction layer to represent
-all entities that are used in pLog: Articles, Users, Blogs, etc. The API borrows a lot of ideas from
-strong object-oriented languages such as Java and C# so do not be surprised if some of the design decisions
-look strangely familiar.
-</p>
-<p>This documentation should only be used as a reference, and for checking which methods each class has and to
-get some basic information about them. This documentation does not try to be an in-depth introduction to the
-pLog API and the best place for developers to get acquainted with pLog is the wiki: http://wiki.plogworld.net/index.php/Developers_Documentation
- */
-
if(PHP_VERSION < 5)
include_once( PLOG_CLASS_PATH."class/object/exception.class.php" );
@@ -23,31 +7,19 @@
include_once( PLOG_CLASS_PATH."debug.php" );
/**
- * \defgroup Core
- *
- * These classes are at the lowest level of the pLog object model. Included here is the Object class,
- * which is the base class from which all other classes in pLog inherit. The Core package also includes
- * classes for dealing with <b>simulated</b> exceptions in PHP4 (they are disabled in PHP5 and the
- * framework will use native exceptions), and a bit of reflection too using PHP4's reflection
- * features.
- */
-
- /**
* \ingroup Core
*
- * This is the highest class on the top of our hierarchy. Provides some common methods
- * useful to deal with objects, an also some commodity methods for debugging such as
- * toString, which will dump the names and the values of the attributes of the object.
- * All the objects should inherit from this one and call this constructor manually, due
- * to PHP not automatically calling the parent's class constructor when inheriting.
+ * <p><b>NOTE:</b> As of LifeType 1.1, this class is deprecated and all other classes in
+ * LifeType do not longer extend this class. This dependency was removed due to performance
+ * and memory usage.</p>
+ * <p>If you have any custom code that is still extending this class, please make the necessary
+ * changes to remove the dependency as this class will most likely be removed in future versions
+ * of LifeType.</p>
*
- * <b>NOTE:</b> As of pLog 1.1, this object is deprecated and all objects in pLog do not depend
- * on the base class Object. This object has been left here for backwards compatibility (plugins, etc)
- * but you are not advised to depend on it for new plugins or development.
- *
* @deprecated
*/
- class Object {
+ class Object
+ {
var $_objId;
var $log;
Modified: plog/trunk/class/summary/action/summaryaction.class.php
===================================================================
--- plog/trunk/class/summary/action/summaryaction.class.php 2006-06-23 21:23:42 UTC (rev 3646)
+++ plog/trunk/class/summary/action/summaryaction.class.php 2006-06-23 22:46:04 UTC (rev 3647)
@@ -45,8 +45,8 @@
}
}
else {
- $sessionLocale = SessionManager::getSessionValue( "summaryLang" );
- if( $sessionLocale ) {
+ $sessionLocale = SessionManager::getSessionValue( "summaryLang" );
+ if( $sessionLocale ) {
$localeCode = $sessionLocale;
}
elseif ( $this->_config->getValue( "use_http_accept_language_detection", HTTP_ACCEPT_LANGUAGE_DETECTION) == 1 )
More information about the pLog-svn
mailing list