2017 © Pedro Peláez
 

library gump

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

image

wixel/gump

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  • Tuesday, July 17, 2018
  • by Wixel
  • Repository
  • 93 Watchers
  • 949 Stars
  • 170,819 Installations
  • PHP
  • 25 Dependents
  • 0 Suggesters
  • 309 Forks
  • 36 Open issues
  • 14 Versions
  • 13 % Grown

The README.md

Getting started

GUMP is a standalone PHP data validation and filtering class that makes validating any data easy and painless without the reliance on a framework. GUMP is open-source since 2013., (*1)

License Total Downloads Latest Stable Version Build Status Coverage Status, (*2)

Install with composer

composer require wixel/gump

Short format example for validations

$is_valid = GUMP::is_valid(array_merge($_POST, $_FILES), [
    'username'       => 'required|alpha_numeric',
    'password'       => 'required|between_len,4;100',
    'avatar'         => 'required_file|extension,png;jpg',
    'tags'           => 'required|alpha_numeric', // ['value1', 'value3']
    'person.name'    => 'required',               // ['person' => ['name' => 'value']]
    'persons.*.age'  => 'required'                // ['persons' => [
                                                  //      ['name' => 'value1', 'age' => 20],
                                                  //      ['name' => 'value2']
                                                  // ]]
]);

// 1st array is rules definition, 2nd is field-rule specific error messages (optional)
$is_valid = GUMP::is_valid(array_merge($_POST, $_FILES), [
    'username' => ['required', 'alpha_numeric'],
    'password' => ['required', 'between_len' => [6, 100]],
    'avatar'   => ['required_file', 'extension' => ['png', 'jpg']]
], [
    'username' => ['required' => 'Fill the Username field please.'],
    'password' => ['between_len' => '{field} must be between {param[0]} and {param[1]} characters.'],
    'avatar'   => ['extension' => 'Valid extensions for avatar are: {param}'] // "png, jpg"
]);

if ($is_valid === true) {
    // continue
} else {
    var_dump($is_valid); // array of error messages
}

Short format example for filtering

$filtered = GUMP::filter_input([
    'field'       => ' text ',
    'other_field' => 'Cool Title'
], [
    'field'       => ['trim', 'upper_case'],
    'other_field' => 'slug'
]);

var_dump($filtered['field']); // result: "TEXT"
var_dump($filtered['other_field']); // result: "cool-title"

Long format example

$gump = new GUMP();

// set validation rules
$gump->validation_rules([
    'username'    => 'required|alpha_numeric|max_len,100|min_len,6',
    'password'    => 'required|max_len,100|min_len,6',
    'email'       => 'required|valid_email',
    'gender'      => 'required|exact_len,1|contains,m;f',
    'credit_card' => 'required|valid_cc'
]);

// set field-rule specific error messages
$gump->set_fields_error_messages([
    'username'      => ['required' => 'Fill the Username field please, its required.'],
    'credit_card'   => ['extension' => 'Please enter a valid credit card.']
]);

// set filter rules
$gump->filter_rules([
    'username' => 'trim|sanitize_string',
    'password' => 'trim',
    'email'    => 'trim|sanitize_email',
    'gender'   => 'trim',
    'bio'      => 'noise_words'
]);

// on success: returns array with same input structure, but after filters have run
// on error: returns false
$valid_data = $gump->run($_POST);

if ($gump->errors()) {
    var_dump($gump->get_readable_errors()); // ['Field <span class="gump-field">Somefield</span> is required.'] 
    // or
    var_dump($gump->get_errors_array()); // ['field' => 'Field Somefield is required']
} else {
    var_dump($valid_data);
}

:star: Available Validators

Important: If you use Pipe or Semicolon as parameter value, you must use array format., (*3)

$is_valid = GUMP::is_valid(array_merge($_POST, $_FILES), [
    'field' => 'regex,/partOf;my|Regex/', // NO
    'field' => ['regex' => '/partOf;my|Regex/'] // YES
]);
| Rule | Description | |--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **required** | Ensures the specified key value exists and is not empty (not null, not empty string, not empty array). | | **contains**,one;two;use array format if one of the values contains semicolons | Verify that a value is contained within the pre-defined value set. | | **contains_list**,value1;value2 | Verify that a value is contained within the pre-defined value set. Error message will NOT show the list of possible values. | | **doesnt_contain_list**,value1;value2 | Verify that a value is contained within the pre-defined value set. Error message will NOT show the list of possible values. | | **boolean**,strict | Determine if the provided value is a valid boolean. Returns true for: yes/no, on/off, 1/0, true/false. In strict mode (optional) only true/false will be valid which you can combine with boolean filter. | | **valid_email** | Determine if the provided email has valid format. | | **max_len**,240 | Determine if the provided value length is less or equal to a specific value. | | **min_len**,4 | Determine if the provided value length is more or equal to a specific value. | | **exact_len**,5 | Determine if the provided value length matches a specific value. | | **between_len**,3;11 | Determine if the provided value length is between min and max values. | | **alpha** | Determine if the provided value contains only alpha characters. | | **alpha_numeric** | Determine if the provided value contains only alpha-numeric characters. | | **alpha_dash** | Determine if the provided value contains only alpha characters with dashed and underscores. | | **alpha_numeric_dash** | Determine if the provided value contains only alpha numeric characters with dashed and underscores. | | **alpha_numeric_space** | Determine if the provided value contains only alpha numeric characters with spaces. | | **alpha_space** | Determine if the provided value contains only alpha characters with spaces. | | **numeric** | Determine if the provided value is a valid number or numeric string. | | **integer** | Determine if the provided value is a valid integer. | | **float** | Determine if the provided value is a valid float. | | **valid_url** | Determine if the provided value is a valid URL. | | **url_exists** | Determine if a URL exists & is accessible. | | **valid_ip** | Determine if the provided value is a valid IP address. | | **valid_ipv4** | Determine if the provided value is a valid IPv4 address. | | **valid_ipv6** | Determine if the provided value is a valid IPv6 address. | | **valid_cc** | Determine if the input is a valid credit card number. | | **valid_name** | Determine if the input is a valid human name. | | **street_address** | Determine if the provided input is likely to be a street address using weak detection. | | **iban** | Determine if the provided value is a valid IBAN. | | **date**,d/m/Y | Determine if the provided input is a valid date (ISO 8601) or specify a custom format (optional). | | **min_age**,18 | Determine if the provided input meets age requirement (ISO 8601). Input should be a date (Y-m-d). | | **max_numeric**,50 | Determine if the provided numeric value is lower or equal to a specific value. | | **min_numeric**,1 | Determine if the provided numeric value is higher or equal to a specific value. | | **starts**,Z | Determine if the provided value starts with param. | | **required_file** | Determine if the file was successfully uploaded. | | **extension**,png;jpg;gif | Check the uploaded file for extension. Doesn't check mime-type yet. | | **equalsfield**,other_field_name | Determine if the provided field value equals current field value. | | **guidv4** | Determine if the provided field value is a valid GUID (v4) | | **phone_number** | Determine if the provided value is a valid phone number. | | **regex**,/test-[0-9]{3}/ | Custom regex validator. | | **valid_json_string** | Determine if the provided value is a valid JSON string. | | **valid_array_size_greater**,1 | Check if an input is an array and if the size is more or equal to a specific value. | | **valid_array_size_lesser**,1 | Check if an input is an array and if the size is less or equal to a specific value. | | **valid_array_size_equal**,1 | Check if an input is an array and if the size is equal to a specific value. | | **valid_twitter** | Determine if the provided value is a valid Twitter account. |

:star: Available Filters

Filter rules can also be any PHP native function (e.g.: trim)., (*4)

| Filter | Description | |------------------------|-----------------------------------------------------------------------------------------------------------------------| | **noise_words** | Replace noise words in a string (http://tax.cchgroup.com/help/Avoiding_noise_words_in_your_search.htm). | | **rmpunctuation** | Remove all known punctuation from a string. | | **urlencode** | Sanitize the string by urlencoding characters. | | **htmlencode** | Sanitize the string by converting HTML characters to their HTML entities. | | **sanitize_email** | Sanitize the string by removing illegal characters from emails. | | **sanitize_numbers** | Sanitize the string by removing illegal characters from numbers. | | **sanitize_floats** | Sanitize the string by removing illegal characters from float numbers. | | **sanitize_string** | Sanitize the string by removing any script tags. | | **boolean** | Converts ['1', 1, 'true', true, 'yes', 'on'] to true, anything else is false ('on' is useful for form checkboxes). | | **basic_tags** | Filter out all HTML tags except the defined basic tags. | | **whole_number** | Convert the provided numeric value to a whole number. | | **ms_word_characters** | Convert MS Word special characters to web safe characters. ([“ ”] => ", [‘ ’] => ', [–] => -, […] => ...) | | **lower_case** | Converts to lowercase. | | **upper_case** | Converts to uppercase. | | **slug** | Converts value to url-web-slugs. | | **trim** | Remove spaces from the beginning and end of strings (PHP). |

Other Available Methods

/**
 * This is the most flexible validation "executer" because of it's return errors format.
 *
 * Returns bool true when no errors.
 * Returns array of errors with detailed info. which you can then use with your own helpers.
 * (field name, input value, rule that failed and it's parameters).
 */
$gump->validate(array $input, array $ruleset);

/**
 * Filters input data according to the provided filterset
 *
 * Returns array with same input structure but after filters have been applied.
 */
$gump->filter(array $input, array $filterset);

// Sanitizes data and converts strings to UTF-8 (if available), optionally according to the provided field whitelist
$gump->sanitize(array $input, $whitelist = null);

// Override field names in error messages
GUMP::set_field_name('str', 'Street');
GUMP::set_field_names([
    'str' => 'Street',
    'zip' => 'ZIP Code'
]);

// Set custom error messages for rules.
GUMP::set_error_message('required', '{field} is required.');
GUMP::set_error_messages([
    'required'    => '{field} is required.',
    'valid_email' => '{field} must be a valid email.'
]);

// Strips and encodes unwanted characters
GUMP::xss_clean(array $data);

Creating your own validators and filters

Adding custom validators and filters is made easy by using callback functions., (*5)

/**
 * You would call it like 'equals_string,someString'
 *
 * @param string $field  Field name
 * @param array  $input  Whole input data
 * @param array  $params Rule parameters. This is usually empty array by default if rule does not have parameters.
 * @param mixed  $value  Value.
 *                       In case of an array ['value1', 'value2'] would return one single value.
 *                       If you want to get the array itself use $input[$field].
 *
 * @return bool   true or false whether the validation was successful or not
 */
GUMP::add_validator("equals_string", function($field, array $input, array $params, $value) {
    return $value === $params;
}, 'Field {field} does not equal to {param}.');

/**
 * @param string $value Value
 * @param array  $param Filter parameters (optional)
 *
 * @return mixed  result of filtered value
 */
GUMP::add_filter("upper", function($value, array $params = []) {
    return strtoupper($value);
});

Alternately, you can simply create your own class that extends GUMP. You only have to have in mind:, (*6)

  • For filter methods, prepend the method name with "filter_".
  • For validator methods, prepend the method name with "validate_".
class MyClass extends GUMP
{
    protected function filter_myfilter($value, array $params = [])
    {
        return strtoupper($value);
    }

    protected function validate_myvalidator($field, array $input, array $params = [], $value)
    {
        return $input[$field] === 'good_value';
    }
}

$validator = new MyClass();
$validated = $validator->validate($_POST, $rules);

Global configuration

This configuration values allows you to change default rules delimiters (e.g.: required|contains,value1;value2 to required|contains:value1,value2)., (*7)

GUMP::$rules_delimiter = '|';

GUMP::$rules_parameters_delimiter = ',';

GUMP::$rules_parameters_arrays_delimiter = ';';

The Versions

17/07 2018

v2.x-dev

2.9999999.9999999.9999999-dev https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

03/06 2018

dev-master

9999999-dev https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

02/06 2018

dev-revert-247-master

dev-revert-247-master https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

04/08 2017

v1.5.6

1.5.6.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

25/07 2017

v1.5.5

1.5.5.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

19/07 2017

v1.5.4

1.5.4.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

09/07 2017

v1.5.3

1.5.3.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

18/04 2017

v1.5.2

1.5.2.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

22/03 2017

v1.5.1

1.5.1.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

22/03 2017

v1.2

1.2.0.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

02/08 2016

1.4

1.4.0.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

06/08 2015

1.3

1.3.0.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

06/08 2015

1.2

1.2.0.0 https://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT

10/06 2014

v1.1

1.1.0.0 http://wixelhq.com/

A fast, extensible & stand-alone PHP input validation class that allows you to validate any data

  Sources   Download

MIT