spunQ_Type Class Reference

Objects of this class describe types. More...

Inheritance diagram for spunQ_Type:

List of all members.

Public Member Functions

__construct ()

Constructor.

getName ()

Gets the name of this type.

getDocumentation ()

Gets the documentation for this type.

getOptions ()

Gets the type options for this type.

check ($value, spunQ_Map $options=NULL, $throwException=true)

Checks if a value is of the type described by this object.

__call ($functionName, $arguments)

Overloaded to provide automatic getters and setters.

__sleep ()

Replaces $_type with the type's name.

_verifyMembers ($omittedMembers=array(), $throwException=true)

Verifies that all members are valid.

_getMember ($name)

Gets the value of a member of this object.

_setMember ($name, $value)

Sets the value of a member of this object.

_getType ($throwException=true)

Gets the type of this object.

Static Public Member Functions

static stringDescribesType ($string)

Checks whether a string is a valid type descriptor.

static getByName ($string)

Will return a Type object with given description.

static getDescription ($value)

Returns the most appropriate textual representation of a value.

static getCommonDescription (array $values)

Finds the most suiting string description for multiple values.

static valueByProperty ($value, $path)

Transforms a value using a property path.

static propertyOfValue ($value, $property)

Gets a single property of a value.

Protected Member Functions

handleGetUntranslated ($memberName, $arguments, $functionName)

Needed by __call().

handleGet ($memberName, $arguments, $functionName)

Needed by __call().

initLocalizedMember ($memberName)

Makes sure a localized member contains a spunQ_Map.

handleGetFromArray ($memberName, $arguments, $functionName)

Needed by __call().

handleSet ($memberName, $arguments, $functionName)

Needed by __call().

handleAdd ($memberName, $arguments, $functionName)

Needed by __call().

handleRemove ($memberName, $arguments, $functionName)

Needed by __call().

Protected Attributes

$name

The name of this type.

$documentation

Documentation of this type as extracted from its doc comments.

$options

Additional options for this member.

$_type

The actual type of this object.

Static Protected Attributes

static $typeInstance = NULL

The one instance of this class that will describe all other instances.

Static Private Attributes

static $nameToTypeCache = array()

Cache for getByName().

Detailed Description

Objects of this class describe types.

Types are needed in the spunQ framework for various reasons:

Enhanced security: Invalid access to members of types can be handled very early, failing fast on the case of an error.
Common convenience functions: The DataObject class can provide many functions to inherited classes, which automates some boilerplate code, like getters/setters.
Managed database administration: The framework can manage creation, adjustment and versioning of database schemata.
Web services: The spunQ framework will be expanded by networking modules, which will allow communication with other spunQ instances, which could even be written in other languages than PHP. Any communication needs predefined types for acceptable communication speeds.

There are some predefined basic types, which can be combined and adjusted to form custom types in the framework. The basic types are:

integer: Natural numbers and ther negatives. Min and max values are -(2^(31-1)) and 2^(31-1), if not constricted by options (see below).
real: Real numbers to be expressed as an IEEE 754-2008 floating point number with 64 bits.
string: An array of characters of arbitrary length. The length of a string is expresssed as the amount of UTF-8 encoded characters in it and is thus variable-length itself (30 chars do not necessaraly mean 30 bytes).
array: An array of other types. The array is a parameterized type, and must always describe the type it can store, too. The syntax is based on Java's an C++'s syntax with generics: array<integer> could be the format to store the contents of a file in.
map: The map is an unsorted data structure mapping objects of one type to another. Since PHP itself does not provide an appropriate implementation for this data structure, a custom implementation has been added to the core.util package. Map types have two parameters, one for the type of the keys and one for the values mapped by the keys. map<string,array<integer>> could be a mapping of file names to file contents, for example.
date: A date/time definition.

Other types can be assembled using these basic building blocks to create so-called user types. User types consist of members, which in turn have a name, a type and certain options. Options are intended to pose further constraints on the types the member can hold. The maximum value of an int, or the list of allowed characters in a string are examples for type options.
User types are extracted implicitly from source files that need to adhere to some standards:

Every type has a name, which includes a module definition, just like packages in Java or namespaces in C++. Dots are used as separator characters to delimit modules. The name of the class must be identical with the name of the type (deprived of any modules). If the type is to be named forum.rights.User, the class must be named User. There is an exception to this rule to prevent name collisions with other classes. The class name may be prefixed with any level of module names of the type, delimited by underscores. The same forum.rights.User type may be defined with the class forum_User or forum_rights_User.
The class file must be in a folder hierarchy that resembles its module name. The available top level modules are to be defined in the spunQ configuration file (see spunQ::init()). The according configuration multi-key is spunQ.modules. This means that the following setup would lead to the folder /tmp/forum becoming the root of the forum module: spunQ.modules.folder = /tmp/forum
The above type should be in the folder rights, which in turn should be in the folder that is defined as the module forum in the configuration. Taking the example above, the file would need to be in /tmp/forum/rights.
The file name itself must be identical to the name of the type, with the extension .type.php. The complete path for the above example would be /tmp/forum/rights/User.type.php.
Every member of the class is considered to be a member of the type, unless it has the tag @local in its doc comment. Those members having the said tag are completely ignored by the spunQ_ITypeParser. All others must have protected visibility and at least the tag @type containing the textual representation of the type of this member. The textual representation of basic types can be found in bold letters in the previous list. String represenations of user types consist of the name of the type as described above. Further options may be added to the doc comments of the member.

Examples for the above rules can be found in the source code of the spunQ framework itself (go ahead, have a look, it has pretty nice docs ;).
The following list contains possible options for certain member types:

integer:
- min: The minimum value of the member.
- max: The maximum value of the member.
real:
- min: The minimum value of the member.
- max: The maximum value of the member.
string:
- length.min: Minimum length of the string.
- length.max: Minimum length of the string.
array: See the options of maps. Arrays are handled identically to maps indexed with integers in this context. array<string> = map<integer,string>
set: Almost the same as array. Sets don't claim to be ordered.
map: This type itself does not have options of its own, but it prvides access to options of its keys/values with the prefix key and value accordingly. The type map<integer,string> could have the option @key.min or @key.max to limit the allowed range of values for the key.

   # Example class (doc comment malformatted for technical reasons)
   class User extends spunQ_DataObject {
 
     / **
       * The usernames this user can use to log in.
       * A user can have a maximum of 10 user names, the first one being his
       * preferred name.
       * @type array<string>
       * @key.min 1
       * @key.max 10
       * @value.length.min 3
       * @value.length.max 100
       * /
     protected $usernames;
 
     / **
       * Caches various things.
       * @local
       * /
     private $cache;
 
   }

Definition at line 283 of file Type.type.php.

Member Function Documentation

spunQ_DataObject::__call	(	$	functionName,
		$	arguments
	)			`[inherited]`

Overloaded to provide automatic getters and setters.

Parameters:

	$functionName	The function that was called.
	$arguments	Array containing the arguments that were passed to the function.

Exceptions:

spunQ_BadArgumentCountError

Definition at line 148 of file DataObject.type.php.

spunQ_DataObject::__sleep ( ) [inherited]

Replaces $_type with the type's name.

Returns:: array<string>

Reimplemented in spunQ_ArrayType, spunQ_MapType, and spunQ_SetType.

Definition at line 178 of file DataObject.type.php.

spunQ_DataObject::_getMember ( $ name ) [inherited]

Gets the value of a member of this object.

Will check if the object has a getter for the member and will use that method for getting the value. Otherwise, the value of the object member is returned.

Parameters:

$name

The name of the member.

Returns:: any Whatever type the member has.

Definition at line 478 of file DataObject.type.php.

spunQ_DataObject::_getType ( $ throwException = true ) [inherited]

Gets the type of this object.

Returns:: spunQ_Type

Definition at line 507 of file DataObject.type.php.

spunQ_DataObject::_setMember	(	$	name,
		$	value
	)			`[inherited]`

Sets the value of a member of this object.

Will check if the object has a setter for the member and will use that method for setting the value. Otherwise, the object member is set directly.

Parameters:

	$name	The name of the member.
	$value	The value to set it to.

Returns:: spunQ_DataObject $this

Definition at line 495 of file DataObject.type.php.

spunQ_DataObject::_verifyMembers	(	$	omittedMembers = `array()`,
		$	throwException = `true`
	)			`[inherited]`

Verifies that all members are valid.

This function is called from various modules prior to critical actions requiring a complete object - like inserting into a database.

Parameters:

	$omittedMembers	Do not perform checks on these member names.
	$throwException	Whether an exception should be thrown if a member does not have a valid value.

Returns:: boolean

Exceptions:

spunQ_IllegalValueException

Definition at line 458 of file DataObject.type.php.

spunQ_Type::check	(	$	value,
		spunQ_Map $	options = `NULL`,
		$	throwException = `true`
	)

Checks if a value is of the type described by this object.

Parameters:

	$value	The value to check
	$options	The type options to consider.
	$throwException	Whether an exception should be thrown if the type of the value differs.

Returns:: boolean Whether $value is of the type described by this object.

Exceptions:

spunQ_IllegalValueException

Reimplemented in spunQ_AnyType, spunQ_ArrayType, spunQ_BooleanType, spunQ_DateTimeType, spunQ_DateType, spunQ_MapType, spunQ_NumericType, spunQ_SetType, spunQ_StringType, spunQ_TimeType, and spunQ_UserType.

Definition at line 479 of file Type.type.php.

static spunQ_Type::getByName ( $ string ) [static]

Will return a Type object with given description.

Parameters:

$string

The string description fo the type.

Returns:: spunQ_Type

Reimplemented in spunQ_ArrayType, spunQ_MapType, spunQ_SetType, and spunQ_BuiltinType.

Definition at line 313 of file Type.type.php.

static spunQ_Type::getCommonDescription ( array $ values ) [static]

Finds the most suiting string description for multiple values.

Parameters:

$values

The values to find string description for.

Returns:: string

Definition at line 373 of file Type.type.php.

static spunQ_Type::getDescription ( $ value ) [static]

Returns the most appropriate textual representation of a value.

Can be used to provide useful information about a value when debugging:

spunQ.DataObjects will be translated using their type names.
spunQ.Type will be translated using their names.
Normal objects will be translated to their class names.
arrays and maps will have their parameter types found recursively, substituting 'any' for undefined types (map<string,any>).
any other type is translated using gettype()

Parameters:

$value

The value to describe as a string.

Returns:: string

Definition at line 343 of file Type.type.php.

spunQ_Type::getDocumentation ( )

Gets the documentation for this type.

Returns:: string

Definition at line 458 of file Type.type.php.

spunQ_Type::getName ( )

Gets the name of this type.

Returns:: string

Reimplemented in spunQ_ArrayType, spunQ_MapType, and spunQ_SetType.

Definition at line 450 of file Type.type.php.

spunQ_Type::getOptions ( )

Gets the type options for this type.

Returns:: map<string,array<string>>

Definition at line 466 of file Type.type.php.

spunQ_DataObject::handleAdd	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of function calls starting with 'add'.

Parameters:

	$memberName	The name of the member that is possibly being appended to. Merely the name of the function without the leading 'add', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The function that was called.

Returns:: spunQ_DataObject $this

Exceptions:

	spunQ_BadArgumentCountError
	spunQ_InvalidArgumentError

Reimplemented in spunQ_StorableObject.

Definition at line 327 of file DataObject.type.php.

spunQ_DataObject::handleGet	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of function calls starting with 'get'.

Todo:: spunQ_CollectionType instead of spunQ_ArrayType(?)

Parameters:

	$memberName	The name of the member that was possibly requested. Merely the name of the function without the leading 'get', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The name of the function that was called.

Returns:: any Whatever type the member has.

Reimplemented in spunQ_StorableObject.

Definition at line 217 of file DataObject.type.php.

spunQ_DataObject::handleGetFromArray	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of getter functions, where the member has an array type.

See also:: handleGet()

Parameters:

	$memberName	The name of the member that was possibly requested. Merely the name of the function without the leading 'set', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The function that was called.

Returns:: array

Reimplemented in spunQ_StorableObject.

Definition at line 264 of file DataObject.type.php.

spunQ_DataObject::handleGetUntranslated	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of functions requesting all translations available for a member.

Parameters:

	$memberName	The name of the member that was possibly requested.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The name of the function that was called.

Returns:: map<spunQ_Locale,any> Mapping locales to whatever type the member has. Note that not every locale needs to be present in this map.

Reimplemented in spunQ_StorableObject.

Definition at line 198 of file DataObject.type.php.

spunQ_DataObject::handleRemove	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of function calls starting with 'remove'.

Parameters:

	$memberName	The name of the member that is possibly being removed from. Merely the name of the function without the leading 'remove', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The function that was called.

Returns:: spunQ_DataObject $this

Exceptions:

	spunQ_BadArgumentCountError
	spunQ_InvalidArgumentError

Reimplemented in spunQ_StorableObject.

Definition at line 399 of file DataObject.type.php.

spunQ_DataObject::handleSet	(	$	memberName,
		$	arguments,
		$	functionName
	)			`[protected, inherited]`

Needed by __call().

Will take care of function calls starting with 'set'.

Parameters:

	$memberName	The name of the member that is possibly being set. Merely the name of the function without the leading 'set', with a lower-case first letter.
	$arguments	Array containing the arguments that were passed to the function.
	$functionName	The function that was called.

Returns:: spunQ_DataObject $this

Reimplemented in spunQ_StorableObject.

Definition at line 292 of file DataObject.type.php.

spunQ_DataObject::initLocalizedMember ( $ memberName ) [protected, inherited]

Makes sure a localized member contains a spunQ_Map.

Parameters:

$memberName The name of the member. This member must have the option 'localized'.

Returns:: void

Definition at line 245 of file DataObject.type.php.

static spunQ_DataObject::propertyOfValue	(	$	value,
		$	property
	)			`[static, inherited]`

Gets a single property of a value.

See also:: valueByProperty()

Parameters:

	$value	The value to fetch property for.
	$property	The property to fetch.

Returns:: any

Definition at line 74 of file DataObject.type.php.

static spunQ_Type::stringDescribesType ( $ string ) [static]

Checks whether a string is a valid type descriptor.

Parameters:

$string

The string to check

Returns:: boolean

Definition at line 298 of file Type.type.php.

static spunQ_DataObject::valueByProperty	(	$	value,
		$	path
	)			`[static, inherited]`

Transforms a value using a property path.

Some types are considered to have properties within spunQ. These properties can be referred to using property path definitions. The most simple case for properties is the user type, for which every member is considered a property. Concatenations of these paths with dots as separators are called property path. The list of all users in the primary group of a given user can be described using this method in a string: 'primaryGroup.users'.
Different types have different properties:

UserType: As already mentioned, every member of a user type is a property of an object of that type.
Map:
- _keys: An array of the keys of the map.
- _values: An array of the values of the map. Note that _keys and _values are guaranteed to return arrays where the index of a key matches the index of its value in the according result.
- _key: The first entry of the _keys property. This is handy for referencing the key of single key/value pairs.
- _value: The first entry of the _values property.
- _count: The amount of items in the map.
Array:
- _keys: The array of keys of the array. Note that the difference between arrays and maps in spunQ is that arrays are always numerically indexed! So this will always return an array containing a range of integers.
- _values: Array of values in this array. This essentially returns the array as-is and is a NOOP.
- _key: The first entry of the _keys property.
- _value: The first entry of the _values property.
- _count: The amount of items in the array.
String:
- _length: The length of the string.

Parameters:

	$value	The value to transform
	$path	The property path to use for the transformation. This can either be a string as described, or an array, each entry holding a property name.

Returns:: any The described value.

Todo:: refactor

Definition at line 54 of file DataObject.type.php.

Member Data Documentation

spunQ_DataObject::$_type [protected, inherited]

The actual type of this object.

Type:: spunQ.Type

Definition at line 129 of file DataObject.type.php.

spunQ_Type::$documentation [protected]

Documentation of this type as extracted from its doc comments.

Type:: string

Definition at line 434 of file Type.type.php.

spunQ_Type::$name [protected]

The name of this type.

Type:: string

Definition at line 428 of file Type.type.php.

spunQ_Type::$nameToTypeCache = array() [static, private]

Cache for getByName().

Type:: array

Definition at line 306 of file Type.type.php.

spunQ_Type::$options [protected]

Additional options for this member.

This map is extracted from the tags in the doc comment. The value is intentionally typed as array, since some options can have multiple values. A doc comment containing two author tags would result in a single entry with two values.

Type:: map<string,array<string>>

Definition at line 444 of file Type.type.php.

spunQ_Type::$typeInstance = NULL [static, protected]

The one instance of this class that will describe all other instances.

Any type describing a type has itself a type (which is spunQ.Type). That instance describing types is stored in this static variable.

Type:: spunQ_Type

Definition at line 291 of file Type.type.php.

The documentation for this class was generated from the following file:

Type.type.php


Public Member Functions
	__construct ()
	Constructor.
	getName ()
	Gets the name of this type.
	getDocumentation ()
	Gets the documentation for this type.
	getOptions ()
	Gets the type options for this type.
	check ($value, spunQ_Map $options=NULL, $throwException=true)
	Checks if a value is of the type described by this object.
	__call ($functionName, $arguments)
	Overloaded to provide automatic getters and setters.
	__sleep ()
	Replaces $_type with the type's name.
	_verifyMembers ($omittedMembers=array(), $throwException=true)
	Verifies that all members are valid.
	_getMember ($name)
	Gets the value of a member of this object.
	_setMember ($name, $value)
	Sets the value of a member of this object.
	_getType ($throwException=true)
	Gets the type of this object.
Static Public Member Functions
static	stringDescribesType ($string)
	Checks whether a string is a valid type descriptor.
static	getByName ($string)
	Will return a Type object with given description.
static	getDescription ($value)
	Returns the most appropriate textual representation of a value.
static	getCommonDescription (array $values)
	Finds the most suiting string description for multiple values.
static	valueByProperty ($value, $path)
	Transforms a value using a property path.
static	propertyOfValue ($value, $property)
	Gets a single property of a value.
Protected Member Functions
	handleGetUntranslated ($memberName, $arguments, $functionName)
	Needed by __call().
	handleGet ($memberName, $arguments, $functionName)
	Needed by __call().
	initLocalizedMember ($memberName)
	Makes sure a localized member contains a spunQ_Map.
	handleGetFromArray ($memberName, $arguments, $functionName)
	Needed by __call().
	handleSet ($memberName, $arguments, $functionName)
	Needed by __call().
	handleAdd ($memberName, $arguments, $functionName)
	Needed by __call().
	handleRemove ($memberName, $arguments, $functionName)
	Needed by __call().
Protected Attributes
	$name
	The name of this type.
	$documentation
	Documentation of this type as extracted from its doc comments.
	$options
	Additional options for this member.
	$_type
	The actual type of this object.
Static Protected Attributes
static	$typeInstance = NULL
	The one instance of this class that will describe all other instances.
Static Private Attributes
static	$nameToTypeCache = array()
	Cache for getByName().