From 065131205d975979abec4613caae416c02d76c2d Mon Sep 17 00:00:00 2001 From: pies Date: Thu, 2 Jun 2005 19:37:06 +0000 Subject: [PATCH] Merged in Olle's changes (comments). Olle, can you sync with the trunk? It's up to half an hour ago. git-svn-id: https://svn.cakephp.org/repo/trunk/cake@213 3807eeeb-6ff5-0310-8944-8be069107fe0 --- app/views/pages/home.thtml | 6 +-- config/paths.php | 26 +++++------ config/routes.php.default | 12 ++--- config/tags.php | 20 ++++----- libs/dbo_mysql.php | 5 ++- libs/dbo_postgres.php | 2 +- libs/dispatcher.php | 2 +- libs/error_messages.php | 34 +++++++------- libs/flay.php | 2 +- libs/folder.php | 2 +- libs/inflector.php | 6 ++- libs/log.php | 5 ++- libs/model.php | 61 +++++++++++++------------ libs/object.php | 10 ++--- libs/router.php | 24 +++++----- libs/template.php | 92 ++++++++++++++++++++------------------ libs/test.php | 29 ++++++------ libs/time.php | 34 +++++++------- libs/validators.php | 3 ++ 19 files changed, 198 insertions(+), 177 deletions(-) diff --git a/app/views/pages/home.thtml b/app/views/pages/home.thtml index 2bf22191a..0fc08c4bb 100644 --- a/app/views/pages/home.thtml +++ b/app/views/pages/home.thtml @@ -4,19 +4,19 @@

Introducing Cake

-

Cake is a structure of libraries, classes and run-time infrastructure for PHP programmers. It's also what I use at work. It's based on certain conventions, so you may find it rigid at first. The directory structure is already layed out, and it's different from what most people use. From what I've experienced, great many PHP programmers start as web- or graphic-designers, i.e. they are not university-educated programmers as many in the C++ and Java-land. They invent their own, peculiar ways of solving problems and stick to them. Perhaps that's why so few people use Pear and Pecl libraries – they don't usually re-use their code. And I was one of them. (linkOut('continued...','http://sputnik.pl/docs/intro')?>)

+

Cake is a structure of libraries, classes and run-time infrastructure for PHP programmers. It's also what I use at work. It's based on certain conventions, so you may find it rigid at first. The directory structure is already laid out, and it's different from what most people use. From what I've experienced, a great many PHP programmers start as web- or graphic-designers, i.e. they are not university-educated programmers as many in C++ and Java-land. They invent their own, peculiar ways of solving problems and stick to them. Perhaps that's why so few people use PEAR and PECL libraries – they don't usually re-use their code. And I was one of them. (linkOut('continued...','http://sputnik.pl/docs/intro')?>)

Features

-

Cake is in it's early infancy, but it works and I'm using it on a few projects. Currently the Dispatcher is working, the Model has CRUD functionality but with no joins between tables yet. The Controller is working and has the most basic functions (including render() for templating).

+

Cake is in its early infancy, but it works and I'm using it on a few projects. Currently the Dispatcher is working, the Model has CRUD functionality but with no joins between tables yet. The Controller is working and has most basic functions (including render() for templating).

Getting involved

diff --git a/config/paths.php b/config/paths.php index f78c95578..bb968a28b 100644 --- a/config/paths.php +++ b/config/paths.php @@ -30,49 +30,49 @@ */ /** - * If index.php file is used instead of an .htaccess file - * or if user can not set the web root to use the public - * directory we will define ROOT there otherwise we set it - * here + * If the index.php file is used instead of an .htaccess file + * or if the user can not set the web root to use the public + * directory we will define ROOT there, otherwise we set it + * here. */ if( !defined('ROOT') ){ define ('ROOT', '../'); } /** - * Path to the application directory. + * Path to the application's directory. */ define ('APP', ROOT.'app'.DS); /** - * Path to the application models directory. + * Path to the application's models directory. */ define ('MODELS', APP.'models'.DS); /** - * Path to the application controllers directory. + * Path to the application's controllers directory. */ define ('CONTROLLERS', APP.'controllers'.DS); /** - * Path to the application helpers directory. + * Path to the application's helpers directory. */ define ('HELPERS', APP.'helpers'.DS); /** - * Path to the application views directory. + * Path to the application's views directory. */ define ('VIEWS', APP.'views'.DS); /** - * Path to the application view layouts directory. + * Path to the application's view's layouts directory. */ define ('LAYOUTS', APP.'views'.DS.'layouts'.DS); /** - * Path to the application view elements directory. + * Path to the application's view's elements directory. * It's supposed to hold pieces of PHP/HTML that are used on multiple pages - * and are not linked to a particular layout (like polls, footers and so on) + * and are not linked to a particular layout (like polls, footers and so on). */ define ('ELEMENTS', APP.'views'.DS.'elements'.DS); @@ -122,7 +122,7 @@ define ('CONTROLLER_TESTS',TESTS.'app'.DS.'controllers'.DS); define ('HELPER_TESTS', TESTS.'app'.DS.'helpers'.DS); /** - * Path to the models test directory. + * Path to the models' test directory. */ define ('MODEL_TESTS', TESTS.'app'.DS.'models'.DS); diff --git a/config/routes.php.default b/config/routes.php.default index 3712d7621..9316e8c0e 100644 --- a/config/routes.php.default +++ b/config/routes.php.default @@ -33,20 +33,20 @@ */ /** - * Here, we are connecting '/' (base path) to controller called 'Pages', - * its action called 'display', and we pass a param to select the view file - * to use (in this case, /app/views/pages/home.thtml)... + * Here we are connecting '/' (base path) to a controller called 'Pages', + * and its action called 'display'. We pass a parameter to select the view file + * to use (in this case, /app/views/pages/home.thtml). */ $Route->connect ('/', array('controller'=>'Pages', 'action'=>'display', 'home')); /** - * ...and connect the rest of 'Pages' controller's urls. + * ...and connect the rest of 'Pages' controller's URLs. */ $Route->connect ('/pages/*', array('controller'=>'Pages', 'action'=>'display')); /** - * Then we connect url '/test' to our test controller. This is helpfull in - * developement. + * Then we connect url '/test' to our test controller. This is helpful in + * development. */ $Route->connect ('/test', array('controller'=>'Tests', 'action'=>'test_all')); diff --git a/config/tags.php b/config/tags.php index 88fc93dc8..610f7179d 100644 --- a/config/tags.php +++ b/config/tags.php @@ -36,17 +36,17 @@ define('TAG_LINK', '%s'); /** - * Tag template for openning form tag. + * Tag template for opening form tag. */ define('TAG_FORM', '
'); /** - * Tag template for an input tag. + * Tag template for an input type='text' tag. */ define('TAG_INPUT', ''); /** - * Tag template for a hidden tag. + * Tag template for an input type='hidden' tag. */ define('TAG_HIDDEN', ''); @@ -56,17 +56,17 @@ define('TAG_HIDDEN', ''); define('TAG_AREA', ''); /** - * Tag template for a checkbox input tag. + * Tag template for a input type='checkbox ' tag. */ define('TAG_CHECKBOX', ''); /** - * Tag template for a radio input tag. + * Tag template for a input type='radio' tag. */ define('TAG_RADIOS', ''); /** - * Tag template for a select openning tag. + * Tag template for a select opening tag. */ define('TAG_SELECT_START', ''); define('TAG_FILE', ''); /** - * Tag template for a submit tag. + * Tag template for a submit button tag. */ define('TAG_SUBMIT', ''); @@ -126,7 +126,7 @@ define('TAG_TABLE_CELL', '%s'); define('TAG_TABLE_ROW', '%s'); /** - * Tag template for a CSS meta-tag. + * Tag template for a CSS link tag. */ define('TAG_CSS', ''); @@ -136,12 +136,12 @@ define('TAG_CSS', ''); define('TAG_CHARSET', ''); /** - * Tag template for inline JavaScript + * Tag template for inline JavaScript. */ define('TAG_JAVASCRIPT', ''); /** - * Tag template for included JavaScript + * Tag template for included JavaScript. */ define('TAG_JAVASCRIPT_INCLUDE', ''); diff --git a/libs/dbo_mysql.php b/libs/dbo_mysql.php index d945983c2..5d6115fd1 100644 --- a/libs/dbo_mysql.php +++ b/libs/dbo_mysql.php @@ -43,7 +43,7 @@ uses('dbo'); /** - * Enter description here... + * MySQL layer for DBO. * * * @package cake @@ -167,7 +167,8 @@ class DBO_MySQL extends DBO { } /** - * Returns number of rows in previous resultset. If no previous resultset exists, this returns false. + * Returns number of rows in previous resultset. If no previous resultset exists, + * this returns false. * * @return int Number of rows */ diff --git a/libs/dbo_postgres.php b/libs/dbo_postgres.php index dadc5ac20..6e8c187bd 100644 --- a/libs/dbo_postgres.php +++ b/libs/dbo_postgres.php @@ -36,7 +36,7 @@ uses('object', 'dbo'); /** - * Enter description here... + * PostgreSQL layer for DBO. * * @package cake * @subpackage cake.libs diff --git a/libs/dispatcher.php b/libs/dispatcher.php index 28bb8b5d3..644d52c37 100644 --- a/libs/dispatcher.php +++ b/libs/dispatcher.php @@ -38,7 +38,7 @@ uses('error_messages', 'object', 'router', 'controller'); /** - * Enter description here... + * Dispatches the request, creating appropriate models and controllers. * * * @package cake diff --git a/libs/error_messages.php b/libs/error_messages.php index 8f2b48894..4d67482ce 100644 --- a/libs/error_messages.php +++ b/libs/error_messages.php @@ -30,97 +30,97 @@ */ /** - * Enter description here... + * Error string for when the specified database driver can not be found. * */ define ('ERROR_UNKNOWN_DATABASE_DRIVER', '[DbFactory] Specified database driver (%s) not found'); /** - * Enter description here... + * Error string for when the dispatcher can not find a default controller. * */ define ('ERROR_NO_CONTROLLER_SET', '[Dispatcher] No default controller, can\'t continue, check routes config'); /** - * Enter description here... + * Error string for when the dispatcher can not find a default action. * */ define ('ERROR_NO_ACTION_SET', '[Dispatcher] No default action, can\'t continue, check routes config'); /** - * Enter description here... + * Error string for when the dispatcher can not find given controller. * */ define ('ERROR_UNKNOWN_CONTROLLER', '[Dispatcher] Specified controller "%s" doesn\'t exist, create it first'); /** - * Enter description here... + * Error string for when the dispatcher can not find expected action in controller. * */ define ('ERROR_NO_ACTION', '[Dispatcher] Action "%s" is not defined in the "%s" controller, create it first'); /** - * Enter description here... + * Error string for errors in view. * */ define ('ERROR_IN_VIEW', '[Controller] Error in view "%s", got:
%s
'); /** - * Enter description here... + * Error string for when the controller can not find expected view. * */ define ('ERROR_NO_VIEW', '[Controller] No template file for view "%s" (expected "%s"), create it first'); /** - * Enter description here... + * Error string for errors in layout. * */ define ('ERROR_IN_LAYOUT', '[Controller] Error in layout "%s", got:
"%s"
'); /** - * Enter description here... + * Error string for when the controller can not find expected layout. * */ define ('ERROR_NO_LAYOUT', '[Controller] Couln\'t find layout "%s" (expected "%s"), create it first'); /** - * Enter description here... + * Error string for database not being able to access the table list. * */ define ('ERROR_NO_TABLE_LIST', '[Database] Couldn\'t get table list, check database config'); /** - * Enter description here... + * Error string for No corresponding database table found for model. * */ define ('ERROR_NO_MODEL_TABLE', '[Model] No DB table for model "%s" (expected "%s"), create it first'); /** - * Enter description here... + * Error string for Field not present in table. * */ define ('ERROR_NO_FIELD_IN_MODEL_DB', '[Model::set()] Field "%s" is not present in table "%s", check database schema'); /** - * Enter description here... + * Error string short short error message. * */ define ('SHORT_ERROR_MESSAGE', '
%s
'); /** - * Enter description here... + * Error string for when original image can not be loaded. * */ -define ('ERROR_CANT_GET_ORIGINAL_IMAGE', '[Image] Couln\'t load original image %s (tried from "%s")'); +define ('ERROR_CANT_GET_ORIGINAL_IMAGE', '[Image] Couldn\'t load original image %s (tried from "%s")'); /** - * Enter description here... + * Error string for error 404. * */ define ('ERROR_404', "The requested address /%s was not found on this server."); // second %s contains short error message /** - * Enter description here... + * Error string for error 500. * */ define ('ERROR_500', "Application error, sorry."); diff --git a/libs/flay.php b/libs/flay.php index c1097f774..902556fb9 100644 --- a/libs/flay.php +++ b/libs/flay.php @@ -39,7 +39,7 @@ uses('object'); /** - * Enter description here... + * Text-to-html parser, similar to Textile or RedCloth, only with a little different syntax. * * * @package cake diff --git a/libs/folder.php b/libs/folder.php index abb51d1a3..15778464f 100644 --- a/libs/folder.php +++ b/libs/folder.php @@ -37,7 +37,7 @@ uses('object'); /** - * Enter description here... + * Folder structure browser, lists folders and files. * * * @package cake diff --git a/libs/inflector.php b/libs/inflector.php index 2bad838ea..9133fc282 100644 --- a/libs/inflector.php +++ b/libs/inflector.php @@ -16,7 +16,7 @@ /** * Purpose: Inflector * I'm trying to port RoR Inflector class here. - * Inflector pluralizes and singularizes english nouns. + * Inflector pluralizes and singularizes English nouns. * Test with $i = new Inflector(); $i->test(); * * @filesource @@ -38,7 +38,9 @@ uses('object'); /** - * Enter description here... + * This is a port of Ruby on Rails' Inflector class. + * Inflector pluralizes and singularizes English nouns. + * Test with $i = new Inflector(); $i->test(); * * @package cake * @subpackage cake.libs diff --git a/libs/log.php b/libs/log.php index 166912e16..40c0f5433 100644 --- a/libs/log.php +++ b/libs/log.php @@ -38,7 +38,10 @@ class Log { return $log = fopen($fn, 'a+') && fwrite($log, $out) && fclose($log); } } - +/** + * Error constant. Used for differentiating error logging and debugging. + * + */ define ('LOG_ERROR', 2); ?> \ No newline at end of file diff --git a/libs/model.php b/libs/model.php index 9a7010265..9d2f62527 100644 --- a/libs/model.php +++ b/libs/model.php @@ -44,7 +44,11 @@ uses('object', 'validators', 'inflector'); /** - * Enter description here... + * DBO-backed object data model, loosely based on RoR (www.rubyonrails.com). + * Automatically selects a database table name based on a pluralized lowercase object class name + * (i.e. class 'User' => table 'users'; class 'Man' => table 'men') + * The table is required to have at least 'id auto_increment', 'created datetime', + * and 'modified datetime' fields. * * * @package cake @@ -79,7 +83,7 @@ class Model extends Object { var $id = false; /** - * Enter description here... + * Container for the data that this model gets from persistent storage (the database). * * @var array * @access public @@ -89,7 +93,7 @@ class Model extends Object { /** * Table name for this Model. * - * @var unknown_type + * @var string * @access public */ var $table = false; @@ -103,7 +107,7 @@ class Model extends Object { var $_table_info = null; /** - * Enter description here... + * Array of other Models this Model references in a one-to-many relationship. * * @var array * @access private @@ -111,7 +115,7 @@ class Model extends Object { var $_oneToMany = array(); /** - * Enter description here... + * Array of other Models this Model references in a one-to-one relationship. * * @var array * @access private @@ -119,7 +123,7 @@ class Model extends Object { var $_oneToOne = array(); /** - * Array of other Models this Model references in a hasMany relationship. + * Array of other Models this Model references in a has-many relationship. * * @var array * @access private @@ -131,29 +135,27 @@ class Model extends Object { * * append entries for validation as ('field_name' => '/^perl_compat_regexp$/') that has to match with preg_match() * validate with Model::validate() - * @var unknown_type + * @var array */ var $validate = array(); /** * Append entries for validation as ('field_name' => '/^perl_compat_regexp$/') that has to match with preg_match() * validate with Model::validate() - * @var unknown_type + * @var array */ var $validationErrors = null; /** - * Constructor binds the Model's database table + * Constructor. Binds the Model's database table to the object. * * @param unknown_type $id + * @param unknown_type $db Database connection object. */ function __construct ($id=false, $db=null) { global $DB; - if ($db) - $this->db = $db; - else - $this->db = &$DB; + $this->db = $db? $db: &$DB; if ($id) $this->id = $id; @@ -165,7 +167,9 @@ class Model extends Object { } /** - * Enter description here... + * Creates has-many relationships, and then call relink. + * + * @see relink() * */ function createLinks () { @@ -182,7 +186,7 @@ class Model extends Object { } /** - * Updates the many-to-one links, by emptying the links list, and linkManyToOne again. + * Updates this model's many-to-one links, by emptying the links list, and then linkManyToOne again. * * @see linkManyToOne() * @@ -218,9 +222,9 @@ class Model extends Object { } /** - * Enter description here... + * Sets a custom table for your controller class. Used by your controller to select a database table. * - * @param unknown_type $table_name + * @param string $table_name Name of the custom table */ function useTable ($table_name) { if (!in_array($table_name, $this->db->tables())) { @@ -242,8 +246,8 @@ class Model extends Object { * (Alternative indata: two strings, which are mangled to * a one-item, two-dimensional array using $one for a key and $two as its value.) * - * @param mixed $one Array or string. - * @param string $two Optional string + * @param mixed $one Array or string of data + * @param string $two Value string for the alternative indata method * @return unknown */ function set ($one, $two=null) { @@ -265,7 +269,7 @@ class Model extends Object { } /** - * Sets current id to given $id. + * Sets current Model id to given $id. * * @param int $id Id */ @@ -277,7 +281,7 @@ class Model extends Object { /** * Returns an array of table metadata (column names and types) from the database. * - * @return array + * @return array Array of table metadata */ function loadInfo () { if (empty($this->_table_info)) @@ -287,10 +291,10 @@ class Model extends Object { /** * Returns true if given field name exists in this Model's database table. - * Starts by pre-caching the metadata into the private property table_info if that is not already set. + * Starts by loading the metadata into the private property table_info if that is not already set. * * @param string $name Name of table to look in - * @return unknown + * @return boolean */ function hasField ($name) { if (empty($this->_table_info)) $this->loadInfo(); @@ -300,9 +304,8 @@ class Model extends Object { /** * Returns a list of fields from the database * - * @param string $fields - * @param array $fields - * @return array of values + * @param mixed $fields String of single fieldname, or an array of fieldnames. + * @return array Array of database fields */ function read ($fields=null) { $this->validationErrors = null; @@ -338,7 +341,7 @@ class Model extends Object { * * @param string $name Name of the table field * @param mixed $value Value of the field - * @return success + * @return boolean True on success save */ function saveField($name, $value) { return $this->save(array($name=>$value), false); @@ -347,9 +350,9 @@ class Model extends Object { /** * Saves model data to the database. * - * @param array $data + * @param array $data Data to save. * @param boolean $validate - * @return success + * @return boolean success */ function save ($data=null, $validate=true) { if ($data) $this->set($data); diff --git a/libs/object.php b/libs/object.php index e821b67d6..bef0931a7 100644 --- a/libs/object.php +++ b/libs/object.php @@ -46,7 +46,7 @@ class Object { /** * A hack to support __construct() on PHP 4 * Hint: descendant classes have no PHP4 class_name() constructors, - * so this one gets called first and calls the top-layer __construct() + * so this constructor gets called first and calls the top-layer __construct() * which (if present) should call parent::__construct() * * @return Object @@ -58,13 +58,13 @@ class Object { } /** - * Class constructor, overriden in descendant classes. + * Class constructor, overridden in descendant classes. */ function __construct() { } /** - * Class destructor, overriden in descendant classes. + * Class destructor, overridden in descendant classes. */ function __destruct() { } @@ -73,7 +73,7 @@ class Object { * Object-to-string conversion. * Each class can override it as necessary. * - * @return string this class' name + * @return string This name of this class */ function toString () { return get_class($this); @@ -83,7 +83,7 @@ class Object { * API for logging events. * * @param string $msg Log message - * @param string $type + * @param int $type Error type constant. Defined in /libs/log.php. */ function log ($msg, $type=LOG_ERROR) { if (!$this->_log) diff --git a/libs/router.php b/libs/router.php index fe720f764..b1dfa2de9 100644 --- a/libs/router.php +++ b/libs/router.php @@ -15,7 +15,7 @@ /** * Purpose: Router - * Parses the request URL into controller, action, and params + * Parses the request URL into controller, action, and parameters. * * @filesource * @author Cake Authors/Developers @@ -37,7 +37,7 @@ uses('object'); /** - * Enter description here... + * Parses the request URL into controller, action, and parameters. * * * @package cake @@ -48,14 +48,14 @@ uses('object'); class Router extends Object { /** - * Enter description here... + * Array of routes * - * @var unknown_type + * @var array */ var $routes = array(); /** - * Enter description here... + * Constructor. * */ function __construct () { @@ -63,10 +63,12 @@ class Router extends Object { } /** - * Enter description here... + * TODO: Better description. Returns this object's routes array. Returns false if there are no routes available. * - * @param unknown_type $route - * @param unknown_type $default + * @param string $route An empty string, or a route string "/" + * @param array $default NULL or an array describing the default route + * @see routes + * @return array Array of routes */ function connect ($route, $default=null) { $parsed = $names = array (); @@ -104,10 +106,10 @@ class Router extends Object { } /** - * Enter description here... + * TODO: Better description. Returns an array of routes. * - * @param unknown_type $url - * @return unknown + * @param string $url URL to be parsed + * @return array */ function parse ($url) { $out = array(); diff --git a/libs/template.php b/libs/template.php index 75b728b31..3653a951a 100644 --- a/libs/template.php +++ b/libs/template.php @@ -37,7 +37,8 @@ uses('object'); /** - * Enter description here... + * Templating for Controller class. Takes care of rendering views. + * * * * @package cake @@ -58,7 +59,7 @@ class Template extends Object { /** * Enter description here... * - * @var unknown_type + * @var string * @access public */ var $layout = 'default'; @@ -66,7 +67,7 @@ class Template extends Object { /** * Enter description here... * - * @var unknown_type + * @var boolean * @access public */ var $autoRender = true; @@ -74,15 +75,15 @@ class Template extends Object { /** * Enter description here... * - * @var unknown_type + * @var boolean * @access public */ var $autoLayout = true; /** - * Enter description here... + * Variables for the view * - * @var unknown_type + * @var array * @access private */ var $_view_vars = array(); @@ -90,13 +91,13 @@ class Template extends Object { /** * Enter description here... * - * @var unknown_type + * @var boolean * @access private */ var $_page_title = false; /** - * Enter description here... + * Constructor. * */ function __construct () { @@ -115,8 +116,8 @@ class Template extends Object { /** * Enter description here... * - * @param unknown_type $one - * @param unknown_type $two + * @param mixed $one An array of POST data. (Or: a string of a single POST datum.) + * @param string $two Value in case $one is a string (which then works as the key). * @return unknown */ function set($one, $two=null) { @@ -124,18 +125,18 @@ class Template extends Object { } /** - * Enter description here... + * Set the title element of the page. * - * @param unknown_type $value + * @param string $pageTitle Text for the title */ - function setTitle ($value) { - $this->_page_title = $value; + function setTitle ($pageTitle) { + $this->_page_title = $pageTitle; } /** - * Enter description here... + * Sets data for this view. Will set title is the key "title" is in given $data array. * - * @param unknown_type $data + * @param array $data Array of */ function _setArray($data) { foreach ($data as $name => $value) { @@ -147,11 +148,11 @@ class Template extends Object { } /** - * Enter description here... + * Displays a flash message. A flash message is feedback to the user that displays after editing actions, among other things. * - * @param unknown_type $message - * @param unknown_type $url - * @param unknown_type $time + * @param string $message Text to display to the user + * @param string $url URL fragment + * @param int $time Display time, in seconds */ function flash ($message, $url, $time=1) { $this->autoRender = false; @@ -165,11 +166,12 @@ class Template extends Object { } /** - * Enter description here... + * Render view for given action and layout. If $file is given, that is used + * for a view filename (e.g. customFunkyView.thtml). * - * @param unknown_type $action - * @param unknown_type $layout - * @param unknown_type $file + * @param string $action Name of action to render for + * @param string $layout + * @param string $file Custom filename for view */ function render ($action=null, $layout=null, $file=null) { $this->autoRender = false; @@ -199,10 +201,10 @@ class Template extends Object { } /** - * Enter description here... + * Enter description here... Renders a layout. Returns output from _render(). Returns false on error. * - * @param unknown_type $content_for_layout - * @return unknown + * @param string $content_for_layout Content to render in a view + * @return string Rendered output */ function renderLayout ($content_for_layout) { $layout_fn = $this->_getLayoutFn(); @@ -230,10 +232,11 @@ class Template extends Object { } /** - * Renders a piece of PHP with provided params and returns HTML, XML, or any other string. + * Renders a piece of PHP with provided parameters and returns HTML, XML, or any other string. * - * @param unknown_type $content_for_layout - * @return unknown + * @param string $name Name of template file + * @param array $params Array of data for rendered view + * @return string Rendered output */ function renderElement ($name, $params=array()) { $fn = ELEMENTS.$name.'.thtml'; @@ -245,31 +248,32 @@ class Template extends Object { } /** - * Enter description here... + * Returns layout filename for this template as a string. * - * @return unknown + * @return string Filename for layout file (.thtml). */ function _getLayoutFn() { return VIEWS."layouts".DS."{$this->layout}.thtml"; } /** - * Enter description here... + * Returns filename of given action's template file (.thtml) as a string. * - * @param unknown_type $action - * @return unknown + * @param string $action Controller action to find template filename for + * @return string Template filename */ function _getViewFn($action) { return VIEWS.$this->viewpath.DS."{$action}.thtml"; } /** - * Enter description here... + * Renders and returns output for given view filename with its + * array of data. * - * @param unknown_type $___view_fn - * @param unknown_type $___data_for_view - * @param unknown_type $___play_safe - * @return unknown + * @param string $___view_fn Filename of the view + * @param array $___data_for_view Data to include in rendered view + * @param boolean $___play_safe If set to false, the include() of the $__view_fn is done without suppressing output of errors + * @return string Rendered output */ function _render($___view_fn, $___data_for_view, $___play_safe = true) { extract($___data_for_view, EXTR_SKIP); # load all view variables @@ -288,11 +292,11 @@ class Template extends Object { } /** - * trims a string to a specified length adding elipsis '..' if necessary + * Returns given string trimmed to given length, adding an elipsis '..' if necessary. * - * @param unknown_type $string - * @param unknown_type $length - * @return unknown + * @param string $string String to trim + * @param int $length Length of returned string, excluding ellipsis + * @return string Trimmed string */ function trimTo ($string, $length) { return substr($string, 0, $length).(strlen($string)>$length? '..': null); diff --git a/libs/test.php b/libs/test.php index a16ef4c3b..fcb3e7276 100644 --- a/libs/test.php +++ b/libs/test.php @@ -74,7 +74,7 @@ if (phpversion() >= '4') { } } /** - * Enter description here... + * Exception class for testing * * * @package cake @@ -126,7 +126,7 @@ class TestException { } /** - * Enter description here... + * Asserts for Unit Testing * * * @package cake @@ -587,7 +587,7 @@ class TestCase extends Assert /* implements Test */ { /** - * Enter description here... + * Test Suite for Unit Testing. * * * @package cake @@ -722,7 +722,7 @@ class TestSuite /* implements Test */ { /** - * Enter description here... + * Test Failure for Unit Testing * * * @package cake @@ -788,7 +788,7 @@ class TestFailure { /** - * Enter description here... + * Test Result for Unit Testing * * * @package cake @@ -959,7 +959,7 @@ class TestResult { } /** - * Enter description here... + * Mines data from test results. Used for Unit Testing. * * * @package cake @@ -975,15 +975,15 @@ class ResultDataMiner extends TestResult { */ var $tests = null; /** - * Enter description here... + * Total number of tests * - * @var unknown_type + * @var int */ var $total_tests = 0; /** - * Enter description here... + * Total number of errors * - * @var unknown_type + * @var int */ var $total_errors = 0; @@ -1025,9 +1025,9 @@ class ResultDataMiner extends TestResult { } /** - * Enter description here... + * Returns an array with total number of performed tests, total number of errors, and details of the tests. * - * @return unknown + * @return array Array with information on how the tests went. */ function report () { return array('tests'=>$this->total_tests, 'errors'=>$this->total_errors, 'details'=>$this->tests); @@ -1036,7 +1036,7 @@ class ResultDataMiner extends TestResult { } /** - * Enter description here... + * Test Runner for Unit Testing. * * * @package cake @@ -1045,9 +1045,8 @@ class ResultDataMiner extends TestResult { * */ class TestRunner { - /* Run a suite of tests and report results. */ /** - * Enter description here... + * Run a suite of tests and report results. * * @param unknown_type $suite * @return unknown diff --git a/libs/time.php b/libs/time.php index 5fb3d8ed1..43030c997 100644 --- a/libs/time.php +++ b/libs/time.php @@ -37,7 +37,7 @@ uses ('object'); /** - * Enter description here... + * Time related functions, formatting for dates etc. * * * @package cake @@ -48,10 +48,10 @@ uses ('object'); class Time extends Object { /** - * Enter description here... + * Returns a formatted date string for given Datetime string. * - * @param unknown_type $date_string - * @return unknown + * @param string $date_string Datetime string + * @return string Formatted date string */ function nice ($date_string=null) { $date = $date_string? strtotime($date_string): time(); @@ -59,10 +59,14 @@ class Time extends Object { } /** - * Enter description here... + * Returns a formatted descriptive date string for given datetime string. + * If the given date is today, the returned string could be "Today, 16:54". + * If the given date was yesterday, the returned string could be "Yesterday, 16:54". + * If $date_string's year is the current year, the returned string does not + * include mention of the year. * * @param string $date_string Datetime string - * @return unknown + * @return string Described, relative date string */ function niceShort ($date_string=null) { $date = $date_string? Time::fromString($date_string): time(); @@ -108,7 +112,7 @@ class Time extends Object { } /** - * Returns a Unix timestamp from a textual datetime description. Wrapper for PHP function strtotime(). + * Returns a Unix timestamp for a datetime string. Wrapper for PHP function strtotime(). * * @param string $date_string Datetime string to be represented as a Unix timestamp * @return int Unix timestamp @@ -118,19 +122,19 @@ class Time extends Object { } /** - * Formats date for Atom RSS feeds + * Returns a date formatted for Atom RSS feeds. * - * @param datetime $date - * @return string + * @param string $date Datetime string + * @return string Formatted date string */ function toRss ($date) { return date('Y-m-d', $date).'T'.date('H:i:s', $date).'Z'; } /** - * This function returns either a relative date or a formatted date depending - * on the difference between the current datetime and the datetime passed. - * $datetime should be in a strtotime parsable format like MySQL datetime. + * Returns either a relative date or a formatted date depending + * on the difference between the current time and given datetime. + * $datetime should be in a strtotime-parsable format like MySQL datetime. * * Relative dates look something like this: * 3 weeks, 4 days ago @@ -138,10 +142,10 @@ class Time extends Object { * Formatted dates look like this: * on 02/18/2004 * - * The function includes 'ago' or 'on' and assumes you'll properly add a word + * The returned string includes 'ago' or 'on' and assumes you'll properly add a word * like 'Posted ' before the function output. * - * @param $datetime Time in strtotime parsable format + * @param $datetime Time in strtotime-parsable format * @return string Relative time string. */ diff --git a/libs/validators.php b/libs/validators.php index e17918f26..8b3a9cf91 100644 --- a/libs/validators.php +++ b/libs/validators.php @@ -32,16 +32,19 @@ /** * Not empty. + * */ define('VALID_NOT_EMPTY', '/.+/'); /** * Numbers [0-9] only. + * */ define('VALID_NUMBER', '/^[0-9]+$/'); /** * A valid email address. + * */ define('VALID_EMAIL', '/^([a-z0-9][a-z0-9_\-\.\+]*)@([a-z0-9][a-z0-9\.\-]{0,63}\.[a-z]{2,3})$/i');