Download the PHP package 3nr1c/structure without Composer

Structure

Structure provides a set of classes to check the data type and format of your variables.

Table of Contents

License
Installation
Introduction
Documentation
Static shortcuts
Class ScalarS
Class NumericS
Classes IntegerS and FloatS
Class StringS
Class ArrayS
Working with Value Sets
Further info
Changelog
Planned features

License

Structure is provided under the MIT License.

Installation

You can install Structure into your project using Composer. Using the latest release is highly recommendable. You can start using it by adding the following to your composer.json:

You can also use the version at your own risk. The code in this version may change at any time.

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:

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:

Here are some more examples:

Documentation

All Structure classes have the same constructor:

The $null argument allows the data to be null when running the method. All classes have also the following methods:

The argument of 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 and . The possible values for this failure variables are specified in their section below.

Static shortcuts

The main Structure class provides four static methods to quickly generate checkers:

All these methods return respectively an ArrayS, NumericS, IntegerS, FloatS or StringS object, with the properties set as passed by the arguments.

Class ScalarS

This class runs the test to a variable. If the result is , the var will show the type of the tested variable.

Usage:

This class and all its children have the 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 :

and tokens evaluate to booleans If you need the strings "true" and "false", escape them

If the tested variable is scalar but isn't in the defined set, the var will be .

Class NumericS

This class runs the test against a variable. A range property can be defined, with the following syntax:

That is, it uses the mathematical notation:

• 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 is used to indicate infinities. It has limitations: the left value can only be , and the right value either or .

The parser will raise an if the syntax is not correct. Here are a couple of examples:

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 variable will have the value .

Classes IntegerS and FloatS

They both inherit from . The only difference is that the check method of IntegerS uses
(is stricter), and uses . Notice this:

As you can see in the examples above, and are strict regarding s of numbers. You can use the attribute (set to by default) to avoid this strictness:

If the type of the tested variable is correct, but the range isn't, the variable will be either or .

Class StringS

This class runs the test against a variable.

Usage:

Min and max length can be required using :

If the test data is a string but does not match the length, the var will have the value .

Class ArrayS

This class has the following methods (plus all the methods inherited from ):

setFormat

The $format argument can have many forms. The type must always be or . The string type is used to define simple arrays, such as

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:

Types can be mixed using the vertical bar :

And the token can be "nested", to define multidimensional arrays

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.

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 command.

As you can see, it has a recursive definition.

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.

This feature is available for all Structure types. When (, , , , and ) is inherited a method is available.

When working with arrays, the Value Set information can be embedded within the format declaration.

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:

Further info

You can read more documentation by running (phpdoc needed) and by looking at the test cases.

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 can be used in place of the 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 methods accept as second argument a variable to be created to return what failed, if the test evaluates to . The last occurred error can be retrieved with and removed with
• ArrayS: quantifiers for simple array description: , ,
• ArrayS: multiple types for a value: ,
• ArrayS: mixed simple arrays:
• ArrayS: nested simple arrays: ,
• ScalarS: and tokens can be escaped to become strings:
• StringS: length test. It can be defined with . For arrays, the syntax is

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