no message
This commit is contained in:
BarboraFleg
Vendored
+222
@@ -0,0 +1,222 @@
|
||||
Nette HTTP Component
|
||||
====================
|
||||
|
||||
[](https://packagist.org/packages/nette/http)
|
||||
[](https://travis-ci.org/nette/http)
|
||||
[](https://ci.appveyor.com/project/dg/http/branch/master)
|
||||
[](https://coveralls.io/github/nette/http?branch=master)
|
||||
[](https://github.com/nette/http/releases)
|
||||
[](https://github.com/nette/http/blob/master/license.md)
|
||||
|
||||
HTTP request and response are encapsulated in `Nette\Http\Request` and `Nette\Http\Response` objects which offer comfortable API and also act as
|
||||
sanitization filter.
|
||||
|
||||
|
||||
HTTP Request
|
||||
-------------
|
||||
|
||||
Nette cleans out data sent by user from control and invalid characters.
|
||||
|
||||
The URL of the request is available as [api:Nette\Http\UrlScript] instance:
|
||||
|
||||
```php
|
||||
$url = $httpRequest->getUrl();
|
||||
echo $url; // e.g. https://nette.org/en/documentation?action=edit
|
||||
echo $url->host; // nette.org
|
||||
```
|
||||
|
||||
Determine current HTTP method:
|
||||
|
||||
```php
|
||||
echo $httpRequest->getMethod(); // GET, POST, HEAD, PUT
|
||||
|
||||
if ($httpRequest->isMethod('GET')) ...
|
||||
```
|
||||
|
||||
Is the connection encrypted (HTTPS)?
|
||||
|
||||
```php
|
||||
echo $httpRequest->isSecured() ? 'yes' : 'no';
|
||||
```
|
||||
|
||||
Is this an AJAX request?
|
||||
|
||||
```php
|
||||
echo $httpRequest->isAjax() ? 'yes' : 'no';
|
||||
```
|
||||
|
||||
What is the user's IP address?
|
||||
|
||||
```php
|
||||
echo $httpRequest->getRemoteAddress(); // user's IP address
|
||||
echo $httpRequest->getRemoteHost(); // and its DNS translation
|
||||
```
|
||||
|
||||
What URL the user came from? Returned as [Nette\Http\Url |urls] object.
|
||||
|
||||
```php
|
||||
echo $httpRequest->getReferer()->host;
|
||||
```
|
||||
|
||||
Request parameters:
|
||||
|
||||
```php
|
||||
$get = $httpRequest->getQuery(); // array of all URL parameters
|
||||
$id = $httpRequest->getQuery('id'); // returns GET parameter 'id' (or null)
|
||||
|
||||
$post = $httpRequest->getPost(); // array of all POST parameters
|
||||
$id = $httpRequest->getPost('id'); // returns POST parameter 'id' (or null)
|
||||
|
||||
$cookies = $httpRequest->getCookies(); // array of all cookies
|
||||
$sessId = $httpRequest->getCookie('sess_id'); // returns the cookie (or null)
|
||||
```
|
||||
|
||||
Uploaded files are encapsulated into [api:Nette\Http\FileUpload] objects:
|
||||
|
||||
```php
|
||||
$files = $httpRequest->getFiles(); // array of all uploaded files
|
||||
|
||||
$file = $httpRequest->getFile('avatar'); // returns one file
|
||||
echo $file->getName(); // name of the file sent by user
|
||||
echo $file->getSanitizedName(); // the name without dangerous characters
|
||||
```
|
||||
|
||||
HTTP headers are also accessible:
|
||||
|
||||
```php
|
||||
// returns associative array of HTTP headers
|
||||
$headers = $httpRequest->getHeaders();
|
||||
|
||||
// returns concrete header (case-insensitive)
|
||||
$userAgent = $httpRequest->getHeader('User-Agent');
|
||||
```
|
||||
|
||||
A useful method is `detectLanguage()`. You can pass it an array with languages supported by application and it returns the one preferred by browser.
|
||||
It is not magic, the method just uses the `Accept-Language` header.
|
||||
|
||||
```php
|
||||
// Header sent by browser: Accept-Language: cs,en-us;q=0.8,en;q=0.5,sl;q=0.3
|
||||
|
||||
$langs = array('hu', 'pl', 'en'); // languages supported in application
|
||||
|
||||
echo $httpRequest->detectLanguage($langs); // en
|
||||
```
|
||||
|
||||
|
||||
RequestFactory and URL filtering
|
||||
------------------
|
||||
|
||||
Object holding current HTTP request is created by [api:Nette\Http\RequestFactory]. Its behavior can be modified.
|
||||
It's possible to clean up URLs from characters that can get into them because of poorly implemented comment systems on various other websites by using filters:
|
||||
|
||||
```php
|
||||
$requestFactory = new Nette\Http\RequestFactory;
|
||||
|
||||
// remove spaces from path
|
||||
$requestFactory->addUrlFilter('%20', '', PHP_URL_PATH);
|
||||
|
||||
// remove dot, comma or right parenthesis form the end of the URL
|
||||
$requestFactory->addUrlFilter('[.,)]$');
|
||||
|
||||
// clean the path from duplicated slashes (default filter)
|
||||
$requestFactory->addUrlFilter('/{2,}', '/', PHP_URL_PATH);
|
||||
```
|
||||
|
||||
And then we let the factory generate a new `httpRequest` and we store it in a system container:
|
||||
|
||||
```php
|
||||
// $container is a system container
|
||||
$container->addService('httpRequest', $requestFactory->createHttpRequest());
|
||||
```
|
||||
|
||||
|
||||
HTTP response
|
||||
--------------
|
||||
|
||||
Whether it is still possible to send headers or change the status code tells the `isSent()` method. If it returns true,
|
||||
it won't be possible to send another header or change the status code.
|
||||
|
||||
In that case, any attempt to send header or change code invokes `Nette\InvalidStateException`. .[caution]
|
||||
|
||||
[Response status code | http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10] can be sent and retrieved this way:
|
||||
|
||||
```php
|
||||
$httpResponse->setCode(Nette\Http\Response::S404_NOT_FOUND);
|
||||
|
||||
echo $httpResponse->getCode(); // 404
|
||||
```
|
||||
|
||||
For better source code readability it is recommended to use predefined constants instead of actual numbers:
|
||||
|
||||
```
|
||||
Http\IResponse::S200_OK
|
||||
Http\IResponse::S204_NO_CONTENT
|
||||
Http\IResponse::S300_MULTIPLE_CHOICES
|
||||
Http\IResponse::S301_MOVED_PERMANENTLY
|
||||
Http\IResponse::S302_FOUND
|
||||
Http\IResponse::S303_SEE_OTHER
|
||||
Http\IResponse::S303_POST_GET
|
||||
Http\IResponse::S304_NOT_MODIFIED
|
||||
Http\IResponse::S307_TEMPORARY_REDIRECT
|
||||
Http\IResponse::S400_BAD_REQUEST
|
||||
Http\IResponse::S401_UNAUTHORIZED
|
||||
Http\IResponse::S403_FORBIDDEN
|
||||
Http\IResponse::S404_NOT_FOUND
|
||||
Http\IResponse::S410_GONE
|
||||
Http\IResponse::S500_INTERNAL_SERVER_ERROR
|
||||
Http\IResponse::S501_NOT_IMPLEMENTED
|
||||
Http\IResponse::S503_SERVICE_UNAVAILABLE
|
||||
```
|
||||
|
||||
Method `setContentType($type, $charset=null)` changes `Content-Type` response header:
|
||||
|
||||
```php
|
||||
$httpResponse->setContentType('text/plain', 'UTF-8');
|
||||
```
|
||||
|
||||
Redirection to another URL is done by `redirect($url, $code=302)` method. Do not forget to terminate the script afterwards!
|
||||
|
||||
```php
|
||||
$httpResponse->redirect('http://example.com');
|
||||
exit;
|
||||
```
|
||||
|
||||
|
||||
To set the document expiration date, we can use `setExpiration()` method. The parameter is either text data, number of seconds or a timestamp:
|
||||
|
||||
```php
|
||||
// browser cache expires in one hour
|
||||
$httpResponse->setExpiration('+ 1 hours');
|
||||
```
|
||||
|
||||
Now we send the HTTP response header:
|
||||
|
||||
```php
|
||||
$httpResponse->setHeader('Pragma', 'no-cache');
|
||||
|
||||
// or if we want to send the same header more times with different values
|
||||
$httpResponse->addHeader('Pragma', 'no-cache');
|
||||
```
|
||||
|
||||
Sent headers are also available:
|
||||
|
||||
```php
|
||||
// returns associative array of headers
|
||||
$headers = $httpResponse->getHeaders();
|
||||
|
||||
// returns concrete header (case-insensitive)
|
||||
$pragma = $httpResponse->getHeader('Pragma');
|
||||
```
|
||||
|
||||
There are two methods for cookie manipulation: `setCookie()` and `deleteCookie()`.
|
||||
|
||||
```php
|
||||
// setCookie($name, $value, $time, [$path, [$domain, [$secure, [$httpOnly]]]])
|
||||
$httpResponse->setCookie('lang', 'en', '100 days'); // send cookie
|
||||
|
||||
// deleteCookie($name, [$path, [$domain, [$secure]]])
|
||||
$httpResponse->deleteCookie('lang'); // delete cookie
|
||||
```
|
||||
|
||||
These two methods can take more parameters: `$path` (subdirectory where the cookie will be available),
|
||||
`$domain` and `$secure`. Their detailed description can be found in PHP manual for [php:setcookie] function.
|
||||
Reference in New Issue
Block a user