helper-url.md 5.35 KB
Newer Older
larnu committed
1 2 3 4 5 6 7 8
Clase Auxiliar URL (URL Helper)
===============================

La clase auxiliar URL proporciona un conjunto de métodos estáticos para gestionar URLs.

Obtener URLs Comunes
--------------------

9
Se pueden usar dos métodos para obtener URLs comunes: URL de inicio (home URL) y URL base (base URL) de la petición
larnu committed
10 11 12 13 14 15 16 17
(request) actual. Para obtener la URL de inicio se puede usar el siguiente código:

```php
$relativeHomeUrl = Url::home();
$absoluteHomeUrl = Url::home(true);
$httpsAbsoluteHomeUrl = Url::home('https');
```

18
Si no se pasan parámetros, las URLs generadas son relativas. Se puede pasar `true`para obtener la URL absoluta del
larnu committed
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
esquema actual o especificar el esquema explícitamente (`https`, `http`).

Para obtener la URL base de la petición actual, se puede usar el siguiente código:

```php
$relativeBaseUrl = Url::base();
$absoluteBaseUrl = Url::base(true);
$httpsAbsoluteBaseUrl = Url::base('https');
```

El único parámetro del método funciona exactamente igual que para `Url::home()`.

Creación de URLs
----------------

34
Para crear una URL para una ruta determinada se puede usar `Url::toRoute()`. El metodo utiliza [[\yii\web\UrlManager]]
larnu committed
35 36 37 38 39 40
para crear una URL:

```php
$url = Url::toRoute(['product/view', 'id' => 42]);
```

41
Se puede especificar la ruta como una cadena de texto, ej. `site/index`. También se puede usar un array si se
larnu committed
42 43 44 45 46 47 48 49 50 51 52 53 54 55
quieren especificar parámetros para la URL que se esta generando. El formato del array debe ser:

```php
// genera: /index.php?r=site/index&param1=value1&param2=value2
['site/index', 'param1' => 'value1', 'param2' => 'value2']
```

Si se quiere crear una URL con un enlace, se puede usar el formato de array con el parámetro `#`. Por ejemplo,

```php
// genera: /index.php?r=site/index&param1=value1#name
['site/index', 'param1' => 'value1', '#' => 'name']
```

56 57
Una ruta puede ser absoluta o relativa. Una ruta absoluta tiene una barra al principio (ej. `/site/index`),
mientras que una ruta relativa no la tiene (ej. `site/index` o `index`). Una ruta relativa se convertirá en una
larnu committed
58 59 60
ruta absoluta siguiendo las siguientes normas:

- Si la ruta es una cadena vacía, se usará la [[\yii\web\Controller::route|route]] actual;
61
- Si la ruta no contiene barras (ej. `index`), se considerará que es el ID de una acción del controlador actual y
larnu committed
62
  se antepondrá con [[\yii\web\Controller::uniqueId]];
63
- Si la ruta no tiene barra inicial (ej. `site/index`), se considerará que es una ruta relativa del modulo actual y
larnu committed
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
  se le antepondrá el [[\yii\base\Module::uniqueId|uniqueId]] del modulo.

A continuación se muestran varios ejemplos del uso de este método:

```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');
```

82
El otro método `Url::to()` es muy similar a [[toRoute()]]. La única diferencia es que este método requiere que la ruta
larnu committed
83 84 85 86
especificada sea un array. Si se pasa una cadena de texto, se tratara como una URL.

El primer argumento puede ser:

87 88
- un array: se llamará a [[toRoute()]] para generar la URL. Por ejemplo: `['site/index']`,
  `['post/index', 'page' => 2]`. Se puede revisar [[toRoute()]] para obtener más detalles acerca de como especificar
larnu committed
89
  una ruta.
90
- una cadena que empiece por `@`: se tratará como un alias, y se devolverá la cadena correspondiente asociada a este
larnu committed
91 92 93 94
  alias.
- una cadena vacía: se devolverá la URL de la petición actual;
- una cadena de texto: se devolverá sin alteraciones.

95 96
Cuando se especifique `$schema` (tanto una cadena de text como `true`), se devolverá una URL con información del host
(obtenida mediante [[\yii\web\UrlManager::hostInfo]]). Si `$url` ya es una URL absoluta, su esquema se reemplazará con
larnu committed
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
el especificado.

A continuación se muestran algunos ejemplos de uso:

```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']);

// la URL solicitada actualmente
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');
```

Recordar la URL para utilizarla más adelante
--------------------------------------------

127
Hay casos en que se necesita recordar la URL y después usarla durante el procesamiento de una de las peticiones
larnu committed
128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
secuenciales. Se puede logar de la siguiente manera:

```php
// Recuerda la URL actual
Url::remember();

// Recuerda la URL especificada. Revisar Url::to() para ver formatos de argumentos.
Url::remember(['product/view', 'id' => 42]);

// Recuerda la URL especificada con un nombre asignado
Url::remember(['product/view', 'id' => 42], 'product');
```

En la siguiente petición se puede obtener la URL memorizada de la siguiente manera:

```php
$url = Url::previous();
$productUrl = Url::previous('product');
```

Reconocer la relatividad de URLs
--------------------------------

151
Para descubrir si una URL es relativa, es decir, que no contenga información del host, se puede utilizar el siguiente
larnu committed
152 153 154 155 156
código:

```php
$isRelative = Url::isRelative('test/it');
```