PHPackages stubbles/values - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. stubbles/values ActiveLibrary[Utility & Helpers](/categories/utility) stubbles/values =============== Useful classes to ease the work with values. v12.0.0(5mo ago)116.6k1[1 PRs](https://github.com/stubbles/stubbles-values/pulls)6BSD-3-ClausePHPPHP ^8.3CI passing Since Jan 11Pushed 1mo ago2 watchersCompare [ Source](https://github.com/stubbles/stubbles-values)[ Packagist](https://packagist.org/packages/stubbles/values)[ Docs](http://stubbles.net/)[ RSS](/packages/stubbles-values/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (4)Versions (17)Used By (6) stubbles/values =============== [](#stubblesvalues) Useful classes to ease the work with values. Build status ------------ [](#build-status) [![Tests](https://github.com/stubbles/stubbles-values/workflows/Tests/badge.svg)](https://github.com/stubbles/stubbles-values/workflows/Tests/badge.svg) [![Latest Stable Version](https://camo.githubusercontent.com/b22181c12221ac6c566371761716c17bff87a56f9b125d201c7573ddf5c78e89/68747470733a2f2f706f7365722e707567782e6f72672f73747562626c65732f76616c7565732f76657273696f6e2e706e67)](https://packagist.org/packages/stubbles/values) [![Latest Unstable Version](https://camo.githubusercontent.com/dc6a302f2456407ffa15a2eab4f491369e23b80a6b51bd598441d0513c29c1aa/68747470733a2f2f706f7365722e707567782e6f72672f73747562626c65732f76616c7565732f762f756e737461626c652e706e67)](//packagist.org/packages/stubbles/values) Installation ------------ [](#installation) *stubbles/values* is distributed as [Composer](https://getcomposer.org/)package. To install it as a dependency of your package use the following command: ``` composer require "stubbles/values": "^12.0" ``` Requirements ------------ [](#requirements) *stubbles/values* requires at least PHP 8.3. Available classes ----------------- [](#available-classes) ### `stubbles\values\Result` [](#stubblesvaluesresult) Enables to wrap a return value which might be `null`. In other languages or libraries this is known as an Optional. To create an instance call `Result::of(someCallThatMightReturnNull())`. #### `isPresent()` [](#ispresent) Returns `true` when result contains a value which is not `null`. #### `isEmpty()` [](#isempty) Returns `true` when result contains an empty value. Please note that this method will always return `false` in case the value is an integer, even if it is 0. #### `value()` [](#value) Returns the actual value. #### `filter(callable $predicate)` [](#filtercallable-predicate) Allows to filter the value. In case the value fulfills the given predicate the `Result` instance is returned. If the value does not fulfill the predicate the equivalent of `Result::of(null)` is returned. ``` $filter = fn($value) => 303 === $value; echo Result::of(303)->filter($filter)->value(); // displays 303 echo Result::of(313)->filter($filter)->value(); // displays nothing echo Result::of(null)->filter($filter)->value(); // displays nothing ``` #### `map(callable $mapper)` [](#mapcallable-mapper) Maps the value using the given mapper into a different result. In case the value is `null` the return value still is equivalent to `Result::of(null)`. ``` $mapper = fn($value) => 'Roland TB 303'; echo Result::of(303)->map($mapper)->value(); // displays "Roland TB 303" echo Result::of(null)->map($mapper)->value(); // displays nothing ``` #### `whenNull($other)` [](#whennullother) Returns the result if value is present, or result of other. ``` $default = 909; echo Result::of(303)->whenNull($default)->value(); // displays 303 echo Result::of(null)->whenNull($default)->value(); // displays 909 ``` #### `applyWhenNull(callable $other)` [](#applywhennullcallable-other) Returns the result if value is present, or the result of applied other. ``` $default = function() { return 909; }; echo Result::of(303)->applyWhenNull($default)->value(); // displays 303 echo Result::of(null)->applyWhenNull($default)->value(); // displays 909 ``` #### `whenEmpty($other)` [](#whenemptyother) Returns the result if value is not empty, or result of other. ``` $default = 'Roland TB 303'; echo Result::of('Roland 909')->whenEmpty($default)->value(); // displays Roland 909 echo Result::of('')->whenEmpty($default)->value(); // displays Roland TB 303 ``` #### `applyWhenEmpty($other)` [](#applywhenemptyother) Returns the result if value is not empty, or result of applied other. ``` $default = fn() => 'Roland TB 303'; echo Result::of('Roland 909')->applyWhenEmpty($default)->value(); // displays Roland 909 echo Result::of('')->applyWhenEmpty($default)->value(); // displays Roland TB 303 ``` ### `stubbles\values\Secret` [](#stubblesvaluessecret) Secret provides a reasonable secure storage for security-sensitive lists of characters, such as passwords. It prevents accidentially revealing them in output, by var\_dump()ing, echo()ing, or casting the object to array. All these cases will not show the password, nor the crypt of it. However, it is not safe to consider this implementation secure in a crypto- graphically sense, because it does not care for a very strong encryption, and it does share the encryption key with all instances of it in a single PHP instance. When using this class, you must make sure not to extract the secured string and pass it to a place where an exception might occur, as it might be exposed as method argument. Instances of this class can not be serialized. #### Create a secret [](#create-a-secret) To create a secret call `Secret::create('my secret value')`. Please note that you can not use this function to create a secret with value `null`. If you explicitly want to do that use `Secret::forNull()`. #### `isContained(): bool` [](#iscontained-bool) Checks whether encryption on creation was successful. In case it failed no errors or exception is thrown, so this is the only way to check. #### `isNull(): bool` [](#isnull-bool) Checks if actual secret is `null`. #### `unveil(): string` [](#unveil-string) Unveils the secret and returns it as a string. This should be called at the latest possible moment to avoid unneccessary revealing of the value to be intended stored secure. #### `substring(int $start, int $length = null): Secret` [](#substringint-start-int-length--null-secret) Creates a substring of the secret value as new `Secret` instance. Please note that this method is deprecated since release 10.0.0 and will be removed with 11.0.0. #### `length(): int` [](#length-int) Returns length of the secret. Allows to check if it would fit a certain place without the need to unveil it first. ### `stubbles\values\Parse` [](#stubblesvaluesparse) Provides methods for parsing strings to a target type. #### `Parse::toInt($value)` [](#parsetointvalue) Parses integer value from given string. #### `Parse::toFloat($value)` [](#parsetofloatvalue) Parses float value from given string. #### `Parse::toBool($string)` [](#parsetoboolstring) Parses boolean value from given string. The return value is true if the string value is either "1", "yes", "true" or "on". In any other case the return value will be false. #### `Parse::toList($string, string $separator = '|')` [](#parsetoliststring-string-separator--) Parses string to a list of strings. If the value is empty the return value will be an empty array. If the value is not empty it will be splitted at "|" (or any other separator provided). ``` Parse::toList("foo|bar|baz"); // results in ['foo', 'bar', 'baz'] ``` #### `Parse::toMap($string)` [](#parsetomapstring) Parses string to a map. If the value is empty the return value will be an empty map. If the value is not empty it will be splitted at "|". The resulting list will be splitted at the first ":", the first part becoming the key and the remainer becoming the value in the map. If no ":" is present, the whole value will be appended to the map using a numeric value for the key. ``` Parse::toMap("foo:bar|baz"); // results in ['foo' => 'bar', 'baz'] ``` #### `Parse::toRange($string)` [](#parsetorangestring) Parses string to a range. Ranges can be written as 1..5 which will return an array: \[1, 2, 3, 4, 5\]. Works also with letters and reverse order a..e, e..a and 5..1. #### `Parse::toClass($string)` [](#parsetoclassstring) Parses string to a reflection class. String must have the format *fully\\qualified\\Classname.class*. In case the string can not be parsed the return value is `null`. #### `Parse::toClassname($string)` [](#parsetoclassnamestring) Parses string as existing class name. String must have the format *fully\\qualified\\Classname::class*. In case the string can not be parsed or the class does not exist the return value is `null`. ### `stubbles\values\Properties` [](#stubblesvaluesproperties) 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'); ``` 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 ``` #### `parse(string $section, string $key)->asInt(): ?int` [](#parsestring-section-string-key-asint-int) Tries to read the value and convert it to int. If you want to have a default value in case the section or key is not set, use `parse($section, $key)->defaultingTo(42)->asInt()`. Please note that the given default value must be of type `int`. #### `parse(string $section, string $key)->asFloat(): ?float` [](#parsestring-section-string-key-asfloat-float) Tries to read the value and convert it to float. If you want to have a default value in case the section or key is not set, use `parse($section, $key)->defaultingTo(3.03)->asFloat()`. Please note that the given default value must be of type `float`. #### `parse(string $section, string $key)->asBool(): ?bool` [](#parsestring-section-string-key-asbool-bool) Tries to read the value and convert it to boolean. The following value contents will be converted to `true`: - yes - true - on All other values will evaluate to `false`. If you want to have a default value of `true` in case the section or key is not set, use `parse($section, $key)->defaultingTo(true)->asBool()`. Please note that the given default value must be of type `bool`. It is not required to explicitly specify `false` as default value. In case the section or key is not set `false` will be the return default value if not specified otherwise. #### `parse(string $section, string $key)->asList(): ?array` [](#parsestring-section-string-key-aslist-array) Tries to read the value and convert it to a list (array with integers as key). 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 `['foo', 'bar', 'baz']`. If you want to have a default value in case the section or key is not set, use `parse($section, $key)->defaultingTo(['foo', 'bar'])->asList()`. Please note that the given default value must be of type `array`. #### `parse(string $section, string $key)->asMap(): ?array` [](#parsestring-section-string-key-asmap-array) Tries to read the value and convert it to a hashmap. 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 `['foo' => 'bar', 'baz']`. If you want to have a default value in case the section or key is not set, use `parse($section, $key)->defaultingTo(['foo' => 'bar'])->asMap()`. Please note that the given default value must be of type `array`. #### `parse(string $section, string $key)->asRange(): ?array` [](#parsestring-section-string-key-asrange-array) Tries to read the value and convert it to a range. Ranges in properties should be written as *key = 1..5* the resulting value is `[1, 2, 3, 4, 5]`. This works also with letters and reverse order: ``` letters = a..e letter_reverse = e..a numbers_reverse = 5..1 ``` If you want to have a default value in case the section or key is not set, use `parse($section, $key)->defaultingTo([1, 2, 3])->asRange()`. Please note that the given default value must be of type `array`. #### `parse(string $section, string $key)->asClass(): ?ReflectionClass` [](#parsestring-section-string-key-asclass-reflectionclass) Tries to read the value and convert it to an instance of `ReflectionClass` for the class name. Classes in properties should be written as \_key = foo\\bar\\Baz.class. If you want to have a default value in case the section or key is not set, use `parse($section, $key)->defaultingTo(new ReflectionClass(stdClass::class))->asClass()`. Please note that the given default value must be of type `ReflectionClass`. #### Passwords [](#passwords) *Available since release 4.0.0* Since release 4.0.0, properties with key `password` will be stored as an instance of `stubbles|values\Secret`. This will also be the return value when requesting the value of such a property. ### Modifiable properties [](#modifiable-properties) *Available since release 1.7.0* By default properties are read only. In case you need modifiable properties use the `stubbles\values\ModifiableProperties` class. It provides means to set property values: #### `setSection(string $section, array $data)` [](#setsectionstring-section-array-data) Sets a complete section with given section name. In case this section already exists it will be replaced. #### `setValue(string $section, string $name, $value)` [](#setvaluestring-section-string-name-value) Sets a single property value. #### `setBooleanValue(string $section, string $name, $value)` [](#setbooleanvaluestring-section-string-name-value) Sets a single property to a boolean value in a way that it can be read properly by `parseBool()`. #### `setArrayValue(string $section, string $name, array $value)` [](#setarrayvaluestring-section-string-name-array-value) Sets an array property to a value in a way that it can be read properly by `parseArray()`. #### `setHashValue(string $section, string $name, array $hash)` [](#sethashvaluestring-section-string-name-array-hash) Sets a map property to a value in a way that it can be read properly by `parseHash()`. #### `setRangeValue(string $section, string $name, array $range)` [](#setrangevaluestring-section-string-name-array-range) Sets a range property to a value in a way that it can be read properly by `parseRange()`. #### `unmodifiable()` [](#unmodifiable) *Available since release 4.0.0* Returns an unmodifiable instance from the modifiable properties. ### `stubbles\values\ResourceLoader` [](#stubblesvaluesresourceloader) *Available since release 7.1.0* #### Description [](#description) The `stubbles\values\ResourceLoader` allows to load resources from different locations. It relies on the root path as described below. In *stubbles/values*, a resource is defined as any kind of file which is located in the path `src/main/resources` of the current project, or in `src/main/resources`of any other Composer package located in `vendor`. #### `open(string $resource, string $withClass = 'stubbles\streams\file\FileInputStream')` [](#openstring-resource-string-withclass--stubblesstreamsfilefileinputstream) Opens the given resource to read its contents using the given `$withClass`. This class must accept the resource path as constructor argument. By default the class `stubbles\streams\file\FileInputStream` will be used, but the package [stubbles/streams](https://github.com/stubbles/stubbles-streams) which provides this class must be required in your project. Resource can either be a complete path to a resource or a local path. In case it is a local path it is searched within the `src/main/resources` folder of the current project. It is not possible to open resources outside of the root path by providing a complete path, a complete path must always lead to a resource located within the root path. #### `load(string $resource)` [](#loadstring-resource) Loads resource contents. Resource can either be a complete path to a resource or a local path. In case it is a local path it is searched within the `src/main/resources` folder of the current project. It is not possible to load resources outside of the root path by providing a complete path, a complete path must always lead to a resource located within the root path. ``` $props = $resourceLoader->load('some/properties.ini'); ``` #### `loadWith(string $resource, callable $loader)` [](#loadwithstring-resource-callable-loader) Loads resource contents. Resource can either be a complete path to a resource or a local path. In case it is a local path it is searched within the `src/main/resources` folder of the current project. It is not possible to load resources outside of the root path by providing a complete path, a complete path must always lead to a resource located within the root path. The given `$loader` must accept a path and return the result from the load operation: ``` $props = $resourceLoader->loadWith( 'some/properties.ini', fn($path) => Properties::fromFile($path) ); ``` #### `availableResourceUris(string $resourceName): array` [](#availableresourceurisstring-resourcename-array) Returns a list of all available URIs for a resource. The returned list is sorted alphabetically, meaning that local resources of the current project are always returned as first entry if they exist, and all vendor resources after. Order of vendor resources is also in alphabetical order of vendor/package names. ### `stubbles\values\Rootpath` [](#stubblesvaluesrootpath) *Available since release 7.1.0* #### Description [](#description-1) The root path within a project is represented by `stubbles\values\Rootpath`. It is defined as the path in which the whole application resides. When an instance is created and no argument is provided, the class will calculate the root path by checking the following locations: - In case the application is inside a phar, it's the directory where the phar is stored. - Try to locate the `vendor/autoload.php` file generated by Composer, and go up one above `vendor/..`. For unit tests it can be useful to supply the actual root path to be used for the test directly when constructing the class. #### `to(string ...$path): string` [](#tostring-path-string) Returns absolute path to given local path. Supports arbitrary lists of arguments, e.g. `$rootpath->to('src', 'main', 'php', 'Example.php')` will return `/absolute/path/to/root/src/main/php/Example.php`. #### `contains(string $path): bool` [](#containsstring-path-bool) Checks if given path is located within root path. #### `sourcePathes(): array` [](#sourcepathes-array) Returns a list of all source pathes defined for the autoloader. It relies on autoloader files generated by Composer. If no such autoloader is present the list of source pathes will be empty. ### `Rootpath::default(): string` [](#rootpathdefault-string) *Available since release 8.1.0* A static method which returns the rootpath directly as string when not instance is required. ### `stubbles\values\Value` [](#stubblesvaluesvalue) *Available since release 7.2.0* #### Description [](#description-2) Represents a single value, mostly scalar ones, on which certain checks can be done. Some of the checks are built-in, but additional checks can be defined. Create an instance with `Value::of($someValue)`. In case `$someValue` is `null`a fixed value instance will be used. For all times there is only one instance of `Value::of(null)` - each creation with `null` will return the same instance. To access the stored value call `$actualValue = $value->value()`. #### `contains($needle): bool` [](#containsneedle-bool) Checks if the value contains the needle. In case the value is a string it is checked whether `$needle` is a substring within the value. In case the value is an array or an instance of `\Traversable` the given `$needle` must be an element within the array or traversable. #### `containsAnyOf(array $elements): bool` [](#containsanyofarray-elements-bool) Checks if the value contains any of the given elements. #### `equals($expected): bool` [](#equalsexpected-bool) Checks if the value equals the expected value. Expected value must be a non-null scalar value. Comparison is done using `===`. #### `isOneOf(array $allowedValues, bool $strict = false): bool` [](#isoneofarray-allowedvalues-bool-strict--false-bool) Checks if the value equals one of the allowed values. In case the value itself is an array this method returns `false` if it contains a value which is not in the list of allowed values. Sometimes it is necessary that the value type must also be equal. In such cases the flag `$strict` should be set to `true`. #### `isMatchedBy(string $regex): bool` [](#ismatchedbystring-regex-bool) Checks if the value can be matched by the given regular expression. #### `satisfies(callable $check): bool` [](#satisfiescallable-check-bool) Checks if the value satisfies the given callable. The given callable must accept a single value, its return value is returned. #### `isNull(): bool` [](#isnull-bool-1) *Available since release 8.1.0* Checks if the value is `null`. #### `isEmpty(): bool` [](#isempty-bool) *Available since release 8.1.0* Checks if the value is empty. A value is empty if it is `null`, an empty string or an empty array. #### Define additional checks [](#define-additional-checks) Additional checks can be defined: `Values::defineCheck('hasPower', function($value) { return 6100 == $value; });` After the definition this check can be used as follows: `Value::of($someValue)->hasPower()` Existing PHP functions must not be defined, they are available automatically: `Value::of($someValue)->is_int()` Available functions ------------------- [](#available-functions) ### `stubbles\values\lastErrorMessage(): Result` [](#stubblesvalueslasterrormessage-result) Returns the message of the native PHP function `error_get_last()['message']` as instance of `stubbles\values\Result`. ### `stubbles\values\typeOf(&$value): string` [](#stubblesvaluestypeofvalue-string) Returns the correct type of given value. For objects the actual class name will be returned. In case of resources the return value will be *resource\[type\_of\_resource\]*, e.g. *resource\[stream\]*. For all other types the result is call to PHP's native `gettype()` function. ### `stubbles\values\pattern($pattern): Pattern` [](#stubblesvaluespatternpattern-pattern) *Available since release 7.1.0.* Creates a pattern from regular expression which can be used to match other string values. The pattern uses preg\_match() and checks if the value occurs exactly one time. Please make sure that the supplied regular expression contains correct delimiters, they will not be applied automatically. The matches() method throws a \\RuntimeException in case the regular expression is invalid. ### Health Score 58 — FairBetter than 98% of packages Maintenance88 Actively maintained with recent releases Popularity26 Limited adoption so far Community17 Small or concentrated contributor base Maturity86 Battle-tested with a long release history Bus Factor1 Top contributor holds 65.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~240 days Recently: every ~523 days Total 16 Last Release 161d ago Major Versions v7.2.1 → v8.0.02016-07-11 v8.1.0 → v9.0.02019-10-29 v9.2.0 → v10.0.02022-12-26 v10.0.0 → v11.0.02023-12-25 v11.0.1 → v12.0.02025-11-29 PHP version history (6 changes)v7.0.0PHP >=5.6.0 v8.0.0PHP ^7.0 v9.0.0PHP ^7.3 v10.0.0PHP ^8.0 v11.0.0PHP ^8.2 v12.0.0PHP ^8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/cde3f4e0a0e4454942288eb300c91644bd359cc3572d65b473e3484701fa4931?d=identicon)[mikey179](/maintainers/mikey179) --- Top Contributors [![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (52 commits)")[![mikey179](https://avatars.githubusercontent.com/u/190475?v=4)](https://github.com/mikey179 "mikey179 (27 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/stubbles-values/health.svg) ``` [![Health](https://phpackages.com/badges/stubbles-values/health.svg)](https://phpackages.com/packages/stubbles-values) ``` ### Alternatives [elements/process-manager-bundle The Process Manager allows you to manage (define,execute...) arbitrary processes/commands in the Pimcore backend. 49633.0k5](/packages/elements-process-manager-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)