Skip to content

Commit cfa97d3

Browse files
kenjiskenjis
authored
Merge pull request #7558 from kenjis/fix-docs-libraries/validation.rst
docs: improve libraries/validation.rst
2 parents 49dabc1 + a842af4 commit cfa97d3

2 files changed

Lines changed: 75 additions & 62 deletions

File tree

‎user_guide_src/source/libraries/validation.rst‎

Lines changed: 72 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -759,71 +759,72 @@ alpha_numeric_space No Fails if field contains anything other than
759759
alphanumeric or space characters.
760760
alpha_numeric_punct No Fails if field contains anything other than
761761
alphanumeric, space, or this limited set of
762-
punctuation characters: ~ (tilde),
763-
! (exclamation), # (number), $ (dollar),
764-
% (percent), & (ampersand), * (asterisk),
765-
- (dash), _ (underscore), + (plus),
766-
= (equals), | (vertical bar), : (colon),
767-
. (period).
762+
punctuation characters: ``~`` (tilde),
763+
``!`` (exclamation), ``#`` (number),
764+
``$`` (dollar), ``% (percent), & (ampersand),
765+
``*`` (asterisk), ``-`` (dash),
766+
``_`` (underscore), ``+`` (plus),
767+
``=`` (equals), ``|`` (vertical bar),
768+
``:`` (colon), ``.`` (period).
768769
decimal No Fails if field contains anything other than
769-
a decimal number.
770-
Also accepts a + or - sign for the number.
771-
differs Yes Fails if field does not differ from the one differs[field_name]
770+
a decimal number. Also accepts a ``+`` or
771+
``-`` sign for the number.
772+
differs Yes Fails if field does not differ from the one ``differs[field_name]``
772773
in the parameter.
773-
exact_length Yes Fails if field is not exactly the parameter exact_length[5] or exact_length[5,8,12]
774+
exact_length Yes Fails if field is not exactly the parameter ``exact_length[5]`` or ``exact_length[5,8,12]``
774775
value. One or more comma-separated values.
775-
greater_than Yes Fails if field is less than or equal to greater_than[8]
776+
greater_than Yes Fails if field is less than or equal to ``greater_than[8]``
776777
the parameter value or not numeric.
777-
greater_than_equal_to Yes Fails if field is less than the parameter greater_than_equal_to[5]
778+
greater_than_equal_to Yes Fails if field is less than the parameter ``greater_than_equal_to[5]``
778779
value, or not numeric.
779780
hex No Fails if field contains anything other than
780781
hexadecimal characters.
781782
if_exist No If this rule is present, validation will
782-
only return possible errors if the field key
783-
exists, regardless of its value.
784-
in_list Yes Fails if field is not within a predetermined in_list[red,blue,green]
783+
check the field only when the field key
784+
exists in the data to validate.
785+
in_list Yes Fails if field is not within a predetermined ``in_list[red,blue,green]``
785786
list.
786787
integer No Fails if field contains anything other than
787788
an integer.
788789
is_natural No Fails if field contains anything other than
789790
a natural number: 0, 1, 2, 3, etc.
790791
is_natural_no_zero No Fails if field contains anything other than
791792
a natural number, except zero: 1, 2, 3, etc.
792-
is_not_unique Yes Checks the database to see if the given value is_not_unique[table.field,where_field,where_value]
793+
is_not_unique Yes Checks the database to see if the given value ``is_not_unique[table.field,where_field,where_value]``
793794
exist. Can ignore records by field/value to
794795
filter (currently accept only one filter).
795-
is_unique Yes Checks if this field value exists in the is_unique[table.field,ignore_field,ignore_value]
796+
is_unique Yes Checks if this field value exists in the ``is_unique[table.field,ignore_field,ignore_value]``
796797
database. Optionally set a column and value
797798
to ignore, useful when updating records to
798799
ignore itself.
799-
less_than Yes Fails if field is greater than or equal to less_than[8]
800+
less_than Yes Fails if field is greater than or equal to ``less_than[8]``
800801
the parameter value or not numeric.
801-
less_than_equal_to Yes Fails if field is greater than the parameter less_than_equal_to[8]
802+
less_than_equal_to Yes Fails if field is greater than the parameter ``less_than_equal_to[8]``
802803
value or not numeric.
803804
matches Yes The value must match the value of the field
804-
in the parameter. matches[field]
805-
max_length Yes Fails if field is longer than the parameter max_length[8]
805+
in the parameter. ``matches[field]``
806+
max_length Yes Fails if field is longer than the parameter ``max_length[8]``
806807
value.
807-
min_length Yes Fails if field is shorter than the parameter min_length[3]
808+
min_length Yes Fails if field is shorter than the parameter ``min_length[3]``
808809
value.
809-
not_in_list Yes Fails if field is within a predetermined not_in_list[red,blue,green]
810+
not_in_list Yes Fails if field is within a predetermined ``not_in_list[red,blue,green]``
810811
list.
811812
numeric No Fails if field contains anything other than
812813
numeric characters.
813-
regex_match Yes Fails if field does not match the regular regex_match[/regex/]
814+
regex_match Yes Fails if field does not match the regular ``regex_match[/regex/]``
814815
expression.
815816
permit_empty No Allows the field to receive an empty array,
816817
empty string, null or false.
817818
required No Fails if the field is an empty array, empty
818819
string, null or false.
819-
required_with Yes The field is required when any of the other required_with[field1,field2]
820-
required fields are present in the data.
821-
required_without Yes The field is required when any of other required_without[field1,field2]
822-
fields do not pass ``required`` checks.
820+
required_with Yes The field is required when any of the other ``required_with[field1,field2]``
821+
fields is not `empty()`_ in the data.
822+
required_without Yes The field is required when any of the other ``required_without[field1,field2]``
823+
fields is `empty()`_ in the data.
823824
string No A generic alternative to the alpha* rules
824825
that confirms the element is a string
825826
timezone No Fails if field does match a timezone per
826-
``timezone_identifiers_list``
827+
`timezone_identifiers_list()`_
827828
valid_base64 No Fails if field contains anything other than
828829
valid Base64 characters.
829830
valid_json No Fails if field does not contain a valid JSON
@@ -832,45 +833,55 @@ valid_email No Fails if field does not contain a valid
832833
email address.
833834
valid_emails No Fails if any value provided in a comma
834835
separated list is not a valid email.
835-
valid_ip No Fails if the supplied IP is not valid. valid_ip[ipv6]
836-
Accepts an optional parameter of 'ipv4' or
837-
'ipv6' to specify an IP format.
836+
valid_ip Yes Fails if the supplied IP is not valid. ``valid_ip[ipv6]``
837+
Accepts an optional parameter of ``ipv4`` or
838+
``ipv6`` to specify an IP format.
838839
valid_url No Fails if field does not contain (loosely) a
839840
URL. Includes simple strings that could be
840841
hostnames, like "codeigniter".
841-
valid_url_strict Yes Fails if field does not contain a valid URL. valid_url_strict[https]
842+
**Normally,** ``valid_url_strict`` **should
843+
be used.**
844+
valid_url_strict Yes Fails if field does not contain a valid URL. ``valid_url_strict[https]``
842845
You can optionally specify a list of valid
843846
schemas. If not specified, ``http,https``
844-
are valid. This rule uses
845-
PHP's ``FILTER_VALIDATE_URL``.
846-
valid_date No Fails if field does not contain a valid date. valid_date[d/m/Y]
847-
Accepts an optional parameter to matches
848-
a date format.
849-
valid_cc_number Yes Verifies that the credit card number matches valid_cc_number[amex]
847+
are valid. This rule uses PHP's
848+
``FILTER_VALIDATE_URL``.
849+
valid_date Yes Fails if field does not contain a valid date. ``valid_date[d/m/Y]``
850+
Any string that `strtotime()`_ accepts is
851+
valid if you don't specify an optional
852+
parameter to matches a date format.
853+
**So it is usually necessary to specify
854+
the parameter.**
855+
valid_cc_number Yes Verifies that the credit card number matches ``valid_cc_number[amex]``
850856
the format used by the specified provider.
851857
Current supported providers are:
852-
American Express (amex),
853-
China Unionpay (unionpay),
854-
Diners Club CarteBlance (carteblanche),
855-
Diners Club (dinersclub),
856-
Discover Card (discover),
857-
Interpayment (interpayment), JCB (jcb),
858-
Maestro (maestro), Dankort (dankort),
859-
NSPK MIR (mir),
860-
Troy (troy), MasterCard (mastercard),
861-
Visa (visa), UATP (uatp), Verve (verve),
862-
CIBC Convenience Card (cibc),
863-
Royal Bank of Canada Client Card (rbc),
864-
TD Canada Trust Access Card (tdtrust),
865-
Scotiabank Scotia Card (scotia),
866-
BMO ABM Card (bmoabm),
867-
HSBC Canada Card (hsbc)
858+
American Express (``amex``),
859+
China Unionpay (``unionpay``),
860+
Diners Club CarteBlance (``carteblanche``),
861+
Diners Club (``dinersclub``),
862+
Discover Card (``discover``),
863+
Interpayment (``interpayment``),
864+
JCB (``jcb``), Maestro (``maestro``),
865+
Dankort (``dankort``), NSPK MIR (``mir``),
866+
Troy (``troy``), MasterCard (``mastercard``),
867+
Visa (``visa``), UATP (``uatp``),
868+
Verve (``verve``),
869+
CIBC Convenience Card (``cibc``),
870+
Royal Bank of Canada Client Card (``rbc``),
871+
TD Canada Trust Access Card (``tdtrust``),
872+
Scotiabank Scotia Card (``scotia``),
873+
BMO ABM Card (``bmoabm``),
874+
HSBC Canada Card (``hsbc``)
868875
======================= ========== ============================================= ===================================================
869876

870877
.. note:: You can also use any native PHP functions that return boolean and
871878
permit at least one parameter, the field data to validate.
872879
The Validation library **never alters the data** to validate.
873880

881+
.. _timezone_identifiers_list(): https://www.php.net/manual/en/function.timezone-identifiers-list.php
882+
.. _strtotime(): https://www.php.net/manual/en/function.strtotime.php
883+
.. _empty(): https://www.php.net/manual/en/function.empty.php
884+
874885
.. _rules-for-file-uploads:
875886

876887
Rules for File Uploads
@@ -892,25 +903,25 @@ file upload related rules::
892903
======================= ========== ============================================= ===================================================
893904
Rule Parameter Description Example
894905
======================= ========== ============================================= ===================================================
895-
uploaded Yes Fails if the name of the parameter does not uploaded[field_name]
906+
uploaded Yes Fails if the name of the parameter does not ``uploaded[field_name]``
896907
match the name of any uploaded files.
897-
max_size Yes Fails if the uploaded file named in the max_size[field_name,2048]
908+
max_size Yes Fails if the uploaded file named in the ``max_size[field_name,2048]``
898909
parameter is larger than the second
899910
parameter in kilobytes (kb). Or if the file
900911
is larger than allowed maximum size declared
901912
in php.ini config file -
902913
``upload_max_filesize`` directive.
903-
max_dims Yes Fails if the maximum width and height of an max_dims[field_name,300,150]
914+
max_dims Yes Fails if the maximum width and height of an ``max_dims[field_name,300,150]``
904915
uploaded image exceed values. The first
905916
parameter is the field name. The second is
906917
the width, and the third is the height. Will
907918
also fail if the file cannot be determined
908919
to be an image.
909-
mime_in Yes Fails if the file's mime type is not one mime_in[field_name,image/png,image/jpeg]
920+
mime_in Yes Fails if the file's mime type is not one ``mime_in[field_name,image/png,image/jpeg]``
910921
listed in the parameters.
911-
ext_in Yes Fails if the file's extension is not one ext_in[field_name,png,jpg,gif]
922+
ext_in Yes Fails if the file's extension is not one ``ext_in[field_name,png,jpg,gif]``
912923
listed in the parameters.
913-
is_image Yes Fails if the file cannot be determined to be is_image[field_name]
924+
is_image Yes Fails if the file cannot be determined to be ``is_image[field_name]``
914925
an image based on the mime type.
915926
======================= ========== ============================================= ===================================================
916927

‎user_guide_src/source/libraries/validation/038.php‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,7 @@
66
'name' => "is_unique[supplier.name,uuid, {$uuid}]", // is not ok
77
'name' => "is_unique[supplier.name,uuid,{$uuid} ]", // is not ok
88
'name' => "is_unique[supplier.name,uuid,{$uuid}]", // is ok
9-
'name' => 'is_unique[supplier.name,uuid,{uuid}]', // is ok - see "Validation Placeholders"
9+
'name' => 'is_unique[supplier.name,uuid,{uuid}]', // is ok - see "Validation Placeholders"
1010
]);
11+
// Warning: If `$uuid` is a user input, be sure to validate the format of the value before using it.
12+
// Otherwise, it is vulnerable.

0 commit comments

Comments
 (0)