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

$property->getValue():mixed

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

Calling this method initiates the algorithm as above.

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

$property->setValue(mixed $value)

The method to write a property's value

Calling this method initiates the algorithm as above.

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.

$property->readCapability(): ?string

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

$property->getReadCapability(): ?string

Is an alias for ->readCapability()

$property->setReadCapability(string $capability)

Sets the read capability for the 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.

=

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 of 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"

Writing own property classes

For more informations about reading own property classes see here.