Improved documentation for php expressions

Fixes issue #1921

framework/base/CComponent.php

@@ -596,6 +596,9 @@ public function raiseEvent($name,$event)
 	 * that can be directly accessed in the expression. See {@link http://us.php.net/manual/en/function.extract.php PHP extract}
 	 * for more details. In the expression, the component object can be accessed using $this.
 	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
+	 *
 	 * @param mixed $_expression_ a PHP expression or PHP callback to be evaluated.
 	 * @param array $_data_ additional parameters to be passed to the above expression/callback.
 	 * @return mixed the expression result

framework/caching/dependencies/CExpressionDependency.php

@@ -25,7 +25,12 @@ class CExpressionDependency extends CCacheDependency
 	/**
 	 * @var string the PHP expression whose result is used to determine the dependency.
 	 * The expression can also be a valid serializable PHP callback.
-	 * The callback will be passed with a parameter which is the dependency object itself.
+	 * It will be passed with a parameter which is the dependency object itself.
+	 *
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $expression;
 

framework/i18n/CChoiceFormat.php

@@ -29,6 +29,8 @@
  * In case the given number doesn't select any message, the last candidate message
  * will be returned.
  *
+ * The PHP expressions will be evaluated using {@link evaluate}.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @package system.i18n
  */

framework/web/auth/CAccessControlFilter.php

@@ -50,6 +50,9 @@
  *   'verbs'=>array('GET', 'POST'),
  * 
  *   // optional, a PHP expression whose value indicates whether this rule applies
+ *   // The PHP expression will be evaluated using {@link evaluateExpression}.
+ *   // A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+ *   // please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
  *   'expression'=>'!$user->isGuest && $user->level==2',
  * 
  *   // optional, the customized error message to be displayed
@@ -235,6 +238,11 @@ class CAccessRule extends CComponent
 	 * function foo($user, $rule) { ... }
 	 * </pre>
 	 * where $user is the current application user object and $rule is this access rule.
+	 *
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $expression;
 	/**

framework/web/filters/CHttpCacheFilter.php

@@ -25,8 +25,13 @@ class CHttpCacheFilter extends CFilter
 	 */
 	public $lastModified;
 	/**
-	 * Expression for the last modification date. If set, this takes precedence over {@link lastModified}.
-	 * @var string|callback
+	 * @var string|callback PHP Expression for the last modification date.
+	 * If set, this takes precedence over {@link lastModified}.
+	 *
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $lastModifiedExpression;
 	/**
@@ -35,8 +40,13 @@ class CHttpCacheFilter extends CFilter
 	 */
 	public $etagSeed;
 	/**
-	 * Expression for the ETag seed. If set, this takes precedence over {@link etagSeed}.
-	 * @var string|callback
+	 * @var string|callback Expression for the ETag seed.
+	 * If set, this takes precedence over {@link etagSeed}.
+	 *
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $etagSeedExpression;
 	/**

framework/web/widgets/COutputCache.php

@@ -109,6 +109,11 @@ class COutputCache extends CFilterWidget
 	 * function foo($cache) { ... }
 	 * </pre>
 	 * where $cache refers to the output cache component.
+	 *
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $varyByExpression;
 	/**

framework/zii/behaviors/CTimestampBehavior.php

@@ -64,7 +64,10 @@ class CTimestampBehavior extends CActiveRecordBehavior {
 	 * or a {@link CDbExpression} object representing a DB expression (e.g. new CDbExpression('NOW()')).
 	 * Defaults to null, meaning that we will attempt to figure out the appropriate timestamp
 	 * automatically. If we fail at finding the appropriate timestamp, then it will
-	 * fall back to using the current UNIX timestamp
+	 * fall back to using the current UNIX timestamp.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $timestampExpression;
 

framework/zii/widgets/grid/CButtonColumn.php

@@ -56,9 +56,16 @@ class CButtonColumn extends CGridColumn
 	public $viewButtonImageUrl;
 	/**
 	 * @var string a PHP expression that is evaluated for every view button and whose result is used
-	 * as the URL for the view button. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object.
+	 * as the URL for the view button. In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based)</li>
+	 *   <li><code>$data</code> the data model for the row</li>
+	 *   <li><code>$this</code> the column object</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $viewButtonUrl='Yii::app()->controller->createUrl("view",array("id"=>$data->primaryKey))';
 	/**
@@ -78,9 +85,16 @@ class CButtonColumn extends CGridColumn
 	public $updateButtonImageUrl;
 	/**
 	 * @var string a PHP expression that is evaluated for every update button and whose result is used
-	 * as the URL for the update button. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object.
+	 * as the URL for the update button. In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based)</li>
+	 *   <li><code>$data</code> the data model for the row</li>
+	 *   <li><code>$this</code> the column object</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $updateButtonUrl='Yii::app()->controller->createUrl("update",array("id"=>$data->primaryKey))';
 	/**
@@ -100,9 +114,16 @@ class CButtonColumn extends CGridColumn
 	public $deleteButtonImageUrl;
 	/**
 	 * @var string a PHP expression that is evaluated for every delete button and whose result is used
-	 * as the URL for the delete button. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object.
+	 * as the URL for the delete button. In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based)</li>
+	 *   <li><code>$data</code> the data model for the row</li>
+	 *   <li><code>$this</code> the column object</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $deleteButtonUrl='Yii::app()->controller->createUrl("delete",array("id"=>$data->primaryKey))';
 	/**
@@ -153,6 +174,9 @@ class CButtonColumn extends CGridColumn
 	 * In the PHP expression for the 'url' option and/or 'visible' option, the variable <code>$row</code>
 	 * refers to the current row number (zero-based), and <code>$data</code> refers to the data model for
 	 * the row.
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 *
 	 * If the 'buttonID' is 'view', 'update' or 'delete' the options will be applied to the default buttons.
 	 *

framework/zii/widgets/grid/CCheckBoxColumn.php

@@ -39,25 +39,47 @@ class CCheckBoxColumn extends CGridColumn
 	public $name;
 	/**
 	 * @var string a PHP expression that will be evaluated for every data cell and whose result will be rendered
-	 * in each data cell as the checkbox value. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object.
+	 * in each data cell as the checkbox value. In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based)</li>
+	 *   <li><code>$data</code> the data model for the row</li>
+	 *   <li><code>$this</code> the column object</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $value;
 	/**
 	 * @var string a PHP expression that will be evaluated for every data cell and whose result will
-	 * determine if checkbox for each data cell is checked. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object.
+	 * determine if checkbox for each data cell is checked. In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based)</li>
+	 *   <li><code>$data</code> the data model for the row</li>
+	 *   <li><code>$this</code> the column object</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 * @since 1.1.4
 	 */
 	public $checked;
 	/**
 	 * @var string a PHP expression that will be evaluated for every data cell and whose result will
-	 * determine if checkbox for each data cell is disabled. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object. Note that expression result will
-	 * overwrite value set with <code>checkBoxHtmlOptions['disabled']</code>.
+	 * determine if checkbox for each data cell is disabled. In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based)</li>
+	 *   <li><code>$data</code> the data model for the row</li>
+	 *   <li><code>$this</code> the column object</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
+	 *
+	 * Note that expression result will overwrite value set with <code>checkBoxHtmlOptions['disabled']</code>.
 	 * @since 1.1.13
 	 */
 	public $disabled;

framework/zii/widgets/grid/CDataColumn.php

@@ -11,7 +11,7 @@
 Yii::import('zii.widgets.grid.CGridColumn');
 
 /**
- * CDataColumn represents a grid view column that is associated with a data attribute or expression.
+ * CDataColumn represents a grid view column that is associated with a data attribute or PHP expression.
  *
  * Either {@link name} or {@link value} should be specified. The former specifies
  * a data attribute name, while the latter a PHP expression whose value should be rendered instead.
@@ -34,10 +34,16 @@ class CDataColumn extends CGridColumn
 	 */
 	public $name;
 	/**
-	 * @var string a PHP expression that will be evaluated for every data cell and whose result will be rendered
-	 * as the content of the data cells. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object.
+	 * @var string a PHP expression that will be evaluated for every data cell using {@link evaluateExpression} and whose result will be rendered
+	 * as the content of the data cell.
+	 * In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based).</li>
+	 *   <li><code>$data</code> the data model for the row.</li>
+	 * 	 <li><code>$this</code> the column object.</li>
+	 * </ul>
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $value;
 	/**

framework/zii/widgets/grid/CGridColumn.php

@@ -50,9 +50,16 @@ abstract class CGridColumn extends CComponent
 	public $visible=true;
 	/**
 	 * @var string a PHP expression that is evaluated for every data cell and whose result
-	 * is used as the CSS class name for the data cell. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object.
+	 * is used as the CSS class name for the data cell. In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based)</li>
+	 *   <li><code>$data</code> the data model for the row</li>
+	 *   <li><code>$this</code> the column object</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $cssClassExpression;
 	/**

framework/zii/widgets/grid/CGridView.php

@@ -111,18 +111,34 @@ class CGridView extends CBaseListView
 	public $rowCssClass=array('odd','even');
 	/**
 	 * @var string a PHP expression that is evaluated for every table body row and whose result
-	 * is used as the CSS class name for the row. In this expression, the variable <code>$row</code>
-	 * stands for the row number (zero-based), <code>$data</code> is the data model associated with
-	 * the row, and <code>$this</code> is the grid object.
+	 * is used as the CSS class name for the row. In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based)</li>
+	 *   <li><code>$data</code> the data model for the row</li>
+	 *   <li><code>$this</code> the grid view object</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 * @see rowCssClass
-	 * @deprecated in 1.1.13
+	 * @deprecated in 1.1.13 in favor of {@link rowHtmlOptionsExpression}
 	 */
 	public $rowCssClassExpression;
 	/**
 	 * @var string a PHP expression that is evaluated for every table body row and whose result
-	 * is used as additional HTML attributes for the row. In this expression, the variable <code>$row</code>
-	 * stands for the row number (zero-based), <code>$data</code> is the data model associated with
-	 * the row, and <code>$this</code> is the grid object.
+	 * is used as additional HTML attributes for the row. The expression should return an
+	 * array whose key value pairs correspond to html attribute and value.
+	 * In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based)</li>
+	 *   <li><code>$data</code> the data model for the row</li>
+	 *   <li><code>$this</code> the grid view object</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 * @since 1.1.13
 	 */
 	public $rowHtmlOptionsExpression;
@@ -312,6 +328,8 @@ class CGridView extends CBaseListView
 	 * @since 1.1.11
 	 */
 	public $enableHistory=false;
+
+
 	/**
 	 * Initializes the grid view.
 	 * This method will initialize required property values and instantiate {@link columns} objects.

framework/zii/widgets/grid/CLinkColumn.php

@@ -31,9 +31,17 @@ class CLinkColumn extends CGridColumn
 	public $label='Link';
 	/**
 	 * @var string a PHP expression that will be evaluated for every data cell and whose result will be rendered
-	 * as the label of the hyperlink of the data cells. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object.
+	 * as the label of the hyperlink of the data cell.
+	 * In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based).</li>
+	 *   <li><code>$data</code> the data model for the row.</li>
+	 * 	 <li><code>$this</code> the column object.</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $labelExpression;
 	/**
@@ -48,9 +56,17 @@ class CLinkColumn extends CGridColumn
 	public $url='javascript:void(0)';
 	/**
 	 * @var string a PHP expression that will be evaluated for every data cell and whose result will be rendered
-	 * as the URL of the hyperlink of the data cells. In this expression, the variable
-	 * <code>$row</code> the row number (zero-based); <code>$data</code> the data model for the row;
-	 * and <code>$this</code> the column object.
+	 * as the URL of the hyperlink of the data cells.
+	 * In this expression, you can use the following variables:
+	 * <ul>
+	 *   <li><code>$row</code> the row number (zero-based).</li>
+	 *   <li><code>$data</code> the data model for the row.</li>
+	 * 	 <li><code>$this</code> the column object.</li>
+	 * </ul>
+	 * The PHP expression will be evaluated using {@link evaluateExpression}.
+	 *
+	 * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
+	 * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
 	 */
 	public $urlExpression;
 	/**