From 6ab10bcda7f2392f3eb312218c0b032de528d8a2 Mon Sep 17 00:00:00 2001
From: Carsten Brandt <mail@cebe.cc>
Date: Sat, 18 Oct 2014 18:39:42 +0200
Subject: [PATCH] updated guide about helpers

make sure to not confuse extending of helper classes with extensions.
Use "customizing" in this case and added note about when this should be done.
---
 docs/guide/helper-overview.md | 31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/docs/guide/helper-overview.md b/docs/guide/helper-overview.md
index e47a9fc..3764a15 100644
--- a/docs/guide/helper-overview.md
+++ b/docs/guide/helper-overview.md
@@ -15,12 +15,13 @@ use yii\helpers\Html;
 echo Html::encode('Test > test');
 ```
 
-> Note: To support [extending helper classes](#extending-helper-classes), Yii breaks each core helper class
+> Note: To support [customizing helper classes](#customizing-helper-classes), Yii breaks each core helper class
   into two classes: a base class (e.g. `BaseArrayHelper`) and a concrete class (e.g. `ArrayHelper`).
   When you use a helper, you should only use the concrete version and never use the base class.
 
 
-## Core Helper Classes
+Core Helper Classes
+-------------------
 
 The following core helper classes are provided in the Yii releases:
 
@@ -39,19 +40,21 @@ The following core helper classes are provided in the Yii releases:
 - VarDumper
 
 
-## Extending Helper Classes
+Customizing Helper Classes <a name="customizing-helper-classes"></a>
+--------------------------
 
-To custom a core helper class (e.g. `yii\helpers\ArrayHelper`), you should extend from its corresponding base class
-(e.g. `yii\helpers\BaseArrayHelper`) and name your class the same as the corresponding concrete class
-(e.g. `yii\helpers\ArrayHelper`), including its namespace.
+To customize a core helper class (e.g. [[yii\helpers\ArrayHelper]]), you should create a new class extending
+from the helpers corresponding base class (e.g. [[yii\helpers\BaseArrayHelper]]) and name your class the same
+as the corresponding concrete class (e.g. [[yii\helpers\ArrayHelper]]), including its namespace. This class
+will then be set up to replace the original implementation of the framework.
 
 The following example shows how to customize the [[yii\helpers\ArrayHelper::merge()|merge()]] method of the
 [[yii\helpers\ArrayHelper]] class:
 
 ```php
-namespace yii\helpers;
+<?php
 
-use yii\helpers\BaseArrayHelper;
+namespace yii\helpers;
 
 class ArrayHelper extends BaseArrayHelper
 {
@@ -62,14 +65,16 @@ class ArrayHelper extends BaseArrayHelper
 }
 ```
 
-Save your class in a file named `ArrayHelper.php`. The file can be in any directory, such as `@app/components`.
+Save your class in a file named `ArrayHelper.php`. The file can be in any directory, for example `@app/components`.
 
 Next, in your application's [entry script](structure-entry-scripts.md), add the following line of code
-after including the `yii.php` file:
+after including the `yii.php` file to tell the [Yii class autoloader](concept-autoloading.md) to load your custom
+class instead of the original helper class from the framework:
 
 ```php
-Yii::$classMap['yii\helpers\ArrayHelper'] = 'path/to/ArrayHelper.php';
+Yii::$classMap['yii\helpers\ArrayHelper'] = '@app/components/ArrayHelper.php';
 ```
 
-The above line instructs the [Yii class autoloader](concept-autoloading.md) to load your version of the helper
-class, instead of the one included in the Yii releases.
+Note that customizing of helper classes is only useful if you want to change the behavior of an existing function
+of the helpers. If you want to add additional functions to use in your application you may better create a separate
+helper for that.
--
libgit2 0.27.1