Properties

A property is a logical piece of information. The property class capsulates everything that has to do with type, validation, semantic meaning and access rights. The data itself is retrieved and stored to a storage.

Every property needs exactly one storage. The linkage between property and storage can be done:

• internally by the property
• by calling the setStorage() method
• Using the property manager

The basic class of a property is AbstractProperty. Properties are managed via the property manager.

Reading a property value

A typical read process would be:

1. The property is called to return a value
2. The property checks if the current user is allowed to read the information (see here).
3. The property fetches the value from the connected storage
4. Optional it formats the output to a human readable form

getValue():mixed

The method to call to read a property's value.

Calling this method initiates the algorithm as above.

getHumanValue(): mixed

Returns the value of the property in a human readable format.

Example:

$duration->getValue()

returns 62

$duration->getHumanValue()

return 1 minute 2 seconds

Default value

When the storage responds that there is no value stored for this property it is possible to return a default value when reading this property or when a persistant storage tries to write an unitinitialized property.

setDefault(mixed $default): static

Sets the default value for this template. When null is passed the property will return null by default. This is a different behavior as setting no default value. In the latter case an exception would be raised when reading the value. {{Note|When setting null as a default value, the method nullable() is also called.

default(): static

Alias for setDefault()

getDefault(): mixed

Returns the default value. Warning: It returns null when there is no default value or when the default value is set to null. So check defaultsNull() too

defaultsNull(): boolean

Returns true, when the default value was set to null.

hasDefault(): boolean

Returns true, when the property has a default value at all.

Writing a property value

A typical write/modify process would be:

1. The property is called to write/modify a value
2. The property checks if the current user is allowed to write or modify the information
3. The property checks if the given value is valid for the type and semantic meaning of the property
4. The property passes the value to the storage

setValue(mixed $value)

The method to write a property's value

Calling this method initiates the algorithm as above.

isValid(mixed $input): bool

Checks if the given input is valid for this property.

nullable(bool $value = true): static

When null is passed as a value this is only possile, when this property if nullable. This methods marks it at nullable. Note: This also sets the default value to null

setNullable(bool $value = true): static

Alias to nullable(true)

notNullable(bool $value = true): static

Alias to nullable(false)

getNullable(): bool

Returns the current value of nullable.

Capabilities

You can assign any property a capability that is needed to read, write, modify or delete it. By default no capability is set. If one is set, the property needs a method to check if the current user has a certain capability. Due the fact that no user management system is forced a interface has to be created and given to the properties.

$property::setUserManager(string $user_manager)

is a static method that takes the name of a user manager (normally the namespace or facade name of laravel) that has to define a method called hasCapability(string $capabilty): bool that has to return true if the current user has the given capability.

The different capabilities

• read capability = Is needed to read a property
• write capability = Is needed to write a previously empty property
• modify capability = Is needed to modify a previously set property.
• delete capability = Is needed to delete a property

readCapability(): ?string

If empty or null this property does not need a certain capabilty.

getReadCapability(): ?string

Is an alias for ->readCapability()

setReadCapability(string $capability)

Sets the read capability for the property.

writeCapability(): ?string

If empty or null this property does not need a certain capabilty.

getWriteCapability(): ?string

Is an alias for ->writeCapability()

setWriteCapability(string $capability)

Sets the write capability for the property.

modifyCapability(): ?string

Returns the modify capability of this property.

getModifyCapability(): ?string

Alias for modify Capability.

setModifyCapability(string $capability): static

Sets the modify capability of this property.

readable/writeable

A property can be unreadable or unwriteable by default. Note: A unreadable or write-only property could be something like a reboot button that you can't read but you can "push" it.

isReadable(): bool

Returns if the current property is readable.

getReadable(): bool

Alias for isReadable()

setReadable(bool $readable = true): AbstractProperty

Sets the value for readable for this property.

isWriteable(): bool

Returns if the property is writeable.

getWriteable(): bool

Alias for isWriteable()

setWriteable(bool $writeable = true)

Sets the value for writeable for this property.

Storage interaction

Due the fact that every property needs a storage to handle the values there are these methods that handle the storage

setStorage(AbstractStorage $storage)

This method sets the active storage for this property. Normally this is done by the property manager.

getStorage(): AbstractStorage

Returns the current set storage for this property.

isValidStorage(AbstractStorage $storage): bool

Checks if the given storage is a valid one. By default this method returns true. Use this for properties that need a certain kind of storage (e.g. PersistentPoolStorage).

createStorage(): ?AbstractStorage

With this method it is possible for derrived properties to create a default storage.

commit() and rollback()

As users should not interact with storages the the following method are passed to the storage.

commit()

this methods is to make a change to the value of a property persistent

rollback()

revoke the changes made to the value of this property

isDirty(): bool

Returns true when an initialized value was changed or an uninitialized property was assigned a value.

Name of property

Every property should have a name. The name does not have necessarily be unique.

setName(string $name)

Sets the name of the property to the given name if it is a valid name. Inavlid names are:

• Names that start with an underscore _
• Reserved names like 'object', 'string' or 'id'
• Empty names ()

name(string $name)

Is an alias to ->setName();

forceName(string $name)

Skips the validation of the property name and should normally not be uses. It is uses internally for objects to define internal variables like _uuid.

getName()

Returns the name of the property.

isValidPropertyName(string $test)

Tests if the given name would pass the validation test.

Ownership of properties

A property can be owned by another property.This is useful in records and arrays but also for the InfoMarket. The statement

$propertyA->owner == $propertyB;

means that propertyA is a part of propertyB. Both can share the same storage or define a storage on their own.

setOwner(AbstractProperty: $owner): AbstractProperty

Sets the owner for this property. $owner must be a valid property.

getOwner(): ?AbstractProperty

Returns the current set owner (or null if no owner is set) of this property.

getPath(): string

This method is used for InfoMarket to identifiy a InfoMarket item. It combines the name of each owning property. Example:

"grandfather.father.son"

Metadata

Each property has some metadata that explains what kind of data it stores.

getSemantic(): string

Returns what semantic id this property has. See Semantics.

getSemanticKeywords(): array

Returns the semantic keywords of this property. See Semantics.

getUnit(): string

Returns the unit of this property. See Units.

getUpdate(): string

This is a hint for the caching of data. This returns how often this value should be updated or in other words is likely to change. See Caching.

getAccessType(): string

Returns a hint how the data is represented.

• string
• integer
• date
• datetime
• time
• float
• boolean
• array
• record
• blob

getMetadata()

Returns an associative array with all the above metadata as elements.

getStructure()

Returns either a stdClass() or an array of stdClass-es with the structure of the property or the included properties. This is needed for the underlying storage to do its job (sometimes)

InfoMarket interaction

All properties could be integrated into the Info market.

requestItem(array $path)

Returns the item that fits to the given path elements.

Information

Every property can hold some additional information items that can be used for information passing.

These information are bound to the property not the object so all the following methods are static.

getInfo(string $key, $default = null)

Returns the information with the name $key. If this information is not stored return the value of $default if not null.

getAllInfos()

Returns all informations that are stored to this property.

hasInfo(string $key): bool

Returns if the property has a information atom with this name.

Other basic property types

There are some other predefined property types (besides the Types and Semantics) that can be used as a base for own properties.

• Simple properties
• Array properties
• Record properties
• Storable record properties
• Pooled record properties
• Objects
• Collections
• Reference properties

Writing own property classes

For more informations about reading own property classes see here.