API Reference elx_validation v0.1.3

Elx Validation

• Easy and Simple Data validator.
• make function for start validation
• ElxValidation Github Wiki Page

install

mix.exs
   {:elx_validation, "~> 0.1.3"}
mix deps.get

How To use

example_data = %{
  first_name: "Majid"
}
rules = [
   %{
      field: "first_name",
      as: "first name",
      validate: ["required", "string", "max:128"].
    },
]

field : The Field name that need to validate

as : its optional and use for response error

validate : list of rules and validations

Run Validation : ElxValidation.make(example_data , rules)

Validator has Error

%{
    errors: [
       name: ["Error Message" , "Error Message"]
    ],
    failed: true
}

Validator without Error:

%{
   errors: [],
   failed: false
}

• The field under validation must be "yes", "on", 1, or true. This is useful for validating "Terms of Service" acceptance or similar fields.

  data = %{
    agreement1: "on",
    agreement2: true,
    agreement3: "true",
    agreement4: "yes",
    agreement5: "1",
    agreement6: 1,
    agreement7: "off"
  }
  rules = [
    %{
      field: "agreement1",
      validate: ["required", "accepted"]
    },
    %{
      field: "agreement2",
      validate: ["accepted"]
    },
   %{
      field: "agreement3",
      validate: ["accepted"]
    },
    %{
      field: "agreement4",
      validate: ["accepted"]
    },
    %{
      field: "agreement5",
      validate: ["accepted"]
    },
    %{
      field: "agreement6",
      validate: ["accepted"]
    },
    %{
      field: "agreement7",
      validate: ["accepted"]
    }
  ]
  ElxValidation.make(data , rules)

• agreement7 returned error because accepted validation must be one of the : true, "true", 1 , "1" , "on" , "yes"

string

• The field under validation must be a string. If you would like to allow the field to also be null, you should assign the nullable rule to the field.

  data = %{
   user_name1: "john_007",
   user_name2: 1879,   ---> return error
  }
  rules = [
    %{
      field: "user_name1",
      validate: ["string"]
    },
   %{
      field: "user_name2",
      validate: ["string"]
    }
  ]

alpha

• The field under validation must be entirely alphabetic characters.

  data = %{
   p1: "John Doe",
   p1: "James 007",   ---> return error
  }
  rules = [
    %{
      field: "p1",
      validate: ["alpha"]
    },
   %{
      field: "p2",
      validate: ["alpha"]
    }
  ]

start_with:foo

• The field under validation must start with the given values.

data = %{
    start_code: "G123other_string",
    start_code2: "other_string". ---> return error
  }
rules = [
    %{
      field: "start_code",
      validate: ["start_with:G123"]
    },
    %{
      field: "start_code2",
      validate: ["start_with:Me32"]
    }
]

end_with:foo

• The field under validation must end with the given values

  data = %{
    end_code: "other_stringG123",
    end_code2: "other_string". ---> return error
  }
  rules = [
    %{
      field: "end_code",
      validate: ["end_with:G123"]
    },
    %{
      field: "end_code2",
      validate: ["end_with:Me32"]
    }
  ]

Build rules by rule name

boolean

• The field under validation must be able to be cast as a boolean. Accepted input are true, false, 1, 0, "1", and "0".

  data = %{
    is_ok1: "true",
    is_ok2: true,
    is_ok3: "false",
    is_ok4: false,
    is_ok5: 0,
    is_ok6: 1,
    is_ok7: "0",
    is_ok8: "1",
    is_ok9: "yes",  ---> return error
  }
  rules = [
    %{
      field: "is_ok1",
      validate: ["boolean"]
    },
    %{
      field: "is_ok2",
      validate: ["boolean"]
    },
    %{
      field: "is_ok3",
      validate: ["boolean"]
    },
    %{
      field: "is_ok4",
      validate: ["boolean"]
    },
    %{
      field: "is_ok5",
      validate: ["boolean"]
    },
    %{
      field: "is_ok6",
      validate: ["boolean"]
    },
    %{
      field: "is_ok7",
      validate: ["boolean"]
    },
    %{
      field: "is_ok8",
      validate: ["boolean"]
    },
   %{
      field: "is_ok9",
      validate: ["boolean"]
    },
  ]

confirmed

• The field under validation must have a matching field of {field}_confirmation. For example, if the field under validation is password, a matching password_confirmation field must be present in the input.

  data = %{
    password: "123456",
    password_confirmation: "123456",
  }
  rules = [
    %{
      field: "password",
      validate: ["confirmed"]
    },
  ]

date

• The field under validation must be a valid, non-relative date.
• "2020-06-26"

time

• The field under validation must be a valid, non-relative time.
• am / pm is optional
• "20:13"
• "01:02"
• "02:40am"
• "05:20pm"

datetime

• The field under validation must be a valid datetime identifier
• "2020-06-26 12:20"

timezone

• The field under validation must be a valid timezone identifier
  • "+04:30"
  • "-01:30"

data = %{
    birthdate: "1990-04-17",
    start_time: "13:30",
    expired: "2020-06-28 12:20",
    my_zone: "+04:30"
}
rules = [
    %{
      field: "birthdate",
      validate: ["date"]
    },
    %{
      field: "start_time",
      validate: ["time"]
    },
    %{
      field: "expired",
      validate: ["datetime"]
    },
    %{
      field: "my_zone",
      validate: ["timezone"]
    },
]

date_equals:date

• The field under validation must be equal to the given date.

  after:date

• The field under validation must be a value after a given date.

  after_or_equal:date

• The field under validation must be a value after or equal to the given date. For more information, see the after rule.

  before:date

• The field under validation must be a value preceding the given date.

  before_or_equal:date

• The field under validation must be a value preceding or equal to the given date.

  data = %{
    eq_bd: "1990-04-17",   ---> == "1990-04-17"
    after_bd: "1990-04-20",  ---> > "1990-04-17"
    after_equal_bd: "1990-04-18", ---> >= "1990-04-17"
    before_bd: "1990-04-16",  ---> < "1990-04-17"
    before_equal_bd: "1990-04-17",  ---> <= "1990-04-17"
  }
  rules = [
    %{
      field: "eq_bd",
      validate: ["date_equals:1990-04-17"]
    },
    %{
      field: "after_bd",
      validate: ["after:1990-04-17"]
    },
    %{
      field: "after_equal_bd",
      validate: ["after_or_equal:1990-04-17"]
    },
    %{
      field: "before_bd",
      validate: ["before:1990-04-17"]
    },
    %{
      field: "before_equal_bd",
      validate: ["before_or_equal:1990-04-17"]
    }
  ]

different:value

• The field under validation must have a different value than field.

equal:value

• The field under validation must be equal to the given field. The two fields must be of the same type. Strings and numerics are evaluated using the same conventions as the size rule.

gt:value

• The field under validation must be greater than the given field. The two fields must be of the same type. Strings and numerics are evaluated using the same conventions as the size rule.

gte:value

• The field under validation must be greater than or equal to the given field. The two fields must be of the same type. Strings and numerics are evaluated using the same conventions as the size rule.

lt:value

• The field under validation must be less than the given field. The two fields must be of the same type. Strings and numerics are evaluated using the same conventions as the size rule.

lte:value

• The field under validation must be less than or equal to the given field. The two fields must be of the same type. Strings and numerics are evaluated using the same conventions as the size rule.

examples

data = %{
   num_diff: 234 --> not be 233
   str_diff: "MQZVD" --> not be ABCD
}
rules = [
    %{
      field: "num_diff",
      validate: ["different:233"]
    },
    %{
      field: "str_diff",
      validate: ["different:ABCD"]
    }
]

data = %{
   num_eq: 100,  --> must be 100
   str_eq: "abcd" --> must be "abcd"
}
rules = [
    %{
      field: "num_eq",
      validate: ["equal:100"]
    },
    %{
      field: "str_eq",
      validate: ["equal:abcd"]
    },
]

data = %{
   num_gt: 101,  --> greater than 100
   num_gte: 200,   --> greater than or equal 200
   str_gt: "abcd",  --> length of this must greater than length of abc(3 char)
   str_gte: "abcd" --> length of this must greater than or equal length of abc(3 char)
}
rules = [
   %{
      field: "num_gt",
      validate: ["gt:100"]
    },
    %{
      field: "num_gte",
      validate: ["gte:200"]
    },
    %{
      field: "str_gt",
      validate: ["gt:abc"]
    },
    %{
      field: "str_gte",
      validate: ["gte:abc"]
    },
]

data = %{
 num_lt: 99, --> less than 100
 num_lte: 199, --> less than or equal 200
 str_lt: "ab",  --> length of this must less than length of abc(3char)
 str_lte: "abcd" --> length of this must less than length of abcde(5 char)
}
rules = [
   %{
      field: "num_lt",
      validate: ["lt:100"]
    },
    %{
      field: "num_lte",
      validate: ["lte:200"]
    },
    %{
      field: "str_lt",
      validate: ["lt:ABC"]
    },
    %{
      field: "str_lte",
      validate: ["lte:ABCDE"]
    },
]

Message builder

Control Exceptions and errors

Run Check field exist on data

in:foo,bar,...

• The field under validation must be included in the given list of values.

not_in:foo,bar,...

• The field under validation must not be included in the given list of values.

  data = %{
    country: "italy",
    grade: "a",
  }
  rules = [
    %{
      field: "country",
      validate: ["in:iran,italy,usa"]
    },
    %{
      field: "grade",
      validate: ["not_in:c,d,e", "in:a,b"]
    }
  ]

email

• The field under validation must be formatted as an email address.

url

• The field under validation must be a valid URL.

ip

• The field under validation must be an IP address.

ipv4

• The field under validation must be an IPv4 address.

ipv6

• The field under validation must be an IPv6 address.

data = %{
    email: "example@gmail.com",
    url: "http://google.com",
    ip: "192.168.1.1",
    ipv4: "192.168.1.1",
    ipv6: "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
  }
rules = [
    %{
      field: "email",
      validate: ["email"]
    },
    %{
      field: "url",
      validate: ["url"]
    },
    %{
      field: "ip",
      validate: ["ip"]
    },
    %{
      field: "ipv4",
      validate: ["ipv4"]
    },
    %{
      field: "ipv6",
      validate: ["ipv6"]
    }
  ]

max:value

• The field under validation must be less than or equal to a maximum value.Strings and numerics are evaluated in the same fashion as the size rule.

data = %{
    name: "john",
    age: 20
}
rules = [
    %{
      field: "name",
      validate: ["max:10"]
    },
    %{
      field: "age",
      validate: ["max:40"]
    }
  ]

min:value

• The field under validation must have a minimum value. Strings and numerics are evaluated in the same fashion as the size rule.

data = %{
    name: "john",
    age: 19  ---> return error minimum value is 20
}
rules = [
    %{
      field: "name",
      validate: ["min:3"]
    },
    %{
      field: "age",
      validate: ["min:20"]
    }
  ]

nullable

• The field under validation may be null.

data = %{
    optional_name: "majid",
}
rules = [
    %{
      field: "optional_name",
      validate: ["nullable" , "alpha" , "min:3"] --> nullable rule as first rule of validation
    },
]

numeric

• The field under validation must be numeric.

data = %{
     number1: 2121,
     number2: "2121"  ----> return error
  }
rules = [
   %{
      field: "number1",
      validate: ["numeric"]
    },
    %{
      field: "number2",
      validate: ["numeric"]
    }
]

digits:value

• The field under validation must be numeric and must have an exact length of value.

data = %{
    age1: 12,
    age2: 9  ---> return error min 2 digit required
}
rules = [
    %{
      field: "age1",
      validate: ["digits:2"]
    },
   %{
      field: "age2",
      validate: ["digits:2"]
    }
]

Required

• The field under validation must be present in the input data and not empty. A field is considered "empty" if one of the following conditions are true:
  • The value is null.
  • The value is an empty string.

data = %{
   first_name: "Majid"
}
rules = [
    %{
      field: "name",
      validate: ["required"]
    }
  ]

rules defined by "name" but data defined by "first name"

it returns error: "The name is not exist"

data = %{
    name: ""
}
rules = [
    %{
      field: "name",
      validate: ["required"]
    }
  ]

rules defined "required" so null , empty string not excepted

it returns error: "The name field is required."

Required If

• required_if:anotherfield
  • The field under validation must be present and not empty if the anotherfield field is exist and equal to any value.

data = %{
  first_name: "Majid",
  last_name: "Ahmadi" ---> if first_name exist and has value last_name field is required
}
rules = [
    %{
      field: "first_name",
      validate: ["nullable", "string" , "max:50"]
    },
   %{
      field: "last_name",
      validate: ["required_if:first_name"]
    }
  ]

Required Unless

• required_unless:anotherfield
  • The field under validation must be present and not empty unless the anotherfield is Not Exist or be null or empty or "" value.

data = %{
  email: "email@example.com",
  phone: "+123456789" ---> if email not exist or has null or "" value the phone field is required
}
rules = [
    %{
      field: "email",
      validate: ["nullable" , "email"]
    },
   %{
      field: "phone",
      validate: ["required_unless:email"]
    }
  ]

Required with

• required_with:foo,bar,...
  • The field under validation must be present and not empty only if any of the other specified fields are present and not empty.

data = %{
     first_name: "John",
     last_name: "doe", --> required if first_name defined and has any value
     full_name: "John Doe" -->required if first_name,last_name is exist or not empty
}
rules = [
    %{
      field: "first_name",
      validate: ["required"]
    },
   %{
      field: "last_name",
      validate: ["required_if:first_name"]
    },
    %{
      field: "full_name",
      validate: ["required_with:first_name,last_name"]
    }
  ]

Required Without

• required_without:foo,bar,...
  • The field under validation must be present and not empty only when any of the other specified fields are empty or not present.

data = %{
     first_name: "",
     last_name: "",
     full_name: "John Doe" -->required if first_name,last_name is/are not exist or empty
}

rules = [
    %{
      field: "first_name",
      validate: ["nullable" , "alpha"]
    },
   %{
      field: "last_name",
      validate: ["nullable" , "alpha"]
    },
    %{
      field: "full_name",
      validate: ["required_with:first_name,last_name"]
    }
  ]

important notice

• if you use required if , unless ,with and without, validator will validates all rules that you set

  data = %{
    first_name: "John",
    last_name: "doe" --> alpha , min and max will validate
  }

  rules = [
    %{
      field: "first_name",
      validate: ["nullable", "alpha", "min:3", "max:10"]
    },
    %{
      field: "last_name",
      validate: ["required_if:first_name" , "alpha", "min:3", "max:10"]
    }
  ]

the logic is :

if first_name has value then last_name is required

if first_name hasn't value then last_name is not required

in case first_name does not exist or null last_name is not necessary but alpha and min and max validations still works.

File

• the field under validation must be a file and at leas 1 kilobyte size
• empty value return error unless field is under nullable validation

  data = %{
    logo: "LOGO FILE",
  }
  rules = [
    %{
      field: "logo",
      validate: ["file","min_size:10","max_size:20","mimes:png,jpg","mime_types:image/png,image/jpeg"]
    },
  ]

• file : data must be a file and at least 1 kb size
• min_size: minimum size (Kb) of file
• max_size: maximum size (Kb) of file
• mimes: list of accepted mimes
• mime_types: list of accepted mime_types

uuid

• The field under validation must be a valid RFC 4122 universally unique identifier (UUID).

data = %{
    uuid_1: "56b2724e-9074-4dc3-9803-4bb13c92ee0e",
    uuid_2: "56b2-9074-4dc3-9803-4bb13c9",   ---> not UUID
}

rules = [
    %{
      field: "uuid_1",
      validate: ["uuid"]
    },
   %{
      field: "uuid_2",
      validate: ["uuid"]
    },
  ]

Validator Factory