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.

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

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.

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

$property->setStorage(AbstractStorage $storage)

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

$property->getStorage(): AbstractStorage

Returns the current set storage for this property.

commit() and rollback()

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

$property->commit()

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

$propery->rollback()

revoke the changes made to the value of this property

Name of property

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

$property->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 ()

$property->name(string $name)

Is an alias to ->setName();

$property->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.

$property->getName()

Returns the name of the property.

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

$property->setOwner(AbstractProperty: $owner): AbstractProperty

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

$property->getOwner(): ?AbstractProperty

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

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

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.

Writing own property classes

For more informations about reading own property classes see here.