Properties

Properties and property files

The stubbles\lang\Properties class provides a convenient way to read property files and make their values accessible. Properties can both be read from a string you might have in memory or from a file:

$properties = Properties::fromString($propertyString);
$properties = Properties::fromFile('path/to/properties.ini');

Since release 3.1.0 one can also use the following functions:

$properties = stubbles\lang\parseProperties($propertyString);
$properties = stubbles\lang\parsePropertiesFile('path/to/properties.ini');

Properties consist of sections, which each has a list of key-value pairs. Suppose the following properties file:

[config]
cool.stuff = "Roland TB 303"
interesting = "Pink fluffy unicorns dancing on rainbows"

[other]
the.answer = 42
github = true

Here, the properties consists of the sections config and other, where both have different key-value pairs, cool.stuff and interesting belong to config and the other two to other.

You can get the raw value of a property:

$answer = $properties->getValue('other', 'the.answer'); // $answer now has the value "42" of type string

However, that might not be what you wanted to achieve. Rather, you would like to have a correct type. That's where the parse*() methods come into play:

$answer = $properties->parseInt('other', 'the.answer'); // $answer now has the value 42 of type int

Parsing methods

parseInt($section, $key, $default = 0)

Tries to read the value and convert it to int. If the section or key is not set, return value is $default.

parseFloat($section, $key, $default = 0.0)

Tries to read the value and convert it to float. If the section or key is not set, return value is $default.

parseBool($section, $key, $default = false)

Tries to read the value and convert it to boolean. If the section or key is not set, return value is $default.

The following value contents will be converted to true:

• 1 (only for releases < 4.1.0, starting with 4.1.0 using 1 as true is not supported any more)
• yes
• true
• on

All other values will evaluate to false.

parseArray($section, $key, array $default = null)

Tries to read the value and convert it to an array. If the section or key is not set, return value is $default.

If the value is empty the return value will be an empty array. If the value is not empty it will be splitted at |. So if the value would be key = foo|bar|baz it gets converted to

array('foo', 'bar', 'baz')

parseHash($section, $key, array $default = null)

Tries to read the value and convert it to a hashmap. If the section or key is not set, return value is $default.

If the value is empty the return value will be an empty hash. If the value is not empty it will be splitted at |. The resulting array will be splitted at the first :, the first part becoming the key and the remaining part becoming the value in the hash. If no : is present, the whole value will be appended to the hash using a numeric value. So key = foo:bar|baz results in

array('foo' => 'bar', 'baz')

parseRange($section, $key, array $default = array())

Tries to read the value and convert it to a range. If the section or key is not set, return value is $default.

Ranges in properties should be written as key = 1..5 the resulting value is

array(1, 2, 3, 4, 5)

This works also with letters and reverse order:

letters = a..e
letter_reverse = e..a
numbers_reverse = 5..1

Passwords

Available since release 4.0.0

Since release 4.0.0, properties with key password will be stored as an instance of stubbles\lang\SecureString. This will also be the return value when requesting the value of such a property.

Modifiable properties

Available since release 1.7.0

By default properties are read only. In case you need modifiable properties use the stubbles\lang\ModifiableProperties class. It provides means to set property values:

setSection($section, array $data)

Sets a complete section with given section name. In case this section already exists it will be replaced.

setValue($section, $name, $value)

Sets a single property value.

setBooleanValue($section, $name, $value)

Sets a single property to a boolean value in a way that it can be read properly by parseBool().

setArrayValue($section, $name, array $value)

Sets an array property to a value in a way that it can be read properly by parseArray().

setHashValue($section, $name, array $hash)

Sets a map property to a value in a way that it can be read properly by parseHash().

setRangeValue($section, $name, array $range)

Sets a range property to a value in a way that it can be read properly by parseRange().

unmodifiable()

Available since release 4.0.0

Returns an unmodifiable instance from the modifiable properties.