PHPackages 3nr1c/structure - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Validation & Sanitization](/categories/validation) 4. / 5. 3nr1c/structure ActiveLibrary[Validation & Sanitization](/categories/validation) 3nr1c/structure =============== Structure provides a set of classes to check the data type and format of your variables. 0.5.2(10y ago)32.8k2MITPHPPHP >=5.4.0 Since Jul 13Pushed 9y ago3 watchersCompare [ Source](https://github.com/3nr1c/structure)[ Packagist](https://packagist.org/packages/3nr1c/structure)[ RSS](/packages/3nr1c-structure/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (1)Versions (14)Used By (0) Structure [![Build Status](https://camo.githubusercontent.com/5935cb575362dbac21d9e601385f6608c03625b67029da7d6cc695f7da794664/68747470733a2f2f7472617669732d63692e6f72672f336e7231632f7374727563747572652e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/3nr1c/structure) ====================================================================================================================================================================================================================================================================================== [](#structure-) **Structure** provides a set of classes to check the data type and format of your variables. Table of Contents ----------------- [](#table-of-contents) **[License](#license)** **[Installation](#installation)** **[Introduction](#introduction)** **[Documentation](#documentation)** **[Static shortcuts](#static-shortcuts)** **[Class ScalarS](#class-scalars)** **[Class NumericS](#class-numerics)** **[Classes IntegerS and FloatS](#classes-integers-and-floats)** **[Class StringS](#class-strings)** **[Class ArrayS](#class-arrays)** **[Working with Value Sets](#working-with-value-sets)** **[Further info](#further-info)** **[Changelog](#changelog)** **[Planned features](#planned-features)** License ------- [](#license) **Structure** is provided under the [MIT License](https://raw.githubusercontent.com/3nr1c/structure/master/LICENSE). Installation ------------ [](#installation) You can install Structure into your project using [Composer](http://getcomposer.org). Using the latest release is highly recommendable. You can start using it by adding the following to your **composer.json**: ``` "require":{ "3nr1c/structure": "0.*" } ``` You can also use the `"dev-master"` version at your own risk. The code in this version may change at any time. Introduction ============ [](#introduction) Have you ever had to check the structure of some variable? (maybe it's an array that must have certain keys and value types, or an integer that must be within a certain range). If so, you probably have written some code like this: ``` if (!is_array($c)) { throw new \Exception(); } else if (!isset($c["profile"])) { throw new \Exception(); } else if (!is_array($c["profile"])) { throw new \Exception(); } //... ``` And that's only the beginning! I suppose that for each key, you also have to check for other keys, and data types. **Structure** helps you with these issues. The previous code becomes: ``` $arrayCheck = new \Structure\ArrayS(); $arrayCheck->setFormat(array("profile" => "array"); if (!$arrayCheck->check($c)) { throw new \Exception(); } //... ``` Here are some more examples: ``` $arrayCheck = new \Structure\ArrayS(); $arrayCheck->setFormat(array( "id" => "int", "rating" => "float[0,10]", "title" => array( "en" => "str", "es" => "str" ), "links" => "string[]", "subtitles" => "bool" )); ``` ``` $arrayCheck = new \Structure\ArrayS(); $arrayCheck->setFormat(array( "name" => "string", "customer_id" => "int", "is_admin" => "bool", "last_session" => "string" )); ``` Documentation ============= [](#documentation) All **Structure** classes have the same constructor: ``` public function __construct($data = null, $null = false); ``` The $null argument allows the data to be null when running the `check` method. All classes have also the following methods: ``` public function setData($data); public function getData(); // to avoid the data to be null: public function setNull($null); public function getNull(); // to check everything (type and range/format) public function check($data = null, &$failed = null); // to format things (specially powerfull in ArrayS) public function format($data = null); public static function getLastFail(); public static function clearLastFail(); ``` The `&$failed` argument of `check` lets you create a variable that will tell you why this method returned false. You can access to the last error information, and erase it, with the static methods `getLastFail` and `clearLastFail`. The possible values for this failure variables are specified in their section below. Static shortcuts ---------------- [](#static-shortcuts) The main Structure class provides four static methods to quickly generate checkers: ``` public static function ArrayS($format = null, $data = null, $countStrict = true, $null = false); public static function NumericS($range = null, $data = null, $null = false); public static function IntegerS($range = null, $data = null, $null = false); public static function FloatS($range = null, $data = null, $null = false); public static function StringS($data = null, $null = false); ``` All these methods return respectively an ArrayS, NumericS, IntegerS, FloatS or StringS object, with the properties set as passed by the arguments. Class ScalarS ------------- [](#class-scalars) This class runs the `is_scalar()` test to a variable. If the result is `false`, the `$failed` var will show the type of the tested variable. Usage: ``` $scalar = new \Structure\ScalarS(); if (!$scalar->check($var, $failed)) { print "Error: expected _scalar_, got " . $failed; } ``` This class and all its children have the `setValueSet` method, which lets you define possible values for the data to be checked. This method can take either a variable number of arguments, or a string with values separated by commas between curly brackets `{` and `}`: ``` $scalar->setFormat("value1", "value2", 10, 11, 12); // or $scalar->setFormat("{value1, value2, 10, 11, 12, commas and brackets can be escaped: \{\,}"); ``` `true` and `false` tokens evaluate to booleans If you need the strings "true" and "false", escape them ``` $scalar->setFormat("{true, false}"); $scalar->check(true); //true $scalar->check(false); //true $scalar->check("true"); //false $scalar->check("false"); //false $scalar->setFormat("{\\true, \\false}"); $scalar->check(true); //false $scalar->check(false); //false $scalar->check("true"); //true $scalar->check("false"); //true ``` If the tested variable is scalar but isn't in the defined set, the `$failed` var will be `"scalar:value"`. Class NumericS -------------- [](#class-numerics) This class runs the `is_numeric()` test against a variable. A range property can be defined, with the following syntax: ``` /^\s*[\(\[]\s*(-?\d+(\.\d+)?|-inf)\s*,\s*(-?\d+(\.\d+)?|\+?inf)\s*[\)\]]\s*$/ ``` That is, it uses the [mathematical notation](https://en.wikipedia.org/wiki/Interval_(mathematics)#Including_or_excluding_endpoints): - The '(' character indicates a strict (<) lower bound - The '\[' character indicates a non-strict (<=) lower bound - The ')' character indicates a strict (>) upper bound - The '\]' character indicates a non-strict (>=) upper bound The term `inf` is used to indicate infinities. It has limitations: the left value can only be `-inf`, and the right value either `inf` or `+inf`. The parser will raise an `\Exception` if the syntax is not correct. Here are a couple of examples: ``` $numeric = new \Structure\NumericS(); $numeric->setRange("(-2,5]"); $numeric->check(-4.2);// false $numeric->check(-2);// false $numeric->check(0.33);// true $numeric->check(3);// true $numeric->check(5);// true $numeric->check(10.42);// false ``` The left number must be *less than or equal to* the right number. If the type of the tested variable is correct, but the range isn't, the `$failed` variable will have the value `"numeric:range"`. Classes IntegerS and FloatS --------------------------- [](#classes-integers-and-floats) They both inherit from `NumericS`. The only difference is that the **check** method of IntegerS uses `is_integer`(is stricter), and `FloatS` uses `is_float`. Notice this: ``` $numeric = new \Structure\NumericS(); $numeric->check("3.2");// true $numeric->check("5");// true $float = new \Structure\FloatS(); $float->check("3.2");// false $integer = new \Structure\IntegerS(); $integer->check("5");// false ``` As you can see in the examples above, `FloatS` and `IntegerS` are strict regarding `string`s of numbers. You can use the attribute `$numeric` (set to `false` by default) to avoid this strictness: ``` $float = new \Structure\FloatS(); $integer = new \Structure\IntegerS(); $float->setNumeric(true); $integer->setNumeric(true); $float->check("3.2");// true $integer->check("5");// true ``` If the type of the tested variable is correct, but the range isn't, the `$failed` variable will be either `"integer:range"` or `"float:range"`. Class StringS ------------- [](#class-strings) This class runs the `is_string()` test against a variable. Usage: ``` $string = new \Structure\StringS(); $string->check($var); ``` Min and max length can be required using `setLength`: ``` $string->setLength(4); // 4 characters or more $string->setLength(4, 10); // 4 to 10 characters $string->setLength(0, 10); // up to 10 characters $string->setLength("(4..10)"); // 4 to 10 characters ``` If the test data is a string but does not match the length, the `$fail` var will have the value `"string:length"`. Class ArrayS ------------ [](#class-arrays) This class has the following methods (plus all the methods inherited from `Structure`): ``` public function setFormat($format); public function getFormat(); public function setCountStrict(); public function isCountStrict(); public static function isAssociative($data); ``` ### setFormat [](#setformat) The $format argument can have many forms. The type must always be `array` or `string`. The string type is used to define simple arrays, such as ``` $array->setFormat("int[]"); $array->setFormat("int[10]"); $array->setFormat("bool[]"); $array->setFormat("MyClass[3]"); ``` The characters `+` and `*` can also be used to test simple arrays. Something like "\[3..5\]" can be used to express variable array size. The following expressions are valid: ``` $array->setFormat("string[*]"); // checks for 0 or more strings $array->setFormat("integer[+]"); // checks for 1 or more integers $array->setFormat("scalar[5+]"); // checks for 5 or more scalars $array->setFormat("float[3..5]"); // checks for 3 to 5 floats $array->setFormat("float[..5]"); // checks for a maximum of 5 floats $array->setFormat("float[3..]"); // checks for at least 3 floats ``` Types can be mixed using the vertical bar `|`: ``` $array->setFormat("(string|int|bool)[4+]"); $array->setFormat("(float|null)[]"); ``` And the token `[]` can be "nested", to define multidimensional arrays ``` $array->setFormat("integer[][]"); $array->setFormat("(integer[]|float[])[]"); // Beware of dimensions. This: $array->setFormat("integer[2][3]"); // Would check true with this: $array->check(array( array(1, 2), array(3, 4), array(5, 6) )); // true // this: $array->setFormat("integer|float[]"); // is different from: $array->setFormat("(integer|float)[]"); ``` The array type is used to represent more complex array structures. If you expect an array to be sequential (i.e., not key-value), the format should be an array of types. Again, if all array elements have to be of the same type, the syntax above is recommended. ``` $array->setFormat(array("integer", "string", "array")); $array->setFormat(array( "int", "string", array("bool", "int", "float"), "numeric[]", "string(8..10)" ); ``` Finally, you can define required keys for an associative array. Warning: if the array has some keys you do not want to check, make sure you run the `$array->setCountStrict(false)` command. ``` $array->setFormat(array( "foo" => "string", "foo2" => "string{hello, bye}[]", "bar" => "int[3,10)", "bar2" => "int[3,10)[4+]", "abc" => "array", "xyz" => array( "integer[]", "string(..5)[]", array( "hello" => "bool" ) ) )); ``` As you can see, it has a recursive definition. Working with Value Sets ----------------------- [](#working-with-value-sets) Sometimes you want to check if a variable has a value that you know. Let's imagine that we want to check if a number is 3 or 7. It's not possible using the mathematical notation supported by Structure (we'd need to use unions and intersections of mathematical entities). Value Sets in Structure provide this feature. ``` $numeric = new \Structure\NumericS(); $numeric->setValueSet(3, 7); $numeric->check(3); //true $numeric->check(7); //true $numeric->check(542); //false // Less efficient, but valid (and needed for ArrayS): // $numeric->setValueSet("{3,7}"); ``` This feature is available for all Structure types. When `ScalarS` (`StringS`, `NumericS`, `IntegerS`, `FloatS`, and `BooleanS`) is inherited a `setValueSet()` method is available. When working with arrays, the Value Set information can be embedded within the format declaration. ``` $format = array( "string{a,b,c}", "integer{2, 4, 6}" ); $array = \Structure\Structure::ArrayS($format); $arrayA = array("a", 2); $arrayB = array("a", 6); $arrayC = array("c", 2); $arrayD = array("f", 2); $array->check($arrayA); //correct $array->check($arrayB); //correct $array->check($arrayC); //correct $array->check($arrayD); //incorrect ``` This feature can also be used to check whether a variable matches a single value, which can be quite useful in an array context. For example, you could check bools, or integers: ``` $format = array( "logged" => "bool{true}", "status" => "integer{0}" ); $array = \Structure\Structure::ArrayS($format); $test1 = array("logged" => true, "status" => 0); $test2 = array("logged" => true, "status" => 1); //the status indicates some error code here $array->check($test1);//true $array->check($test2);//false ``` Further info ============ [](#further-info) You can read more documentation by running `composer doc` (phpdoc needed) and by looking at the test cases. Changelog ========= [](#changelog) **0.6.0** - ArrayS: arrays can be of variable length! "integer\[1..5\]", "string\[..4\]", "numeric\[3..\]" - ArrayS: format can be defined with a JSON string - ArrayS: format can be defined with a path to a file containing a format in JSON - ArrayS: fixed a bug with formats of the type "null|string\[\]" - ArrayS: literal `null` can be used in place of the `"null"` string - ArrayS: an array item can be "(string{a,b,c}|integer\[3,10\])\[\]" - ArrayS: "string\[3\]" can now be used to describe an associative array - Structure::typeof is now a public method **0.5.0** - Compilation of strings for ArrayS, ScalarS (value sets) and NumericS (integer ranges) to avoid re-parsing - Failure reporting: all `check` methods accept as second argument a variable to be created to return what failed, if the test evaluates to `false`. The last occurred error can be retrieved with `Structure::getLastFail()` and removed with `Structure::clearLastFail()` - ArrayS: quantifiers for simple array description: `"type[*]"`, `"type[+]"`, `"type[10+]"` - ArrayS: multiple types for a value: `"integer|float"`, `"string|null"` - ArrayS: mixed simple arrays: `"(integer|float)[]"` - ArrayS: nested simple arrays: `"integer[][]"`, `"(integer[]|string[])[]"` - ScalarS: `true` and `false` tokens can be escaped to become strings: `"{\\true, \\false}"` - StringS: length test. It can be defined with `setLength`. For arrays, the syntax is `"string(min..max)"` Planned features ================ [](#planned-features) - Date formats: timestamp, mysql date/time/datetime, standard times - Email, ip, hash formats - Objects: attributes (name, visibility) and methods (name, visibility, parameters) - Regexp for strings - ArrayS: mark some keys as optional ### Health Score 31 — LowBetter than 68% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity24 Limited adoption so far Community12 Small or concentrated contributor base Maturity55 Maturing project, gaining track record Bus Factor1 Top contributor holds 99.2% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~5 days Total 13 Last Release 3897d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/3c0b0a85842eb5ce5556f8ac0284d703f5eec4310a42bd1c7e40828d11fadce9?d=identicon)[3nr1c](/maintainers/3nr1c) --- Top Contributors [![3nr1c](https://avatars.githubusercontent.com/u/1206574?v=4)](https://github.com/3nr1c "3nr1c (131 commits)")[![ifrins](https://avatars.githubusercontent.com/u/757530?v=4)](https://github.com/ifrins "ifrins (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/3nr1c-structure/health.svg) ``` [![Health](https://phpackages.com/badges/3nr1c-structure/health.svg)](https://phpackages.com/packages/3nr1c-structure) ``` ### Alternatives [webmozart/assert Assertions to validate method input/output with nice error messages. 7.6k894.0M1.2k](/packages/webmozart-assert)[bensampo/laravel-enum Simple, extensible and powerful enumeration implementation for Laravel. 2.0k15.9M104](/packages/bensampo-laravel-enum)[swaggest/json-schema High definition PHP structures with JSON-schema based validation 48612.5M73](/packages/swaggest-json-schema)[stevebauman/purify An HTML Purifier / Sanitizer for Laravel 5325.6M19](/packages/stevebauman-purify)[ashallendesign/laravel-config-validator A package for validating your Laravel app's config. 217905.3k5](/packages/ashallendesign-laravel-config-validator)[crazybooot/base64-validation Laravel validators for base64 encoded files 1341.9M8](/packages/crazybooot-base64-validation) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)