Merge pull request #262 from raicabogdan/6.0.x

Update Filter and API documentation for filter and Request

Author: niden

docs/api/phalcon_filter.md

@@ -55,6 +55,32 @@ Exceptions thrown in Phalcon\Filter will use this class
 
 Lazy loads, stores and exposes sanitizer objects
 
+@method int          absint(mixed $input)
+@method string       alnum(mixed $input)
+@method string       alpha(mixed $input)
+@method bool         bool(mixed $input)
+@method string       email(string $input)
+@method float        float(mixed $input)
+@method int          int(string $input)
+@method string|false ip(string $input, int $filter = FILTER_FLAG_NONE)
+@method string       lower(string $input)
+@method string       lowerfirst(string $input)
+@method mixed        regex(mixed $input, mixed $pattern, mixed $replace)
+@method mixed        remove(mixed $input, mixed $replace)
+@method mixed        replace(mixed $input, mixed $source, mixed $target)
+@method string       special(string $input)
+@method string       specialfull(string $input)
+@method string       string(string $input)
+@method string       stringlegacy(mixed $input)
+@method string       striptags(string $input)
+@method string       trim(string $input)
+@method string       upper(string $input)
+@method string       upperFirst(string $input)
+@method null         upperWords(string $input): strin
+@method null         url(string $input): strin
+
+@property array $mapper
+@property array $services
 
 
 ### Constants
@@ -66,6 +92,7 @@ const FILTER_BOOL = bool;
 const FILTER_EMAIL = email;
 const FILTER_FLOAT = float;
 const FILTER_INT = int;
+const FILTER_IP = ip;
 const FILTER_LOWER = lower;
 const FILTER_LOWERFIRST = lowerfirst;
 const FILTER_REGEX = regex;
@@ -447,6 +474,39 @@ public function __invoke( mixed $input );
 
 
 
+## Filter\Sanitize\Ip 
+
+[Source on GitHub](https://github.com/phalcon/cphalcon/blob/5.0.x/phalcon/Filter/Sanitize/Ip.zep)
+
+
+-   __Namespace__
+
+    - `Phalcon\Filter\Sanitize`
+
+-   __Uses__
+    
+
+-   __Extends__
+    
+
+-   __Implements__
+    
+
+Phalcon\Filter\Sanitize\IP
+
+Sanitizes a value to an ip address or CIDR range
+
+
+### Methods
+
+```php
+public function __invoke( string $input, int $filter = int ): string | false;
+```
+
+
+
+
+
 ## Filter\Sanitize\Lower 
 
 [Source on GitHub](https://github.com/phalcon/cphalcon/blob/5.0.x/phalcon/Filter/Sanitize/Lower.zep)
@@ -2223,6 +2283,16 @@ $validator->add(
         ]
     )
 );
+
+$validator->add(
+    "täst@example.com",
+    new EmailValidator(
+        [
+            "message" => "The e-mail is not valid",
+            "allowUTF8" => true,
+        ]
+    )
+);
 ```
 
 

docs/api/phalcon_http.md

@@ -115,7 +115,7 @@ protected $value;
 ### Methods
 
 ```php
-public function __construct( string $name, mixed $value = null, int $expire = int, string $path = string, bool $secure = null, string $domain = null, bool $httpOnly = null, array $options = [] );
+public function __construct( string $name, mixed $value = null, int $expire = int, string $path = string, bool $secure = bool, string $domain = string, bool $httpOnly = bool, array $options = [] );
 ```
 Phalcon\Http\Cookie constructor.
 
@@ -717,6 +717,11 @@ private $rawBody = ;
  */
 private $strictHostCheck = false;
 
+/**
+ * @var array
+ */
+private $trustedProxies;
+
 ```
 
 ### Methods
@@ -772,11 +777,11 @@ _SERVER["HTTP_ACCEPT_LANGUAGE"]
 
 
 ```php
-public function getClientAddress( bool $trustForwardedHeader = bool ): string | bool;
+public function getClientAddress( bool $trustForwardedHeader = bool ): string | false;
 ```
-Gets most possible client IPv4 Address. This method searches in
+Gets most possible client IP Address. This method searches in
 `$_SERVER["REMOTE_ADDR"]` and optionally in
-`$_SERVER["HTTP_X_FORWARDED_FOR"]`
+`$_SERVER["HTTP_X_FORWARDED_FOR"]` and returns the first non-private or non-reserved IP address
 
 
 ```php
@@ -832,7 +837,7 @@ Retrieves a query/get value always sanitized with the preset filters
 ```php
 public function getHTTPReferer(): string;
 ```
-Gets web page that refers active request. ie: https://www.google.com
+Gets web page that refers active request. ie: http://www.google.com
 
 
 ```php
@@ -980,13 +985,13 @@ Note: This method relies on the `$_SERVER["HTTP_ACCEPT_LANGUAGE"]` header.
 ```php
 public function getPut( string $name = null, mixed $filters = null, mixed $defaultValue = null, bool $notAllowEmpty = bool, bool $noRecursive = bool ): mixed;
 ```
-Gets a variable from put request
+Gets a variable from the PUT request
 
 ```php
-// Returns value from $_PUT["user_email"] without sanitizing
+// Returns value from PUT stream without sanitizing
 $userEmail = $request->getPut("user_email");
 
-// Returns value from $_PUT["user_email"] with sanitizing
+// Returns value from PUT stream with sanitizing
 $userEmail = $request->getPut("user_email", "email");
 ```
 
@@ -1247,6 +1252,12 @@ Sets if the `Request::getHttpHost` method must be use strict validation
 of host name or not
 
 
+```php
+public function setTrustedProxies( array $trustedProxies ): RequestInterface;
+```
+Set trusted proxy
+
+
 ```php
 final protected function getBestQuality( array $qualityParts, string $name ): string;
 ```
@@ -1272,6 +1283,12 @@ final protected function hasFileHelper( mixed $data, bool $onlySuccessful ): lon
 Recursively counts file in an array of files
 
 
+```php
+protected function isIpAddressInCIDR( string $ip, string $cidr ): bool;
+```
+Check if an IP address exists in CIDR range
+
+
 ```php
 protected function resolveAuthorizationHeaders(): array;
 ```
@@ -1642,7 +1659,7 @@ $_SERVER["PHP_AUTH_DIGEST"]
 ```php
 public function getHTTPReferer(): string;
 ```
-Gets web page that refers active request. ie: https://www.google.com
+Gets web page that refers active request. ie: http://www.google.com
 
 
 ```php
@@ -1756,13 +1773,13 @@ $userEmail = $request->getPost("user_email", "email");
 ```php
 public function getPut( string $name = null, mixed $filters = null, mixed $defaultValue = null, bool $notAllowEmpty = bool, bool $noRecursive = bool ): mixed;
 ```
-Gets a variable from put request
+Gets a variable from the PUT request
 
 ```php
-// Returns value from $_PUT["user_email"] without sanitizing
+// Returns value from PUT stream without sanitizing
 $userEmail = $request->getPut("user_email");
 
-// Returns value from $_PUT["user_email"] with sanitizing
+// Returns value from PUT stream with sanitizing
 $userEmail = $request->getPut("user_email", "email");
 ```
 
@@ -2531,7 +2548,7 @@ Cookies aren't sent if headers are sent in the current request
 
 
 ```php
-public function set( string $name, mixed $value = null, int $expire = int, string $path = string, bool $secure = null, string $domain = null, bool $httpOnly = null, array $options = [] ): CookiesInterface;
+public function set( string $name, mixed $value = null, int $expire = int, string $path = string, bool $secure = bool, string $domain = string, bool $httpOnly = bool, array $options = [] ): CookiesInterface;
 ```
 Sets a cookie to be sent at the end of the request.
 
@@ -2637,7 +2654,7 @@ Sends the cookies to the client
 
 
 ```php
-public function set( string $name, mixed $value = null, int $expire = int, string $path = string, bool $secure = null, string $domain = null, bool $httpOnly = null, array $options = [] ): CookiesInterface;
+public function set( string $name, mixed $value = null, int $expire = int, string $path = string, bool $secure = bool, string $domain = string, bool $httpOnly = bool, array $options = [] ): CookiesInterface;
 ```
 Sets a cookie to be sent at the end of the request
 

docs/filter-filter.md

@@ -117,6 +117,21 @@ IntVal( mixed $input ): int
 ```
 Remove all characters except digits, plus and minus sign, and casts the value as an integer. Internally it uses [filter_var][filter_var] and `(int)`.
 
+#### `ip`
+```php
+Ip( string input, int filter = 0 ): int
+```
+Sanitize the IP address or CIDR IP range. Internally it uses [filter_var][filter_var]. You can pass specific filters to sanitize your input:
+
+```
+FILTER_FLAG_IPV4
+FILTER_FLAG_IPV6
+FILTER_FLAG_NO_RES_RANGE
+FILTER_FLAG_NO_PRIV_RANGE
+```
+By default, it will detect the IPv4 or IPv6 protocol if you do not use a predefined filter and sanitize the input.
+It will return `false` for invalid IP address or CIDR IP range.
+
 #### `lower`
 ```php
 Lower( mixed $input ): string
@@ -220,6 +235,7 @@ const FILTER_BOOL          = 'bool';
 const FILTER_EMAIL         = 'email';
 const FILTER_FLOAT         = 'float';
 const FILTER_INT           = 'int';
+const FILTER_IP            = 'ip';
 const FILTER_LOWER         = 'lower';
 const FILTER_LOWERFIRST    = 'lowerfirst';
 const FILTER_REGEX         = 'regex';
@@ -262,6 +278,7 @@ $filter->bool(mixed $input): bool
 $filter->email(string $input): string
 $filter->float(mixed $input): float
 $filter->int(string $input): int
+filter->ip(string $input, int $filter = FILTER_FLAG_NONE): string|false
 $filter->lower(string $input): string
 $filter->lowerfirst(string $input): string
 $filter->regex(mixed $input, mixed $pattern, mixed $replace): mixed
@@ -583,6 +600,7 @@ $filteredIp = $locator->sanitize('127.0.0.1', 'ipv4');
 [filter-sanitize-email]: api/phalcon_filter.md#filtersanitizeemail
 [filter-sanitize-floatval]: api/phalcon_filter.md#filtersanitizefloatval
 [filter-sanitize-intval]: api/phalcon_filter.md#filtersanitizeintval
+[filter-sanitize-ip]: api/phalcon_filter.md#filtersanitizeip
 [filter-sanitize-lower]: api/phalcon_filter.md#filtersanitizelower
 [filter-sanitize-lowerfirst]: api/phalcon_filter.md#filtersanitizelowerfirst
 [filter-sanitize-regex]: api/phalcon_filter.md#filtersanitizeregex