Trabajar con URLs

Las clases Url, UrlImmutable y UrlScript facilitan generar, analizar y manipular URL.

→ Instalación y requisitos

Url

La clase Nette\Http\Url permite manipular con facilidad las URL y sus distintos componentes, tal y como se ve en este diagrama:

scheme  user  password  host   port    path        query  fragment
  |      |      |        |      |       |            |       |
/--\   /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer
\______\__________________________/
    |               |
 hostUrl        authority

Generar URL es intuitivo:

use Nette\Http\Url;

$url = new Url;
$url->setScheme('https')
	->setHost('localhost')
	->setPath('/edit')
	->setQueryParameter('foo', 'bar');

echo $url; // 'https://localhost/edit?foo=bar'

También puede analizar una URL y manipularla después:

$url = new Url(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

La clase Url implementa la interfaz JsonSerializable y tiene el método __toString(), así que el objeto se puede imprimir o usar en los datos que se pasan a json_encode().

echo $url;
echo json_encode([$url]);

Componentes de la URL

Para obtener o modificar los distintos componentes de la URL están disponibles los siguientes métodos:

Los métodos getUser(), getPassword(), setUser() y setPassword() están obsoletos, porque no se recomienda incrustar las credenciales directamente en la URL.

Atención: al trabajar con una URL obtenida de una petición HTTP, tenga presente que no contendrá el fragmento, porque el navegador no lo envía al servidor.

También podemos trabajar con los distintos parámetros de consulta mediante:

getDomain (int $level = 2): string

Devuelve la parte derecha o izquierda del host. Así funciona si el host es www.nette.org:

isEqual (string|Url $url): bool

Comprueba si dos URL son idénticas.

$url->isEqual('https://nette.org');

canonicalize()

Convierte la URL a su forma canónica. Convierte el nombre de host a minúsculas y normaliza la ruta (codificación por porcentaje y eliminación de caracteres redundantes). La cadena de consulta se deja sin cambios.

Url::isAbsolute (string $url): bool

Comprueba si una URL es absoluta. Una URL se considera absoluta si empieza por un esquema (p. ej. http, https, ftp) seguido de dos puntos.

Url::isAbsolute('https://nette.org');    // true
Url::isAbsolute('//nette.org');          // false

Url::removeDotSegments (string $path): string

Normaliza la ruta de una URL eliminando los segmentos especiales . y ... Este método elimina los elementos redundantes de la ruta igual que hacen los navegadores web.

Url::removeDotSegments('/path/../subtree/./file.txt');  // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar');                // '/foo/bar'
Url::removeDotSegments('./today/../file.txt');          // 'file.txt'

UrlImmutable

La clase Nette\Http\UrlImmutable es la alternativa inmutable a la clase Url (de forma parecida a como DateTimeImmutable es la alternativa inmutable a DateTime en PHP). En lugar de setters tiene “withers”, que no cambian el objeto sino que devuelven nuevas instancias con el valor modificado:

use Nette\Http\UrlImmutable;

$url = new UrlImmutable(
	'https://nette.org:8080/en/download?name=param#footer',
);

$newUrl = $url
	->withHost('example.com')
	->withPath('/en/')
	->withQueryParameter('name', 'value');

echo $newUrl; // 'https://example.com:8080/en/?name=value#footer'

La clase UrlImmutable implementa la interfaz JsonSerializable y tiene el método __toString(), así que el objeto se puede imprimir o usar en los datos que se pasan a json_encode().

echo $url;
echo json_encode([$url]);

Componentes de la URL

Para obtener o cambiar los distintos componentes de la URL están disponibles los siguientes métodos:

Los métodos getUser(), getPassword(), withUser(), withPassword() y withoutUserInfo() están obsoletos, porque no se recomienda incrustar las credenciales directamente en la URL.

También podemos trabajar con los distintos parámetros de consulta mediante:

getDomain (int $level = 2): string

Devuelve la parte derecha o izquierda del host. Así funciona si el host es www.nette.org:

resolve (string $reference): UrlImmutable

Resuelve una URL absoluta igual que un navegador procesa los enlaces de una página HTML:

• si el enlace es una URL absoluta (contiene un esquema), se usa sin cambios
• si el enlace empieza por //, se adopta solo el esquema de la URL actual
• si el enlace empieza por /, se crea una ruta absoluta desde la raíz del dominio
• en los demás casos, la URL se construye relativa a la ruta actual

$url = new UrlImmutable('https://example.com/path/page');
echo $url->resolve('../foo');           // 'https://example.com/foo'
echo $url->resolve('/bar');             // 'https://example.com/bar'
echo $url->resolve('sub/page.html');    // 'https://example.com/path/sub/page.html'

isEqual (string|Url $url): bool

Comprueba si dos URL son idénticas.

$url->isEqual('https://nette.org');

UrlScript

La clase Nette\Http\UrlScript es descendiente de UrlImmutable y la amplía con componentes virtuales adicionales de la URL, como el directorio raíz del proyecto, etc. Igual que su clase padre, es un objeto inmutable.

El siguiente diagrama muestra los componentes que reconoce UrlScript:

     baseUrl    basePath  relativePath  relativeUrl
        |          |        |               |
/---------------/-----\/--------\---------------------------\
http://nette.org/admin/script.php/pathinfo/?name=param#footer
                \_______________/\________/
                       |              |
                  scriptPath       pathInfo

• baseUrl es la URL base de la aplicación, incluidos el dominio y la parte de la ruta hasta el directorio raíz de la aplicación
• basePath es la parte de la ruta hasta el directorio raíz de la aplicación
• scriptPath es la ruta al script actual
• relativePath es el nombre del script (y, eventualmente, más segmentos de la ruta) relativo a basePath
• relativeUrl es toda la parte de la URL posterior a baseUrl, incluidas la cadena de consulta y el fragmento
• pathInfo es una parte de la URL, hoy poco usada, posterior al nombre del script

Para obtener estas partes de la URL están disponibles los siguientes métodos:

Normalmente no creamos los objetos UrlScript directamente; en su lugar, el método Nette\Http\Request::getUrl() lo devuelve con los componentes ya correctamente establecidos para la petición HTTP actual.