[pLog-svn] r1657 - in plog/trunk/class: . data data/Date data/forms
data/pager data/validator data/validator/rules
oscar at devel.plogworld.net
oscar at devel.plogworld.net
Wed Mar 30 20:25:51 GMT 2005
Author: oscar
Date: 2005-03-30 20:25:51 +0000 (Wed, 30 Mar 2005)
New Revision: 1657
Modified:
plog/trunk/class/Doxyfile
plog/trunk/class/data/Date.class.php
plog/trunk/class/data/Date/Calc.class.php
plog/trunk/class/data/Date/Human.class.php
plog/trunk/class/data/Date/Span.class.php
plog/trunk/class/data/Date/TimeZone.class.php
plog/trunk/class/data/forms/formvalidator.class.php
plog/trunk/class/data/htmlcalendar.class.php
plog/trunk/class/data/kses.class.php
plog/trunk/class/data/mimetype.class.php
plog/trunk/class/data/pager/pager.class.php
plog/trunk/class/data/plogcalendar.class.php
plog/trunk/class/data/stringutils.class.php
plog/trunk/class/data/textfilter.class.php
plog/trunk/class/data/timestamp.class.php
plog/trunk/class/data/validator/arrayvalidator.class.php
plog/trunk/class/data/validator/chainedvalidator.class.php
plog/trunk/class/data/validator/emailvalidator.class.php
plog/trunk/class/data/validator/emptyvalidator.class.php
plog/trunk/class/data/validator/httpurlvalidator.class.php
plog/trunk/class/data/validator/integervalidator.class.php
plog/trunk/class/data/validator/ipmatchvalidator.class.php
plog/trunk/class/data/validator/passwordvalidator.class.php
plog/trunk/class/data/validator/rules/arrayrule.class.php
plog/trunk/class/data/validator/rules/emaildnsrule.class.php
plog/trunk/class/data/validator/rules/emailformatrule.class.php
plog/trunk/class/data/validator/rules/equalrule.class.php
plog/trunk/class/data/validator/rules/intrule.class.php
plog/trunk/class/data/validator/rules/ipcidrformatrule.class.php
plog/trunk/class/data/validator/rules/ipformatrule.class.php
plog/trunk/class/data/validator/rules/iprangerule.class.php
plog/trunk/class/data/validator/rules/nonemptyrule.class.php
plog/trunk/class/data/validator/rules/numericrule.class.php
plog/trunk/class/data/validator/rules/rangerule.class.php
plog/trunk/class/data/validator/rules/rule.class.php
plog/trunk/class/data/validator/rules/uintrule.class.php
plog/trunk/class/data/validator/rules/urlformatrule.class.php
plog/trunk/class/data/validator/stringvalidator.class.php
plog/trunk/class/data/validator/templatevalidator.class.php
plog/trunk/class/data/validator/uploadvalidator.class.php
plog/trunk/class/data/validator/usernamevalidator.class.php
plog/trunk/class/data/validator/validation.class.php
plog/trunk/class/data/validator/validationlist.class.php
plog/trunk/class/data/validator/validator.class.php
Log:
finished the documentation of the data/ folder
Modified: plog/trunk/class/Doxyfile
===================================================================
--- plog/trunk/class/Doxyfile 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/Doxyfile 2005-03-30 20:25:51 UTC (rev 1657)
@@ -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/
+INPUT = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/ mail/ bayesian/ misc/ net/ data/
# 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/data/Date/Calc.class.php
===================================================================
--- plog/trunk/class/data/Date/Calc.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date/Calc.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -8,6 +8,8 @@
}
/**
+ * \ingroup Data
+ *
* Date_Calc is a calendar class used to calculate and
* manipulate calendar dates and retrieve dates in a calendar
* format. It does not rely on 32-bit system date stamps, so
@@ -29,7 +31,6 @@
* @version 1.2.6
* @author Monte Ohrt <monte at ispi.net>
*/
-
class Date_Calc
{
/**
Modified: plog/trunk/class/data/Date/Human.class.php
===================================================================
--- plog/trunk/class/data/Date/Human.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date/Human.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -20,6 +20,8 @@
//
/**
+ * \ingroup Data
+ *
* Class to convert date strings between Gregorian and Human calendar formats.
* The Human Calendar format has been proposed by Scott Flansburg and can be
* explained as follows:
Modified: plog/trunk/class/data/Date/Span.class.php
===================================================================
--- plog/trunk/class/data/Date/Span.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date/Span.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -23,6 +23,7 @@
require_once PLOG_CLASS_PATH.'class/data/Date/Calc.class.php';
/**
+ *
* Non Numeric Separated Values (NNSV) Input Format.
*
* Input format guessed from something like this:
@@ -39,8 +40,6 @@
* '3-12-30-18' -> 3, 12, 30, 18<br>
* '3 days, 12-30-18' -> 3, 12, 30, 18<br>
* '12:30 with 18 secs' -> 0, 12, 30, 18<br>
- *
- * @const int
*/
define('DATE_SPAN_INPUT_FORMAT_NNSV', 1);
@@ -59,9 +58,10 @@
$_DATE_SPAN_INPUT_FORMAT = DATE_SPAN_INPUT_FORMAT_NNSV;
/**
+ * \ingroup Data
+ *
* Generic time span handling class for PEAR.
*
- * @package Date
* @author Leandro Lucarella <llucax at php.net>
* @version $Revision: 1.4 $
* @since 1.4
Modified: plog/trunk/class/data/Date/TimeZone.class.php
===================================================================
--- plog/trunk/class/data/Date/TimeZone.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date/TimeZone.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -24,6 +24,8 @@
//
/**
+ * \ingroup Data
+ *
* TimeZone representation class, along with time zone information data.
*
* TimeZone representation class, along with time zone information data.
@@ -41,7 +43,6 @@
*
*
* @author Baba Buehler <baba at babaz.com>
- * @package Date
* @access public
* @version 1.0
*/
Modified: plog/trunk/class/data/Date.class.php
===================================================================
--- plog/trunk/class/data/Date.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/Date.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,9 +1,5 @@
<?php
- /**
- * @package data
- */
-
/* vim: set expandtab tabstop=4 shiftwidth=4: */
// +----------------------------------------------------------------------+
// | PHP Version 4 |
@@ -62,6 +58,8 @@
/**@#-*/
/**
+ * \ingroup Data
+ *
* Generic date handling class for PEAR.
*
* Generic date handling class for PEAR. Attempts to be time zone aware
@@ -69,7 +67,6 @@
* Date::Calc on Date objects.
*
* @author Baba Buehler <baba at babaz.com>
- * @package Date
* @access public
*/
class Date
Modified: plog/trunk/class/data/forms/formvalidator.class.php
===================================================================
--- plog/trunk/class/data/forms/formvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/forms/formvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -14,7 +14,7 @@
*
* This the class used for form validation. It works helped by the Validator classes to perform data validation,
* as well as in conjunction with the Action and View classes. It is fact internally used by the Action class and it is
- * capable of reporting to the view class which fields of a given form genrated an error.
+ * capable of reporting to the view class which fields of a given form generated an error.
*/
class FormValidator extends Object
{
Modified: plog/trunk/class/data/htmlcalendar.class.php
===================================================================
--- plog/trunk/class/data/htmlcalendar.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/htmlcalendar.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,46 +1,36 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
-
-// PHP Calendar Class Version 1.4 (5th March 2001)
-//
-// Copyright David Wilkinson 2000 - 2001. All Rights reserved.
-//
-// This software may be used, modified and distributed freely
-// providing this copyright notice remains intact at the head
-// of the file.
-//
-// This software is freeware. The author accepts no liability for
-// any loss or damages whatsoever incurred directly or indirectly
-// from the use of this script. The author of this software makes
-// no claims as to its fitness for any purpose whatsoever. If you
-// wish to use this software you should first satisfy yourself that
-// it meets your requirements.
-//
-// URL: http://www.cascade.org.uk/software/php/calendar/
-// Email: davidw at cascade.org.uk
-
-
-/**
- * Generates an html calendar
+
+/**
+ * \ingroup Data
+ *
+ * Generates an html calendar
*
- * Class borrowed from http://www.cascade.org.uk/software/php/calendar
+ * PHP Calendar Class Version 1.4 (5th March 2001)
*
- * Modified by me to make in inherit from the Object class.
+ * Copyright David Wilkinson 2000 - 2001. All Rights reserved.
+ *
+ * This software may be used, modified and distributed freely
+ * providing this copyright notice remains intact at the head
+ * of the file.
+ *
+ * This software is freeware. The author accepts no liability for
+ * any loss or damages whatsoever incurred directly or indirectly
+ * from the use of this script. The author of this software makes
+ * no claims as to its fitness for any purpose whatsoever. If you
+ * wish to use this software you should first satisfy yourself that
+ * it meets your requirements.
+ *
+ * URL: http://www.cascade.org.uk/software/php/calendar/
+ * Email: davidw at cascade.org.uk
+ *
+ * Modified by fuze (http://www.fuze.org) on 2004/07/11
+ *
+ * Just changed the html table output for better (CSS) accessibility
+ * and variable names.
*/
-
- /**
- * Modified by fuze (http://www.fuze.org) on 2004/07/11
- *
- * Just changed the html table output for better (CSS) accessibility
- * and variable names.
- */
-
+
class Calendar extends Object
{
/*
Modified: plog/trunk/class/data/kses.class.php
===================================================================
--- plog/trunk/class/data/kses.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/kses.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,14 +1,15 @@
<?php
-
- /**
- * @package data
- */
-
- /*
+ /**
+ * \ingroup Data
+ *
* This is a fork of a slick piece of procedural code called 'kses' written by Ulf Harnhammar
* The entire set of functions was wrapped in a PHP object with some internal modifications
* by Richard Vasquez (http://www.chaos.org/) 7/25/2003
*
+ * The pLog project has made a few improvements to the code, for example including a mode where
+ * the filter can convert invalid XHTML code into valid markup, as well as a more aggressive
+ * filtering mode.
+ *
* The original (procedural) version of the code can be found at:
* http://sourceforge.net/projects/kses/
*
@@ -46,7 +47,6 @@
*
* Email: View current valid email address at http://www.chaos.org/contact/
*/
-
class kses
{
var $allowed_protocols = array('http', 'https', 'ftp', 'news', 'nntp', 'telnet', 'gopher', 'mailto', 'irc');
Modified: plog/trunk/class/data/mimetype.class.php
===================================================================
--- plog/trunk/class/data/mimetype.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/mimetype.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,13 +1,10 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
/**
+ * \ingroup Data
+ *
* Copyright (C) 2002 Jason Sheets <jsheets at shadonet.com>.
* All rights reserved.
*
@@ -63,7 +60,7 @@
*
* Example:
*
- * $mimetype = new mimetype();
+ * $mimetype = new MimeType();
* print $mimetype->getType('acrobat.pdf');
*
* Author: Jason Sheets <jsheets at shadonet.com>
@@ -78,7 +75,8 @@
* types as an static variable inside the class, so that it does not have to be rebuilt
* everytime when calling getType.
*/
-class MimeType extends Object {
+class MimeType extends Object
+{
var $mimetypes = Array(
"ez" => "application/andrew-inset",
Modified: plog/trunk/class/data/pager/pager.class.php
===================================================================
--- plog/trunk/class/data/pager/pager.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/pager/pager.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,7 +6,47 @@
define("DEFAULT_PAGER_MAX_PAGES", 1);
/**
- * generic implementation of a pager
+ * \defgroup Pager
+ *
+ * generic implementation of a pager. It doesn't take of generating SQL queries for paging or
+ * anythign like that, it only takes care of generating the number of pages based on the number
+ * of registers, keeping track of the current page, etc.
+ *
+ * There also needs to be some display logic in order to get it to work fine.
+ *
+ * At the PHP level, some code like this is necessary:
+ *
+ * <pre>
+ * $pager = new Pager( "?op=editPosts&showStatus={$this->_showStatus}&page=",
+ * $this->_page,
+ * $numPosts,
+ * $this->_itemsPerPage );
+ * $view->setValue( "pager", $pager );
+ * </pre>
+ *
+ * The first parameter passed to the constructor is the string that the pager class will use
+ * to generate the page links. It will only append a page number, nothing else.
+ *
+ * At the Smarty/template level, some code like this is necessary in order to display the links
+ * properly, etc:
+ *
+ * <pre>
+ * {if !$pager->isFirstPage() && !$pager->isEmpty()}
+ * <a class="pagerLink" href="{$pager->getPrevPageLink()}">«Prev</a>
+ * {/if}
+ * {foreach from=$pager->getPageLinks() item=pageLink key=pageId}
+ * {if $pageId == $pager->getCurrentPage()}
+ * <span class="pagerCurrent"> {$pageId} >/span<
+ * {else}
+ * <a class="pagerLink" href="{$pageLink}"> {$pageId} </a>
+ * {/if}
+ * {/foreach}
+ * {if !$pager->isLastPage() && !$pager->isEmpty()}
+ * <a class="pagerLink" href="{$pager->getNextPageLink()}">Next»</a>
+ * {/if}
+ * </pre>
+ *
+ * The display logic might look a bit complex but it is unavoidable...
*/
class Pager extends Object
{
@@ -22,11 +62,13 @@
/**
- * @param baseUrl
- * @param offset
- * @param totalRegs
- * @param regsForPage
- * @param maxPages
+ * Constructor of the pager
+ *
+ * @param baseUrl The base url that will be used to generate the different URLs to the pages
+ * @param curPage The current page
+ * @param totalRegs The total number of registers
+ * @param regsForPage The maximum number of registers per page, defaults to
+ * DEFAULT_PAGER_REGS_FOR_PAGE
*/
function Pager($baseUrl, $curPage, $totalRegs, $regsForPage = DEFAULT_PAGER_REGS_FOR_PAGE )
{
@@ -41,15 +83,17 @@
}
/**
- * Add function info here
- */
+ * Sets the base url
+ *
+ * @param url The url
+ */
function setBaseUrl($url)
{
$this->_baseUrl = $url;
}
/**
- * Add function info here
+ * @return returns the base url
*/
function getBaseUrl()
{
@@ -57,40 +101,40 @@
}
/**
- * Add function info here
- */
+ * @return Returns the current total amount of registers
+ */
function getTotalRegs()
{
return $this->_totalRegs;
}
/**
- * Add function info here
- */
+ * @return Returns the current number of records per page
+ */
function getRegsForPage()
{
return $this->_regsForPage;
}
/**
- * Add function info here
- */
+ * @return Returns the maximum number of pages
+ */
function getMaxPages()
{
return $this->_maxPages;
}
/**
- * Add function info here
- */
+ * @return The total number of pages
+ */
function getTotalPages()
{
return $this->_totalPages;
}
/**
- * Add function info here
- */
+ * @return The current page
+ */
function getCurrentPage()
{
return $this->_curPage;
@@ -125,39 +169,39 @@
}
/**
- * Add function info here
- */
+ * @return Returns the current start page, if any
+ */
function getStartPage()
{
return $this->_startPage;
}
/**
- * Add function info here
- */
+ * @return Returns the last page
+ */
function getEndPage()
{
return $this->_endPage;
}
/**
- * Add function info here
- */
+ * @return True if the current page is the first page or false otherwise
+ */
function isFirstPage()
{
return ($this->_curPage == 1);
}
/**
- * Add function info here
- */
+ * @return Returns true if the current page is the last one or false otherwise
+ */
function isLastPage()
{
return ($this->_curPage == $this->_totalPages);
}
/**
- *
+ * @return Returns an array containing all the links to the different pages
*/
function getPageLinks()
{
@@ -165,7 +209,7 @@
}
/**
- *
+ * @return Returns a link to the next page
*/
function getNextPageLink()
{
@@ -173,7 +217,7 @@
}
/**
- *
+ * @return Returns a link to the previous page
*/
function getPrevPageLink()
{
@@ -181,7 +225,7 @@
}
/**
- * returns the link to the first page
+ * @return returns the link to the first page
*/
function getFirstPageLink()
{
@@ -189,7 +233,7 @@
}
/**
- * returns the link to the last page
+ * @return returns the link to the last page
*/
function getLastPageLink()
{
@@ -224,8 +268,8 @@
}
/**
- * Add function info here
- */
+ * @private
+ */
function _init()
{
$this->_totalPages = ceil($this->_totalRegs / $this->_regsForPage);
Modified: plog/trunk/class/data/plogcalendar.class.php
===================================================================
--- plog/trunk/class/data/plogcalendar.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/plogcalendar.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/htmlcalendar.class.php" );
include_once( PLOG_CLASS_PATH."class/locale/locale.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
@@ -12,19 +7,23 @@
include_once( PLOG_CLASS_PATH."class/dao/bloginfo.class.php" );
include_once( PLOG_CLASS_PATH."class/locale/locales.class.php" );
- /**
+ /**
+ * \ingroup Data
+ *
* A derived class is required to reimplement some methods from the parent
* Calendar class to add things like links to the days and so on.
* This one also converts the original HtmlCalendar into Locale aware, respecting
- * things like the first day of the week and the abbreviations of the days of the week.
+ * things like the first day of the week and the abbreviations of the days of the week.
+ *
+ * User classes will rarely need to use this class.
*/
- class PlogCalendar extends Calendar {
+ class PlogCalendar extends Calendar
+ {
var $_dayPosts;
- var $_blogInfo;
+ var $_blogInfo;
+ var $rg;
- var $rg;
-
/**
* Constructor.
*
@@ -64,7 +63,9 @@
/**
* Function overwritten from the base one, so that we can display links for the
- * next month and the previous month
+ * next month and the previous month
+ *
+ * @see Calendar::getCalendarLink()
*/
function getCalendarLink( $month, $year )
{
@@ -79,7 +80,9 @@
/**
* Function overwritten from the base one, so that we can display a link for the days
- * that have posts
+ * that have posts
+ *
+ * @see Calendar::getDateLink()
*/
function getDateLink( $day, $month, $year )
{
Modified: plog/trunk/class/data/stringutils.class.php
===================================================================
--- plog/trunk/class/data/stringutils.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/stringutils.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,19 +1,32 @@
<?php
- /**
- * @package data
+ include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
+
+ /**
+ * \ingroup Data
+ *
+ * Basic methods for formatting or doing nasty things to strings :-)
*/
-
-
- include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
-
- class StringUtils extends Object {
-
+ class StringUtils extends Object
+ {
+
+ /**
+ * Alias for htmlspecialchars
+ * @static
+ */
function htmlTranslate( $string )
{
return htmlspecialchars( $string );
}
-
+
+ /**
+ * cuts a string at a given character
+ *
+ * @param string
+ * @param n
+ * @return The reduced string
+ * @static
+ */
function cutString( $string, $n )
{
return substr( $string, 0, $n );
@@ -23,7 +36,8 @@
* Returns an array with all the links in a string.
*
* @param string The string
- * @return An array with the links in the string.
+ * @return An array with the links in the string.
+ * @static
*/
function getLinks( $string )
{
@@ -43,7 +57,8 @@
* Returns a size formatted and with its unit: "bytes", "KB", "MB" or "GB"
*
* @param size The amount
- * @return A string with the formatted size.
+ * @return A string with the formatted size.
+ * @static
*/
function formatSize( $size )
{
@@ -57,7 +72,9 @@
* Returns a string in a readable and url-compliant format.
*
* @param string The string
- * @return A string ready to use in urls.
+ * @return A string ready to use in urls.
+ * @static
+ * @see TextFilter::urlize()
*/
function text2url( $string )
{
@@ -83,12 +100,12 @@
}
/**
- * extremely lame function. I'm sure there are better ways to do this in php
- * but I can't think of any myself at the moment :-)
+ * extremely lame function.
*
* @param count how many times we'd like to repeat the character
* @param char The character (or string) we'd like to repeat
- * @return The resulting string
+ * @return The resulting string
+ * @static
*/
function pad( $count, $char = " ")
{
Modified: plog/trunk/class/data/textfilter.class.php
===================================================================
--- plog/trunk/class/data/textfilter.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/textfilter.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,18 +1,22 @@
<?php
/**
- * @package data
+ * \defgroup Data
+ *
+ * The Data module includes all sorts of functions that deal with data manipulation such as Validator
+ * classes, text formatters or pagers
*/
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
include_once( PLOG_CLASS_PATH."class/data/kses.class.php" );
include_once( PLOG_CLASS_PATH."class/data/stringutils.class.php" );
/**
- * Implements some text filters, for example removing javascript
- * code from a string or removing any non-allowed character.
+ * \ingroup Data
+ *
+ * Implements some text filters that can be used to remove Javascript code, or convert
+ * non-XHTML code into valid XHTML code, etc.
*/
class TextFilter extends Object
{
@@ -114,6 +118,8 @@
/**
* Alias for filterHTMLEntities
+ *
+ * @see filterHTMLEntities
*/
function filterXMLEntities( $string )
{
@@ -137,27 +143,6 @@
}
/**
- * Translates all the >a href="..."< tags of a text to include the
- * target="blank_" parameter so that they will open in a new window
- */
- function linksInNewWindow( $text )
- {
- $text = str_replace( "<a ", "<a target=\"blank_\" ", $text );
-
- return $text;
- }
-
- function translateSmileys( $text )
- {
- foreach( $this->_smileys as $symbol => $icon ) {
- $new_text = str_replace( $symbol, $icon, $text );
- $text = $new_text;
- }
-
- return $text;
- }
-
- /**
* Texturize function borrowed from http://photomatt.net/tools/texturize
*
* Takes care of "beautifying" code typed by users.
@@ -212,6 +197,9 @@
*
* Takes care of "beautifying" text, by adding <p> tags to blocks of texts without the users
* needing to know any html.
+ *
+ * @param pee
+ * @param br
*/
function autoP($pee, $br=1)
{
@@ -380,6 +368,17 @@
return $newtext;
}
+ /**
+ * Given a string, convert it into something that can be used in a URL (it probably doesn't work very
+ * well with non iso-8859-X strings) It will remove the following characters:
+ *
+ * ; / ? : @ & = + $ ,
+ *
+ * It will convert accented characters such as , , , etc to their non-accented counterparts (a, e, i) And
+ * any other non-alphanumeric character that hasn't been removed or replaced will be thrown away.
+ *
+ * @param string The string that we wish to convert into something that can be used as a URL
+ */
function urlize( $string )
{
// remove unnecessary spaces and make everything lower case
@@ -400,7 +399,10 @@
}
/**
- * xhtml-izes a string
+ * xhtml-izes a string. It uses the KSes filter for the task as long as the configuration parameter
+ * xhtml_converter_enabled is enabled. If xhtml_converter_aggreesive_mode_enabled is also enabled,
+ * KSes will be set into "aggressive" mode and it will try to fix even more problems with the XHTML
+ * markup (but it can also introduce more mistakes)
*
* @param string
* @return the xhtml-ized string
@@ -423,7 +425,7 @@
}
/**
- * tbd
+ * @private
*/
function checkboxToBoolean( $value )
{
Modified: plog/trunk/class/data/timestamp.class.php
===================================================================
--- plog/trunk/class/data/timestamp.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/timestamp.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
include_once( PLOG_CLASS_PATH."class/locale/locales.class.php" );
@@ -18,7 +13,27 @@
define( "TIME_DIFFERENCE_CALCULATION_DYNAMIC", 0 );
define( "TIME_DIFFERENCE_CALCULATION_STATIC", 1 );
-
+
+ /**
+ * \ingroup Data
+ *
+ * This class allows to deal with all sorts of different date formats, as many as the PEAR::Date class
+ * supports (Timestamp started as an independent class but later on due to requirements it was developed
+ * as an extension for PEAR::Date, maintaining the previous interface for compatibility reasons)
+ *
+ * PEAR::Date has its own documentation available here: http://pear.php.net/package/Date/docs/1.4.2/Date/Date.html
+ *
+ * The formats supported by PEAR::Date are:
+ *
+ * - DATE_FORMAT_ISO (YYYY-MM-DD HH:MM:SS)
+ * - DATE_FORMAT_ISO_BASIC (YYYYMMSSTHHMMSS(Z|(+/-)HHMM)?)
+ * - DATE_FORMAT_ISO_EXTENDED (YYYY-MM-SSTHH:MM:SS(Z|(+/-)HH:MM)?)
+ * - DATE_FORMAT_ISO_EXTENDED_MICROTIME (YYYY-MM-SSTHH:MM:SS(.S*)?(Z|(+/-)HH:MM)?)
+ * - DATE_FORMAT_TIMESTAMP (YYYYMMDDHHMMSS)
+ * - DATE_FORMAT_UNIXTIME (seconds since the unix epoch)
+ *
+ * @see Date
+ */
class Timestamp extends Date
{
@@ -29,6 +44,8 @@
* Creates a Timestamp object
* If $timestamp is empty or not specified, creates a timestamp
* taking the current time
+ *
+ * @param timestamp a valid SQL timestamp (DATE_FORMAT_TIMESTAMP / YYYYMMDDHHMMSS)
*/
function Timestamp( $timestamp = null )
{
@@ -58,6 +75,7 @@
* century will be '2000', not 21.
*
* @return An integer value representing the current century.
+ * @deprecated
*/
function getCentury()
{
@@ -97,6 +115,9 @@
die();
}
+ /**
+ * @return Returns the current month, as a value from "00" to "12"
+ */
function getMonth()
{
// call the parent getMonth() method
@@ -107,6 +128,11 @@
return $month;
}
+ /**
+ * Sets a new value for the minutes in this timestamp
+ *
+ * @param newMinutes the new value for the minutes
+ */
function setMinutes( $newMinutes )
{
$this->setMinute( $newMinutes );
Modified: plog/trunk/class/data/validator/arrayvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/arrayvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/arrayvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,16 +1,16 @@
<?php
- /**
- * @package data
- */
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/arrayrule.class.php" );
/**
- * validates if a value is a php array... very useful when we are expecting
+ * \ingroup Validator
+ *
+ * validates if a value is a php array. Useful when we are expecting
* parameters as array in a request and we'd like to know whether we're really
- * receiving an array
+ * receiving an array.
+ *
+ * @see ArrayRule
*/
class ArrayValidator extends Validator
{
Modified: plog/trunk/class/data/validator/chainedvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/chainedvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/chainedvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,20 +1,37 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
/**
+ * \ingroup Validator
+ *
* Validator class that allows to make chained validators so that we can validate for more complex
* rules. The parameter for the constructor is an array of Validator objects that we are going to
- * chain... Well in fact, we're not going to chain the validators but their rules, one after each
- * other using the Validator::addValidator() method
+ * chain.
+ *
+ * Internally, this class is not actually going to chain the validators but their rules, one after each
+ * other using the Validator::addValidator() method.
+ *
+ * You can either create your own brand new custom Validator class and add the rules that you need
+ * or if you know that some Validator classes are already doing what you need, you can always
+ * chain them by using the ChainedValidator class.
+ *
+ * Example:
+ *
+ * <pre>
+ * $val = new ChainedValidator( Array( new StringValidator(),
+ * new UsernameValidator());
+ * $result = $val->validate( $value );
+ * </pre>
*/
class ChainedValidator extends Validator
{
+ /**
+ * Constructor of the chained validator
+ *
+ * @param validators An array of Validator objects which implement the logic that
+ * we need
+ */
function ChainedValidator( $validators )
{
$this->Validator();
Modified: plog/trunk/class/data/validator/emailvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/emailvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/emailvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,20 +1,27 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/emailformatrule.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/emaildnsrule.class.php" );
/**
- * Extends the validator class to determine wether an email address is valid or not.
+ * \ingroup Validator
+ *
+ * Implements validation of email addresses. If check_email_address_validity is set to
+ * enabled, it will also check whether the email address is valid in the given email server
+ * by adding an EmailDnsRule to the list of rules to validate.
+ *
+ * @see EmailFormatRule
+ * @see EmailDnsRule
*/
class EmailValidator extends Validator
{
+ /**
+ * The constructor only initializes the validator and depending on the
+ * value of check_email_address_validity, it will also add a EmailDnsRule
+ * rule to check for the validity of the mailbox in the given email server
+ */
function EmailValidator()
{
$this->Validator();
Modified: plog/trunk/class/data/validator/emptyvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/emptyvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/emptyvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,17 +1,20 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
/**
- * Empty validation class that always returns true
+ * \ingroup Validator
+ *
+ * Empty validation class that always returns true.
*/
class EmptyValidator extends Validator
- {
+ {
+ /**
+ * This method always return true
+ *
+ * @param value
+ * @return Always true
+ */
function validate( $value )
{
return true;
Modified: plog/trunk/class/data/validator/httpurlvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/httpurlvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/httpurlvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,16 +1,15 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/regexprule.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/nonemptyrule.class.php" );
/**
+ * \ingroup Validator
+ *
* Checks whether the string is a valid http/https url
+ *
+ * @see NonEmptyRule
*/
class HttpUrlValidator extends Validator
{
Modified: plog/trunk/class/data/validator/integervalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/integervalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/integervalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,15 +1,14 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/uintrule.class.php" );
/**
+ * \ingroup Validator
+ *
* Checks that it is really an integer value.
+ *
+ * @see UIntRule
*/
class IntegerValidator extends Validator
{
Modified: plog/trunk/class/data/validator/ipmatchvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/ipmatchvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/ipmatchvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,28 +1,29 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
/**
+ * \ingroup Validator
+ *
* Matches ip address with masks. Returns true wether
* the given ip address matches with the given mask
*/
- class IpMatchValidator extends Validator {
+ class IpMatchValidator extends Validator
+ {
function IpValidator()
{
$this->Validator();
}
-
+
function validate( $ip, $mask )
{
return $this->checkip( $ip, $mask );
}
+ /**
+ * @private
+ */
function checkip($ip , $csiext)
{
$counter = 0;
Modified: plog/trunk/class/data/validator/passwordvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/passwordvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/passwordvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/nonemptyrule.class.php" );
@@ -16,7 +11,15 @@
define( "ERROR_PASSWORD_EMPTY", 2 );
/**
- * Checks passwords
+ * \ingroup Validator
+ *
+ * Validates passwords according to certain rules:
+ *
+ * - passwords should not be empty
+ * - password should have a length between minimun_password_length (if not available, defaults to '6') and a maximum length of 32
+ *
+ * @see NonEmptyRule
+ * @see RangeRule
*/
class PasswordValidator extends Validator
{
Modified: plog/trunk/class/data/validator/rules/arrayrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/arrayrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/arrayrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,11 +1,18 @@
<?php
include_once(PLOG_CLASS_PATH."class/data/validator/rules/rule.class.php");
-
+
+ /**
+ * \ingroup Validator_Rules
+ *
+ * Implements a rule that checks if the input is a valid php array (used
+ * in cases when we'd like to validate if something coming from $_GET or $_POST
+ * is an array)
+ */
class ArrayRule extends Rule
{
/**
- * The constructor does nothing.
+ * Initializes the rule
*/
function ArrayRule()
{
@@ -13,8 +20,9 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Validates the data.
+ *
+ * @param value The array that we'd like to validate
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/emaildnsrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/emaildnsrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/emaildnsrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -8,13 +8,16 @@
define( "ERROR_RULE_EMAIL_DNS_NOT_PERMITTED", "error_rule_email_dns_not_permitted");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * Given an email address it will connect to the MX server listed for the given domain
+ * and check whether the given user name has a valid mailbox in the server. This operation
+ * is a bit costly concerning time, since it takes a while to carry out these operations.
+ *
+ * This class will set one of these errors:
+ *
+ * - ERROR_RULE_EMAIL_DNS_NOT_PERMITTED
+ * - ERROR_RULE_EMAIL_DNS_SERVER_UNREACHABLE
*/
class EmailDnsRule extends Rule
{
@@ -27,8 +30,7 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Checks the given email address
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/emailformatrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/emailformatrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/emailformatrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,13 +6,10 @@
define( "ERROR_RULE_EMAIL_FORMAT_WRONG", "error_rule_email_format_wrong");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * Given an email address, returns true if it looks like a valid email address (if it has the
+ * valid format) If not, it will return ERROR_RULE_EMAIL_FORMAT_WRONG
*/
class EmailFormatRule extends RegExpRule
{
@@ -25,8 +22,7 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Validates the format of the given email address
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/equalrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/equalrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/equalrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,13 +6,11 @@
define( "ERROR_RULE_VALUES_NOT_EQUAL", "error_rule_values_not_equal");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * checks whether an item is equal to another via the binary operator '=='.
+ * Use the setEqualValue() method to set the first value and call the validate()
+ * method with the second value.
*/
class EqualRule extends Rule
{
@@ -28,7 +26,7 @@
}
/**
- * Add function info here
+ * @return returns the value we're comparing
*/
function getEqualValue()
{
@@ -36,7 +34,9 @@
}
/**
- * Add function info here
+ * Sets the value we're comparing to
+ *
+ * @param equalValue the valure we're comparing to
*/
function setEqualValue($equalValue)
{
@@ -44,8 +44,8 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Returns true if the two given values are equal. It will return ERROR_RULE_VALUES_NOT_EQUAL
+ * if they're not
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/intrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/intrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/intrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,15 @@
define( "ERROR_RULE_INT_FORMAT_WRONG", "error_rule_int_format_wrong");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * Checks if the given value is an integer, not only in type but also in format.
+ * It will return ERROR_RULE_INT_FORMAT_WRONG if the format is not correct
*/
class IntRule extends RegExpRule
{
/**
- * The constructor does nothing.
+ * Initialize the rule
*/
function IntRule()
{
@@ -25,8 +22,8 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Returns true if the given value is an integer, or false otherwise. In case of error
+ * it will also set the error code to ERROR_RULE_INT_FORMAT_WRONG
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/ipcidrformatrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/ipcidrformatrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/ipcidrformatrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,19 @@
define( "ERROR_RULE_IP_CIDR_FORMAT_WRONG", "error_rule_ip_cidr_format_wrong");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * Returns true if a given IP address is in valid CIDR format (Classless Inter-Domain Routing) These addresses
+ * should have the following format:
+ *
+ * <pre>xxx.yyy.zzz.www</pre>
+ *
+ * where each one of the elements is an integer between 0 and 255.
*/
class IpCidrFormatRule extends RegExpRule
{
/**
- * The constructor does nothing.
+ * Initializes the rule
*/
function IpCidrFormatRule()
{
@@ -25,8 +26,9 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Retursn true if the given IP address is in valid CIDR format
+ *
+ * @param value the IP address to validate
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/ipformatrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/ipformatrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/ipformatrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,19 @@
define( "ERROR_RULE_IP_FORMAT_WRONG", "error_rule_ip_format_wrong");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * Returns true if a given IP address is in valid CIDR format (Classless Inter-Domain Routing) These addresses
+ * should have the following format:
+ *
+ * <pre>xxx.yyy.zzz.www</pre>
+ *
+ * where each one of the elements is an integer between 0 and 255.
*/
class IpFormatRule extends RegExpRule
{
/**
- * The constructor does nothing.
+ * Initializes the rule
*/
function IpFormatRule()
{
@@ -25,8 +26,9 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Retursn true if the given IP address is in valid CIDR format
+ *
+ * @param value the IP address to validate
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/iprangerule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/iprangerule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/iprangerule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -5,20 +5,23 @@
define( "ERROR_RULE_IP_NOT_IN_RANGE", "error_rule_ip_not_in_range");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * This rule returns true if the given IP address is within a certain range. Use the constructor
+ * or the setRange() method for setting the right range. The range should be given in a submask format,
+ * so for example 1.2.3.4 would be within the range 1.2.3.255
+ *
+ * It will set the error flag ERROR_RULE_IP_NOT_IN_RANGE error if the address is not in the
+ * given range.
*/
class IpRangeRule extends Rule
{
var $_range;
/**
- * The constructor does nothing.
+ * Initializes the rule with the given range
+ *
+ * @param range The range.
*/
function IpRangeRule($range)
{
@@ -27,7 +30,9 @@
}
/**
- * Add function info here
+ * Sets a different range than the one given in the constructor
+ *
+ * @param range the new range
*/
function setRange($range)
{
@@ -35,7 +40,9 @@
}
/**
- * Add function info here
+ * Returns the current range being used for the calculations
+ *
+ * @return A string representing the range
*/
function getRange()
{
@@ -43,8 +50,11 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Returns true if the address is within the given range or false otherwise. It will
+ * also set the error ERROR_RULE_IP_NOT_IN_RANGE
+ *
+ * @param value The IP address to validate
+ * @return True if within range or false otherwise
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/nonemptyrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/nonemptyrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/nonemptyrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -5,12 +5,14 @@
define( "ERROR_RULE_VALUE_IS_EMPTY", "error_rule_value_is_empty");
/**
+ * \ingroup Validator_Rules
+ *
* Validates if a string is empty or not
*/
class NonEmptyRule extends Rule
{
/**
- * The constructor does nothing.
+ * Initializes the rule
*/
function NonEmptyRule()
{
@@ -18,8 +20,11 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Returns true if the value is not empty or false otherwise. If empty,
+ * the error ERROR_RULE_VALUE_IS_EMPTY will be set.
+ *
+ * @param value the string that we'd like to validate
+ * @return true if successful or false otherwise
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/numericrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/numericrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/numericrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,14 @@
define( "ERROR_RULE_NUMERIC_FORMAT_WRONG", "error_rule_numeric_format_wrong");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * Via a regular expression, validates whether the given string is a valid numeric value.
*/
class NumericRule extends RegExpRule
{
/**
- * The constructor does nothing.
+ * Initializes the rule
*/
function NumericRule()
{
@@ -25,8 +21,11 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Returns true if the rule is successful or false otherwise. It will set the error
+ * ERROR_RULE_NUMERIC_FORMAT_WRONG in case the validation is unsuccessful.
+ *
+ * @param value The value that should be checked
+ * @return true if successful or false otherwise.
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/rangerule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/rangerule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/rangerule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,13 +6,13 @@
define( "ERROR_RULE_TOO_LARGE", "error_rule_too_large");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * Given two values that will be used as lower and upper boundaries of the range,
+ * it will validate whether the given value falls within the range.
+ *
+ * It will set the errors ERROR_RULE_TOO_SMALL or ERROR_RULE_TOO_LARGE in case the
+ * validation is not successful.
*/
class RangeRule extends Rule
{
@@ -20,7 +20,10 @@
var $_maxValue;
/**
- * The constructor does nothing.
+ * Initializes the rule
+ *
+ * @param minValue the lower boundary of the range
+ * @param maxValue the upper boundary of the range
*/
function RangeRule($minValue, $maxValue)
{
@@ -31,7 +34,7 @@
}
/**
- * Add function info here
+ * @return the lower boundary of the range
*/
function getMinValue()
{
@@ -39,7 +42,9 @@
}
/**
- * Add function info here
+ * sets the lower boundary of the range
+ *
+ * @param minValue the minimum value
*/
function setMinValue($minValue)
{
@@ -47,7 +52,7 @@
}
/**
- * Add function info here
+ * @return the upper boundary of the range
*/
function getMaxValue()
{
@@ -55,7 +60,9 @@
}
/**
- * Add function info here
+ * sets the lower boundary of the range
+ *
+ * @param minValue the minimum value
*/
function setMaxValue($maxValue)
{
@@ -63,8 +70,10 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * validates that the given value is within the two boundaries previously specified
+ *
+ * @param value The value to validate
+ * @return True if successful or false otherwise
*/
function validate($value)
{
@@ -87,4 +96,4 @@
}
}
}
-?>
+?>
\ No newline at end of file
Modified: plog/trunk/class/data/validator/rules/rule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/rule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/rule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -3,14 +3,37 @@
include_once( PLOG_CLASS_PATH."class/data/validator/validation.class.php");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \defgroup Validator_Rules
+ *
+ * The main classes that implement the Strategy pattern as described here
+ * http://www.phppatterns.com/index.php/article/articleview/13/1/1/ are the classes
+ * that extend the Validator interface.
+ *
+ * But at a deeper level, a Validator class is nothing else than a collection of rules,
+ * or classes that extend the Rule interface. Implementing Validator classes as a collection
+ * of Rule classes allows for better code reusability, since sometimes most of the Validator
+ * classes check for similar things and therefore we can reuse most of the Rule classes.
+ *
+ * In order to implement your own rule, simply create your own class extending the Rule
+ * class and make sure to implement the Rule::Validate() method with your own validation logic. This
+ * method should return 'true' if the data complies with the logic of the rule or 'false' if it does
+ * not. Additionally, since Rule extends the Validation interface it is also possible to set
+ * certain error flags or messages via the private method Validation::_setError(). These error
+ * codes can be checked by Validator classes or by users of this class via the Validation::getError()
+ * method.
+ *
+ * See the documentation of the Validator base class on how to use Rule classes in your own validators.
+ * @see Validator
*/
+
+ /**
+ * \ingroup Validator_Rules
+ *
+ * This is the main base class that all custom Rule classes should extend. Please implement the
+ * Rule::validate() with your own logic and return 'true' if the validation was successful or
+ * 'false' otherwise. Please use Validation::_setError() to set additional error codes reporting
+ * more information.
+ */
class Rule extends Validation
{
/**
@@ -24,10 +47,13 @@
/**
* Validates the data. Does nothing here and it must be reimplemented by
* every child class.
+ *
+ * @param value The value that we're going to validate
+ * @return True if successful or false otheriwse
*/
function validate($value)
{
- throw(new Exception("qRule::validate: This method must be implemented by child classes."));
+ throw(new Exception("Rule::validate: This method must be implemented by child classes."));
die();
}
}
Modified: plog/trunk/class/data/validator/rules/uintrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/uintrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/uintrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -6,18 +6,15 @@
define( "ERROR_RULE_UINT_FORMAT_WRONG", "error_rule_uint_format_wrong");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator_Rules
+ *
+ * Validates that the given value is an unsigned integer or not. If unsuccessful, the error
+ * ERROR_RULE_UINT_FORMAT_WRONG will be set.
*/
class UIntRule extends RegExpRule
{
/**
- * The constructor does nothing.
+ * Initialize the rule
*/
function UIntRule()
{
@@ -25,8 +22,10 @@
}
/**
- * Validates the data. Does nothing here and it must be reimplemented by
- * every child class.
+ * Checks whether the given value is an unsigned integer
+ *
+ * @return True if successful or false otherwise. If unsuccessful, the error
+ * ERROR_RULE_UINT_FORMAT_WRONG will be set.
*/
function validate($value)
{
Modified: plog/trunk/class/data/validator/rules/urlformatrule.class.php
===================================================================
--- plog/trunk/class/data/validator/rules/urlformatrule.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/rules/urlformatrule.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,21 +1,21 @@
<?php
-/**
-* I'm leaving the copyright just to give some credit to the original author... Good work here,
-* I guess he deserves it :)
-*
-* @copyright 2004Esben Maaløe esm-at-baseclassmodulweb.dk
-* @authorEsben Maaløe esm-at-baseclassmodulweb.dk
-* @license You are free to copy/modify this function to your hearts content
-*However I ask that you return any improvements you make to me,
-*and that you credit me in your sourcecode if you use it
-* @version 0.21
-*/
-
include_once(PLOG_CLASS_PATH."class/data/validator/rules/rule.class.php");
include_once(PLOG_CLASS_PATH."class/net/dns.class.php");
include_once(PLOG_CLASS_PATH."class/net/httpvars.class.php");
+ /**
+ * \ingroup Validator_Rules
+ *
+ * Checks that a given URL is valid.
+ *
+ * @copyright 2004Esben Maaløe esm-at-baseclassmodulweb.dk
+ * @authorEsben Maaløe esm-at-baseclassmodulweb.dk
+ * @license You are free to copy/modify this function to your hearts content
+ * However I ask that you return any improvements you make to me,
+ * and that you credit me in your sourcecode if you use it
+ * @version 0.21
+ */
class UrlFormatRule extends Rule
{
Modified: plog/trunk/class/data/validator/stringvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/stringvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/stringvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,19 +1,14 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/nonemptyrule.class.php" );
/**
- * Checks that a string is not empty. That could be because it is
- * 'null', there is really nothing ('') or it is just a bunch of
- * blank spaces.
+ * \ingroup Validator
*
- * Classes can extend this one to provide a custom error message.
+ * Checks that a string is not empty.
+ *
+ * @see NonEmptyRule
*/
class StringValidator extends Validator
{
Modified: plog/trunk/class/data/validator/templatevalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/templatevalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/templatevalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH.'class/data/validator/validator.class.php' );
include_once( PLOG_CLASS_PATH.'class/file/file.class.php' );
@@ -12,11 +7,28 @@
define( 'ERROR_MISSING_BASE_FILES', -2 );
/**
- * Little class that will return true if a template set is valid
- * or not.
+ * 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:
*
- * Could have moved this as a static method in the TemplateService
- * class but didn't feel like making TemplateService too big after all...
+ * - main.template
+ * - postandcomments.template
+ * - commentarticle.template
+ * - posttrackbacks.template
+ * - error.template
+ * - album.template
+ * - albums.template
+ * - resource.template
+ *
+ * The template files should be inside a folder with the same name as template set.
+ *
+ * If the template set is not valid, this class will set one of the following errors:
+ *
+ * - ERROR_TEMPLATE_NOT_INSIDE_FOLDER
+ * - ERROR_MISSING_BASE_FILES
+ *
+ * This Validator class is also a good example of the more complex things that can be achieved
+ * with Validator classes, not just simple data validation.
*/
class TemplateValidator extends Validator
{
Modified: plog/trunk/class/data/validator/uploadvalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/uploadvalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/uploadvalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
include_once( PLOG_CLASS_PATH."class/misc/glob.class.php" );
@@ -15,13 +10,24 @@
define( "UPLOAD_VALIDATOR_ERROR_FORBIDDEN_EXTENSION", -2 );
/**
- * This class is designed for administrators who want to have some rules on what can
- * be uploaded. At the moment does nothing but accept that the file is valid, but many many
- * things can be done here...
+ * \ingroup Validator
+ *
+ * Given a FileUpload object, checks that it is not bigger than the maximum size allowed
+ * and that it does not have one of the forbidden extensions.
+ *
+ * The maximum size allowed is controlled via the 'maximum_file_upload_size' configuration setting
+ * and the list of forbidden extensions can be configured via the upload_forbidde_files configuration
+ * setting.
+ *
+ * If the validation is unsuccessful, the error codes UPLOAD_VALIDATOR_ERROR_UPLOAD_TOO_BIG or
+ * UPLOAD_VALIDATOR_ERROR_FORBIDDEN_EXTENSION will be set.
*/
class UploadValidator extends Validator
{
+ /**
+ * Constructor. Initializes the rule.
+ */
function UploadValidator()
{
$this->Validator();
Modified: plog/trunk/class/data/validator/usernamevalidator.class.php
===================================================================
--- plog/trunk/class/data/validator/usernamevalidator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/usernamevalidator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/data/validator/validator.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/nonemptyrule.class.php" );
include_once( PLOG_CLASS_PATH."class/data/validator/rules/regexprule.class.php" );
@@ -13,7 +8,18 @@
define( "ONLY_ALPHANUMERIC_REGEXP", "^([A-za-z0-9]*)$" );
/**
- * checks if a username is valid
+ * \ingroup Validator
+ *
+ * Checks if a username is valid. Usernames have to comply with the following rules:
+ *
+ * - They must not be empty
+ * - They must only be made of alphanumeric characters (a-z, A-Z and 0-9)
+ * - They must not be any of the forbidden usernames. Forbidden usernames can be configured
+ * via the 'forbidden_usernames' configuration parameter.
+ *
+ * @see NonEmptyRule
+ * @see RegExpRule
+ * @see FilteredWordsRule
*/
class UsernameValidator extends Validator
{
Modified: plog/trunk/class/data/validator/validation.class.php
===================================================================
--- plog/trunk/class/data/validator/validation.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/validation.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,27 +1,23 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator
+ *
+ * This is the base class that the Rule classes implement. Classes extending this one
+ * can use the private method _setError for raising custom error codes (in addition to
+ * returning 'false' from the validate() method)
+ *
+ * Client classes can use the public method getError() to retrieve this error codes
+ * and perhaps show a more meaningful message based on its value (if any)
*/
class Validation extends Object
{
var $_error;
/**
- * The constructor does nothing.
+ * Initialize the validation scheme
*/
function Validation()
{
@@ -30,27 +26,41 @@
}
/**
- * Add function info here
- **/
+ * Set a custom error code or message
+ *
+ * @param error The new error code
+ */
function _setError($error)
{
$this->_error = $error;
}
/**
- * Add function info here
- **/
+ * For client classes, use this method to retrieve the custom error code which was (if any)
+ * that was set in the validate() method.
+ *
+ * It is not guaranteed that an unsuccessful result of the validate() method will set a custom
+ * error message, as that is completely up to the Validator class. Also depending on the
+ * class we might get different return values from this method.
+ *
+ * @return An extended error message
+ */
function getError()
{
return $this->_error;
}
/**
- * Add function info here
- **/
+ * Implementation of the validation logic
+ *
+ * @param value The value that we're going to validate
+ * @return true if successful or false otherwise
+ * @see Rule::validate()
+ * @see Validator::validate()
+ */
function validate($value)
{
- throw(new Exception("qValidation::validate: This method must be implemented by child classes."));
+ throw(new Exception("Validation::validate: This method must be implemented by child classes."));
die();
}
}
Modified: plog/trunk/class/data/validator/validationlist.class.php
===================================================================
--- plog/trunk/class/data/validator/validationlist.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/validationlist.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,22 +1,11 @@
<?php
- /**
- * @package data
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php");
define(ERROR_RULE_IS_EMPTY, "error_rule_is_empty");
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * @private
*/
class ValidationList extends Object
{
Modified: plog/trunk/class/data/validator/validator.class.php
===================================================================
--- plog/trunk/class/data/validator/validator.class.php 2005-03-30 20:09:19 UTC (rev 1656)
+++ plog/trunk/class/data/validator/validator.class.php 2005-03-30 20:25:51 UTC (rev 1657)
@@ -1,20 +1,55 @@
<?php
/**
- * @package data
+ * \defgroup Validator
+ *
+ * Validator in pLog is an implementation of the 'Strategy' pattern as it can be seen
+ * http://www.phppatterns.com/index.php/article/articleview/13/1/1/.
+ *
+ * Validator classes allow to reuse validation logic wherever needed, and in a uniform
+ * way since class users can safely assume that all validators implement the
+ * Validator::validate() method.
+ *
+ * Validator classes in pLog can be built as a set of Rules, as a set of chained Validator
+ * classes or they can also bring their own non-reusable logic (non-reusable in the sense that
+ * validation logic does not necessarily need to be part of a Rule class)
+ *
+ * This the preferred way to validate data using a Validator class in pLog:
+ *
+ * <pre>
+ * $val = new UsernameValidator();
+ * if( !$val->validate( $newUsername ))
+ * print( "the username $newUsername is not correct!" );
+ * else
+ * print( "the username is correct" );
+ * </pre>
+ *
+ * It is also possible to implemlent our own custom validators by extending the Validator base class
+ * and adding a few rules. Keep in mind that if we overwrite the Validator::validate() method,
+ * we will lose some logic regarding rules. If our Validator class does not use rules, it is safe
+ * to overwrite such method and return 'true' if successful or false otherwise.
+ *
+ * In order to implement our own validator, the preferred way of doing it is by adding the necessary
+ * Validator and Rule objects in the constructor:
+ *
+ * <pre>
+ * class NewValidator extend Validator {
+ * function NewValidator()
+ * {
+ * $this->addRule( new NonEmptyRule());
+ * $this->addRule( new NumericRule());
+ * }
+ * }
+ * </pre>
*/
-
include_once( PLOG_CLASS_PATH."class/data/validator/validation.class.php" );
/**
- * This is an implementation of the 'Strategy' pattern as it can be seen
- * http://www.phppatterns.com/index.php/article/articleview/13/1/1/. Here we use
- * this pattern to validate data received from forms. Its is useful since for example
- * we check in many places if a 'postId' is valid or not. We can put the
- * checkings inside the class and simply reuse this class wherever we want. If we ever
- *`change the format of the postId parameter, we only have to change the code of the
- * class that validates it and it will be automatically used everywhere.
+ * \ingroup Validator
+ *
+ * Base class that all other validators extend. See the documentation of the Validator module for more
+ * information.
*/
class Validator extends Validation
{
@@ -22,7 +57,7 @@
var $_rules;
/**
- * The constructor does nothing.
+ * Initializes the constructor
*/
function Validator()
{
@@ -32,16 +67,21 @@
}
/**
- * Add function info here
- **/
+ * Adds a rule to the Validator
+ *
+ * @param rule A valid Rule object
+ */
function addRule(&$rule)
{
$this->_rules[] = &$rule;
}
/**
- * Add function info here
- **/
+ * Our validators can also be built based on other validators. It is also possible
+ * to use the ChainedValidator if we don't wish to create a completely new Validator
+ *
+ * @param validator A Validator object or a class extending from it
+ */
function addValidator(&$validator)
{
foreach ($validator->_rules as $rule)
@@ -51,8 +91,15 @@
}
/**
- * Add function info here
- **/
+ * This is the main method that takes care of processing all the rules. It is not necessary
+ * to reimplement this method in our custom Validator classes if we have already added some rules,
+ * as this method already provides some logic for going through the rules and setting some extended
+ * error codes if necessary.
+ *
+ * If your custom validator does not use rules, it is safe to reimplement this method.
+ *
+ * @param value The value that we're going to validate.
+ */
function validate($value)
{
foreach ($this->_rules as $rule)
More information about the pLog-svn
mailing list