PHPackages                             samleybrize/valoa - 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. samleybrize/valoa

ActiveLibrary[Utility & Helpers](/categories/utility)

samleybrize/valoa
=================

Easy value objects and entities

v0.8.7(10y ago)5807MITPHPPHP >=5.4

Since May 29Pushed 10y ago1 watchersCompare

[ Source](https://github.com/samleybrize/valoa)[ Packagist](https://packagist.org/packages/samleybrize/valoa)[ Docs](https://github.com/samleybrize/valoa)[ RSS](/packages/samleybrize-valoa/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (9)Used By (0)

Valoa - Easy value objects and entities
=======================================

[](#valoa---easy-value-objects-and-entities)

Installation
------------

[](#installation)

For a quick install with [Composer](https://getcomposer.org) use :

```
$ composer require samleybrize/valoa

```

Requirements
------------

[](#requirements)

- PHP 5.4+

Usage
-----

[](#usage)

Traditionnaly, when you build value objects (or entities), you define properties as private and then you create a getter (and maybe a setter) for each of them. Valoa handles get and set operations without the need to create any method. All you need is to use the `Samleybrize\Valoa\ValueObject\ValueObjectTrait` trait.

```
use Samleybrize\Valoa\ValueObject\ValueObjectTrait;

class EntityTest
{
    use ValueObjectTrait;

    /**
     * @var int
     */
    private $var1;

    /**
     * @var string
     */
    private $var2;
}

$test       = new EntityTest();
$test->var1 = 23;
$test->var2 = "message";

echo $test->var2;
```

Additionally, you can define constraints to your properties. On the example above, `$var1` only accepts integer values, as specified by the `@var` tag.

### Validation strictness

[](#validation-strictness)

By default, validation is non-strict. For some validators, non-strict validation allows you to give a value of a different type that will be converted. For an integer property, you can set a string `123azerty` that will be converted to the integer `123`. Strict validation is enabled with the `@strict` tag. If strict validation is enabled on an integer property, only integers will be accepted.

```
use Samleybrize\Valoa\ValueObject\ValueObjectTrait;

class EntityTest
{
    use ValueObjectTrait;

    /**
     * @var int
     * @strict
     */
    private $var1;

    /**
     * @var int
     */
    private $var2;
}

$test       = new EntityTest();
$test->var2 = "23text"; // will be converted to the integer "23"
$test->var1 = "23text"; // will raise an exception
```

### Define the validator used

[](#define-the-validator-used)

By default, the `@var` tag define which validator will be used. If for somme reason you need to put some funky value into that tag, you have to specify the validator with the `@validator` tag. If there is a `@validator` tag, the `@var` tag is always ignored.

If you don't want any validation on a property, use the `any` validator.

```
use Samleybrize\Valoa\ValueObject\ValueObjectTrait;

class EntityTest
{
    use ValueObjectTrait;

    /**
     * @var some text
     * @validator string
     */
    private $var1;

    /**
     * @var some text
     * @validator any
     */
    private $var2;
}

$test       = new EntityTest();
$test->var1 = "text"; // validate as string
$test->var2 = "whatever you want"; // will not be validated, any value may be setted
```

### Immutable property

[](#immutable-property)

A property can be made immutable with the `@immutable` tag. Immutable properties can't be setted from outside.

```
use Samleybrize\Valoa\ValueObject\ValueObjectTrait;

class EntityTest
{
    use ValueObjectTrait;

    /**
     * @var string
     * @immutable
     */
    private $var1;
}

$test       = new EntityTest();
$test->var1 = "text"; // will raise an exception
```

You can make all properties immutable at once by setting the `@immutable` tag on the class.

```
/**
 * @immutable
 */
class EntityTest
{
    use ValueObjectTrait;

    /**
     * @var string
     */
    private $var1;

    /**
     * @var boolean
     */
    private $var2;
}

$test       = new EntityTest();
$test->var1 = "text"; // will raise an exception
$test->var2 = true; // will raise an exception
```

### Nullable property

[](#nullable-property)

A property can accept a `null` value with the `@nullable` tag.

```
class EntityTest
{
    use ValueObjectTrait;

    /**
     * @var string
     */
    private $var1;

    /**
     * @var string
     * @nullable
     */
    private $var2;
}

$test       = new EntityTest();
$test->var1 = "text"; // ok
$test->var1 = null; // will raise an exception

$test->var2 = "text"; // ok
$test->var2 = null; // ok
```

### Array types

[](#array-types)

Array types can be specified in several ways. The simplest method is to add `[]` to the tag. This way you can also validate multidimensional arrays, by adding as many `[]` as you want.

```
/**
 * Array of string
 * @var string[]
 */
private $var1;

/**
 * Array of DateTime objects
 * @var \DateTime[]
 */
private $var2;

/**
 * Array of array of string
 * @var string[][]
 */
private $var1;
```

The other way of specifying array types is `@var array` and `@validator` setted to the underlying type. If there is no `@validator` tag, the validator `any`is used by default. This method does not allow to validate multidimensional arrays.

```
/**
 * Array of string
 * @var array
 * @validator string
 */
private $var1;

/**
 * Array of DateTime objects
 * @var array
 * @validator \DateTime
 */
private $var2;
```

### Enum validator

[](#enum-validator)

The enum validator allows you to define a list of accepted values with the `@enum` tag. Each allowed value should be scalar.

```
/**
 * This var accept integer 1, integer 5 and string "text".
 * @var ...
 * @validator enum
 * @enum [1, 5, "text"]
 */
private $var;
```

### Class constants validator

[](#class-constants-validator)

The class constants validator define a set of class constants as allowed values. The `@classname` tag specify the full class name that contains allowed class constants. By default, all class constants in that class are allowed. You can restrict allowed values with the followin options :

- The `@contain` tag is a filter on the class constants names
- The `@beginWith` tag is a filter on the beginning of class constants names
- The `@endWith` tag is a filter on the end of class constants names

```
class Test
{
    const TEST_NAME1   = 1;
    const TEST_NAME2_P = 2;

    const X_AZERTY3    = 3;
    const X_AZERTY4_P  = 3;

    /**
     * Allow all class constants of the class 'Test'
     * @var int
     * @validator ClassConstants
     * @classname Test
     */
    private $var1;

    /**
     * Allow TEST_NAME1 and TEST_NAME2_P
     * @var int
     * @validator ClassConstants
     * @classname Test2
     * @beginWith TEST_
     */
    private $var1;

    /**
     * Allow TEST_NAME2_P and X_NAME4_P
     * @var int
     * @validator ClassConstants
     * @classname Test2
     * @endWith _P
     */
    private $var1;

    /**
     * Allow TEST_NAME1 and TEST_NAME2_P
     * @var int
     * @validator ClassConstants
     * @classname Test2
     * @contain NAME
     */
    private $var1;
}
```

### Validator list

[](#validator-list)

ValidatorOptionsDescriptionNon strictAnyAllow any valueBooleanAllow boolean valuesAny scalar valueClassConstantsAllow constants values of a given classAny scalar value`beginWith`Filter constant names`endWith`Filter constant names`contain`Filter constant namesEmailAllow email adressesEnumAllow a predefined list of valuesAny scalar valueFloatAllow decimal valuesAny scalar value`min`Min valid value`max`Max valid valueIntegerAllow integer valuesAny scalar value`min`Min valid value`max`Max valid valueIpAllow IP addressesStringAllow stringsAny scalar value`minLength`Min valid string length`maxLength`Max valid string length`regex`Validation regex (ex: ^\[0-9\]+$)### Write your own validator

[](#write-your-own-validator)

Custom validators can be created by implementing the `Samleybrize\Valoa\ValueObject\Validator\ValidatorInterface` interface.

```
namespace Your\Namespace;

use Samleybrize\Valoa\ValueObject\Validator\ValidatorInterface;

class CustomValidator implements ValidatorInterface
{
    // $tags contains all doc comment tags
    public function __construct(array $tags = array())
    {
        // ...
    }

    public function isValid(&$value)
    {
        // ...
    }
}
```

To use it, you have to specify the full class name on the `@validator` tag.

```
use Samleybrize\Valoa\ValueObject\ValueObjectTrait;

class EntityTest
{
    use ValueObjectTrait;

    /**
     * @var string
     * @validator \Your\Namespace\CustomValidator
     */
    private $var1;
}
```

### Lazy loaders

[](#lazy-loaders)

Sometimes you want to retrieve some data on demand. All properties accept an instance of the `Samleybrize\Valoa\ValueObject\ValueObjectLazyLoaderInterface` interface regardless of its associated validator. When you first try to get its value, the lazy loader is used to retrieve the effective value and validates it using the validator. Next times, the lazy loader is no longer used.

```
use Samleybrize\Valoa\ValueObject\ValueObjectLazyLoaderInterface;
use Samleybrize\Valoa\ValueObject\ValueObjectTrait;

class Test
{
    /**
     * @var string
     */
    private $var;
}

class LazyLoaderString implements ValueObjectLazyLoaderInterface
{
    public function load()
    {
        // retrieve the value from a database for example
        return "text";
    }
}

class LazyLoaderInteger implements ValueObjectLazyLoaderInterface
{
    public function load()
    {
        // retrieve the value from a database for example
        return 12;
    }
}

$test       = new EntityTest();

$test->var  = new LazyLoaderString();
echo $test->var; // outputs "text"

$test->var  = new LazyLoaderInteger();
echo $test->var; // raise an exception
```

Known limitations
-----------------

[](#known-limitations)

Array types can't be directly modified from outside. Instead, you have two workarounds :

- Retrieve and modify the array externally then set the whole array
- Create a method that modify the array from inside

```
// will not work
$object->array[] = 8;

// workaround 1
$array         = $object->array;
$array[]       = 8;
$object->array = $array;

// workaround 2
$object->addToArray(8);
```

Author
------

[](#author)

This project is authored and maintained by Stephen Berquet.

License
-------

[](#license)

Valoa is licensed under the MIT License - see the `LICENSE` file for details.

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity18

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~34 days

Recently: every ~22 days

Total

8

Last Release

3763d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2a71a22c08e18dedcce0dd335cb0954028d9f2d1ba2f0fed291153fd4f32de16?d=identicon)[samleybrize](/maintainers/samleybrize)

---

Top Contributors

[![samleybrize](https://avatars.githubusercontent.com/u/2537770?v=4)](https://github.com/samleybrize "samleybrize (48 commits)")

### Embed Badge

![Health badge](/badges/samleybrize-valoa/health.svg)

```
[![Health](https://phpackages.com/badges/samleybrize-valoa/health.svg)](https://phpackages.com/packages/samleybrize-valoa)
```

###  Alternatives

[spatie/laravel-help-space

Integrate Helpspace in your Laravel app

2333.7k](/packages/spatie-laravel-help-space)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)