{"id":20494333,"url":"https://github.com/voltra/yavlphp","last_synced_at":"2026-04-19T11:35:38.538Z","repository":{"id":62545254,"uuid":"113470849","full_name":"Voltra/yavlphp","owner":"Voltra","description":"The PHP implementation of yavljs (https://www.npmjs.com/package/yavljs) that allows you to use the same definitions for front-end and back-end","archived":false,"fork":false,"pushed_at":"2017-12-08T21:16:55.000Z","size":1226,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-02T01:34:42.289Z","etag":null,"topics":["json","php","php-library","php7","validation"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Voltra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-07T15:59:26.000Z","updated_at":"2022-02-12T09:16:21.000Z","dependencies_parsed_at":"2022-11-02T22:01:08.886Z","dependency_job_id":null,"html_url":"https://github.com/Voltra/yavlphp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2Fyavlphp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2Fyavlphp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2Fyavlphp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2Fyavlphp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Voltra","download_url":"https://codeload.github.com/Voltra/yavlphp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242076048,"owners_count":20068231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","php","php-library","php7","validation"],"created_at":"2024-11-15T17:39:08.445Z","updated_at":"2026-04-19T11:35:38.499Z","avatar_url":"https://github.com/Voltra.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# What is yavlphp ?\n\nThe PHP implementation of [yavljs](https://www.npmjs.com/package/yavljs) that allows you to use the same definitions for front-end and back-end validation.\n\n\n\n\n\n# Table of content\n\n[TOC]\n\n# Why YavlJS for PHP ?\n\n[yavljs](https://www.npmjs.com/package/yavljs) is a javascript library for front-end form validation. Sadly, front-end validation is merely for the user's experience : a developer should **NEVER** rely on it for the complete validation of the submitted data.\n\nTherefore, I decided to develop its equivalent in PHP.\n\nMy goal was that you could both validate on the front-end and back-end part of your application, all that using the same files.\n\n\n\n# What are the key differences with YavlJS ?\n\nThere's only one difference, the **field's name** .\n\nWhere using [yavljs](https://www.npmjs.com/package/yavljs) you could simply give names for the sake of semantic, in [yavlphp](https://packagist.org/packages/voltra/yavlphp) things are different, let's illustrate this with an example:\n\n```html\n\u003cform id=\"form\"\u003e\n  \u003cinput type=\"text\" name=\"field1\"/\u003e\n  \u003cinput type=\"text\" name=\"field2\"/\u003e\n  \u003cinput type=\"text\" name=\"field3\"/\u003e\n  \n  \u003cbutton type=\"submit\"\u003e\n    Submit\n  \u003c/button\u003e\n\u003c/form\u003e\n```\n\n## With yavljs\n\n```json\n{\n  \"form\": \"#form\",\n  \"fields\": {\n    \"first field\": {\n      \"selector\": \"[name='field1']\",\n      \"error_selector\": \"*\",\n      \"required\": true,\n      \"type\": \"int\",\n      \"rules\": {\n        \"min\": 3,\n      \t\"max\": 6\n      }\n    },\n    \"second field\": {\n      \"selector\": \"[name='field2']\",\n      \"error_selector\": \"*\",\n      \"required\": true,\n      \"type\": \"int\",\n      \"rules\": {\n        \"min\": 8,\n      \t\"max\": 12\n      }\n    },\n    \"third field\": {\n      \"selector\": \"[name='field3']\",\n      \"error_selector\": \"*\",\n      \"required\": true,\n      \"type\": \"int\",\n      \"rules\": {\n        \"min\": 24,\n      \t\"max\": 32\n      }\n    },\n  }\n}\n```\n\n## With yavlphp\n\n```json\n{\n  \"form\": \"#form\",\n  \"fields\": {\n    \"field1\": {\n      \"selector\": \"[name='field1']\",\n      \"error_selector\": \"*\",\n      \"required\": true,\n      \"type\": \"int\",\n      \"rules\": {\n        \"min\": 3,\n      \t\"max\": 6\n      }\n    },\n    \"field2\": {\n      \"selector\": \"[name='field2']\",\n      \"error_selector\": \"*\",\n      \"required\": true,\n      \"type\": \"int\",\n      \"rules\": {\n        \"min\": 8,\n      \t\"max\": 12\n      }\n    },\n    \"field3\": {\n      \"selector\": \"[name='field3']\",\n      \"error_selector\": \"*\",\n      \"required\": true,\n      \"type\": \"int\",\n      \"rules\": {\n        \"min\": 24,\n      \t\"max\": 32\n      }\n    },\n  }\n}\n```\n\n\n\nAs you can see, the names that were only used for semantic are now required to be the field's name.\n\nThis is due to the fact that the vast majority of use cases will use the request's variable to validate the form.\n\nOther than this, there are no differences in how the validation process is executed.\n\n\n\n# How to install yavlphp ?\n\nI highly recommend you to use [composer](https://getcomposer.org/) if you are not using it already, it is a very handy PHP package manager.\n\nWith composer installed, simply run the following command in your application's folder:\n\n`composer require voltra/yavlphp`\n\nThis will automatically install [yavlphp](https://packagist.org/packages/voltra/yavlphp) and its dependencies (if there are any).\n\n\n\n# How to use yavlphp ?\n\n## The instance of the validator\n\nThis is very simple, you will use an instance of `YavlPhp\\Yavl`. You can either create it directly from a `YavlPhp\\Components\\YavlFieldsMap` and a `YavlPhp\\Components\\YavlLocaleMap` .\n\n```php\nuse YavlPhp\\Yavl;\nuse YavlPhp\\Components\\YavlFieldsMap;\nuse YavlPhp\\Components\\YavlLocaleMap;\n\n$validationSettings = new YavlFieldsMap(/* check the documentations for parameters */);\n$errorMessages = new YavlLocaleMap(/* check the documentations for parameters */);\n\n$v = new Yavl($validationSettings, $errorMessages);\n```\n\n\n\nOr you can directly skip those steps and use your JSON files instead :\n\n```php\nuse YavlPhp\\Yavl;\n\nfunction getUrlFromServerRoot(string $path) : string{}\n\n$v = Yavl::fromJson(\n\tgetUrlFromServerRoot(\"assets/json/formx/form.json\"),\n  \tgetUrlFromServerRoot(\"assets/json/formx/locale.json\")\n);\n```\n\n**Sidenote :** Both `Yavl\\Php\\Components\\YavlLocaleMap` and a path to the locale file are optionnal, they are defaulted (but it is highly recommended to give one).\n\n## Actually validating the data\n\nNow that you have youre `Yavl` instance ready to use, you will use its method `validate` which can take an argument : the associative array of data, the association being `fieldName =\u003e fieldValue`.\n\nNote that if you don't provide this argument, it'll try to get the arguments itself from either `$_GET` or `$_POST` (will go for `$_GET` if the method is GET, will go for `$_POST` if it is not GET).\n\n\n\n```php\n$errors = $v-\u003evalidate();\n\n$errors = $v-\u003evalidate($formFieldsAssociativeArray);\n```\n\nThe validation is then being processed and errors are reported in the return value of the method.\n\nThe `validate` method returns an associative array that associates an error message to the field's name :\n\nWhen a validation rule is not respected (required, regex, etc...) it will set the corresponding error message and go on with the other fields.\n\n\n\nTherefore, if there were no validation error (meaning that the data passed is completely validated) then you would have an empty array as a result.\n\n## Handling errors\n\nLet's say that you have the following form:\n\n```html\n\u003cform\u003e\n  \u003cinput type=\"text\" name=\"username\"/\u003e\n  \u003cinput type=\"text\" name=\"password\"/\u003e\n  \u003cbutton type=\"submit\"\u003eSubmit\u003c/button\u003e\n\u003c/form\u003e\n```\n\nYou can handle errors like so :\n\n```php\n$errors = $v-\u003evalidate;\nif(!empty( $errorss )){\n  rediret_to_form_with_errors(\"some/url/to/the/form\", $errors);\n  //This is not an actual function ;)\n}else{\n  //go on with your correct data !\n}\n```\n\n\n\n# How to extend yavlphp (plugins) ?\n\n## Creating the plugin\n\nThis is very simple, a validation rule/function is an object of a class that inherits from `YavlPhp\\Components\\YavlValidationFunction` which has two methods that you need to override :\n\n* `call` \u0026rarr; The method that checks whether or not the data is valid\n* `getNameForJson` \u0026rarr; The method that returns the name of this rule as it should be in the JSON file\n\n\n\nHere are their signatures:\n\n```php\nabstract function call(YavlLocaleMap $locale, $value, $expected, array $fieldsValues) : ?string;\n\nabstract function getNameForJson() : string;\n```\n\nNote that, if the data (`$value`) is valid, then `call` would return `null`, otherwise it would return the corresponding error message from `$locale`.\n\n\n\nFor instance, let's take a look at `YavlPhp\\Rules\\YavlMaxLength` which is the validation function for the `maxLength` rule (in the JSON file):\n\n```php\nfinal class YavlMaxLength extends YavlValidationFunction {\n\n    public function call(\n      YavlLocaleMap $locale,\n      $value,\n      $expected,\n      array $fieldsValues\n    ): ?string {\n      //$expected is the value given in the JSON file for this rule\n      //$value is the field's value\n        return (strlen(\"{$value}\") \u003c= intval($expected))\n          ? null //It is less than or equal to the maximum value, so return null\n          : $locale-\u003eget($this-\u003egetNameForJson()); //It is not, fetch the error message\n    }\n\n    public function getNameForJson(): string {\n        return \"maxLength\";\n    }\n}\n```\n\nIf your error message needs any kind of manipulation (for instance, replacing `%input%` by the `$value` variable) you can use either `preg_replace` or `str_replace`.\n\nNote that `%value%` is always replaced with the value of `$expected`, unless you replace it first.\n\n\n\n## Adding the plugin to the validator\n\nOnce you have your plugin class ready, you can totally add it to your validator using its method `registerPlugin`:\n\n```php\n$v = /*get a Yavl instance*/;\n$v-\u003eregisterPlugin(new AwesomeYavlPlugin());\n```\n\nIt will deduce the name (`getNameForJson`) automatically. Be aware that doing so, you might override someone else's plugin so be careful.\n\n\n\n## Removing a plugin\n\nIf by any chance you wanted to remove a plugin, you can do so by using your validator's method `removePlugin`.\n\nThis method takes as an argument the name of your plugin (cf. the  `getNameForJson` method).\n\n\n\n## Get a list of the defined plugins\n\nYou can also get a list of the defined plugins, this might be useful if you have to determine a new name for you plugin (if your initial one was already in use).\n\nTo do so, you need to call your validator's method `getPluginNamesList` which returns the names of all the plugins (cf. the `getNameforJson`method).\n\n\n\n# In need of extra information ?\n\nTo refer to how [yavlphp]() works, please refer to this [page](https://www.npmjs.com/package/yavljs) (yavljs on npm).\n\n\n\nTo test your plugins with PHPUnit, you can inherit from `YavlPhp\\Tests\\Components\\YavlFunctionTest_Abstract`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltra%2Fyavlphp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoltra%2Fyavlphp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltra%2Fyavlphp/lists"}