Added guide on Url helper

docs/guide/README.md

@@ -194,6 +194,6 @@ Helpers
 * [Overview](helper-overview.md)
 * [ArrayHelper](helper-array.md)
 * **TBD** [Html](helper-html.md)
-* **TBD** [Url](helper-url.md)
+* [Url](helper-url.md)
 * **TBD** [Security](helper-security.md)
 

docs/guide/helper-url.md

+Url Helper
+==========
+
+Url helper provides a set of static methods for managing URLs.
+
+
+Getting common URLs
+-------------------
+
+There are two methods you can use to get common URLs: home URL and base URL of the current request. In order to get
+home URL use the follwing:
+
+```php
+$relativeHomeUrl = Url::home();
+$absoluteHomeUrl = Url::home(true);
+$httpsAbsoluteHomeUrl = Url::home('https');
+```
+
+If no parameter is passed, URL generated is relative. You can either pass `true` to get absolute URL for the current
+schema or specify schema explicitly (`https`, `http`).
+
+To get base URL of the current request use the following:
+ 
+```php
+$relativeBaseUrl = Url::base();
+$absoluteBaseUrl = Url::base(true);
+$httpsAbsoluteBaseUrl = Url::base('https');
+```
+
+The only parameter of the method works exactly the same as for `Url::home()`.
+
+Creating URLs
+-------------
+
+In order to create URL to a given route use `Url::toRoute()` method. The method uses [[\yii\web\UrlManager]] to create
+a URL:
+
+```php
+$url = Url::toRoute(['product/view', 'id' => 42]);
+```
+ 
+You may specify the route as a string, e.g., `site/index`. You may also use an array if you want to specify additional
+query parameters for the URL being created. The array format must be:
+
+```php
+// generates: /index.php?r=site/index&param1=value1&param2=value2
+['site/index', 'param1' => 'value1', 'param2' => 'value2']
+```
+
+If you want to create a URL with an anchor, you can use the array format with a `#` parameter. For example,
+
+```php
+// generates: /index.php?r=site/index&param1=value1#name
+['site/index', 'param1' => 'value1', '#' => 'name']
+```
+
+A route may be either absolute or relative. An absolute route has a leading slash (e.g. `/site/index`), while a relative
+route has none (e.g. `site/index` or `index`). A relative route will be converted into an absolute one by the following rules:
+
+- If the route is an empty string, the current [[\yii\web\Controller::route|route]] will be used;
+- If the route contains no slashes at all (e.g. `index`), it is considered to be an action ID of the current controller
+  and will be prepended with [[\yii\web\Controller::uniqueId]];
+- If the route has no leading slash (e.g. `site/index`), it is considered to be a route relative to the current module
+  and will be prepended with the module's [[\yii\base\Module::uniqueId|uniqueId]].
+
+Below are some examples of using this method:
+
+```php
+// /index?r=site/index
+echo Url::toRoute('site/index');
+
+// /index?r=site/index&src=ref1#name
+echo Url::toRoute(['site/index', 'src' => 'ref1', '#' => 'name']);
+
+// http://www.example.com/index.php?r=site/index
+echo Url::toRoute('site/index', true);
+
+// https://www.example.com/index.php?r=site/index
+echo Url::toRoute('site/index', 'https');
+```
+
+There's another method `Url::to()` that is very similar to [[toRoute()]]. The only difference is that this method
+requires a route to be specified as an array only. If a string is given, it will be treated as a URL.
+
+The first argument could be:
+         
+- an array: [[toRoute()]] will be called to generate the URL. For example:
+  `['site/index']`, `['post/index', 'page' => 2]`. Please refer to [[toRoute()]] for more details
+  on how to specify a route.
+- a string with a leading `@`: it is treated as an alias, and the corresponding aliased string
+  will be returned.
+- an empty string: the currently requested URL will be returned;
+- a normal string: it will be returned as is.
+
+When `$scheme` is specified (either a string or true), an absolute URL with host info (obtained from
+[[\yii\web\UrlManager::hostInfo]]) will be returned. If `$url` is already an absolute URL, its scheme
+will be replaced with the specified one.
+
+Below are some usage examples:
+
+```php
+// /index?r=site/index
+echo Url::to(['site/index']);
+
+// /index?r=site/index&src=ref1#name
+echo Url::to(['site/index', 'src' => 'ref1', '#' => 'name']);
+
+// the currently requested URL
+echo Url::to();
+
+// /images/logo.gif
+echo Url::to('@web/images/logo.gif');
+
+// images/logo.gif
+echo Url::to('images/logo.gif');
+
+// http://www.example.com/images/logo.gif
+echo Url::to('@web/images/logo.gif', true);
+
+// https://www.example.com/images/logo.gif
+echo Url::to('@web/images/logo.gif', 'https');
+```
+
+Remember URL for future use
+---------------------------
+
+There are cases when you need to remember URL and afterwards use it during processing of the one of sequential requests.
+It can be achieved in the following way:
+ 
+```php
+// Remember current URL 
+Url::remember();
+
+// Remember URL specified. See Url::to() for argument format.
+Url::remember(['product/view', 'id' => 42]);
+
+// Remember URL specified with a name given
+Url::remember(['product/view', 'id' => 42], 'product');
+```
+
+In the next request we can get URL remembered in the following way:
+
+```php
+$url = Url::previous();
+$productUrl = Url::previous('product');
+```
+                        
+Finding out if URL is relative
+------------------------------
+
+To find out if URL is relative i.e. it doesn't have host info part, you can use the following code:
+                             
+```php
+$isRelative = Url::isRelative('test/it');
+```