Skip to content

Sets

So far you've seen hardcoded Sets via Set\Element and integers one via Set\Integers. But there are much more.

Tip

You can find more on Packagist.

Common methods

Map

For all Set objects you can transform the generated values with a function of your own.

Let's say the code you want to prove needs a Password object. You can wrap strings in your object like this:

use Innmind\BlackBox\Set;

$set = Set\Strings::any()
    ->map(static fn(string $string) => new Password($string));

Now if you use $set in a proof it will generate instances of Password with a random string inside it.

Filter

To reuse the password example from above. Say that your password needs to contain the character $. You can do:

use Innmind\BlackBox\Set;

$set = Set\Strings::any()
    ->filter(static fn(string $string) => \str_contains($string, '$'))
    ->map(static fn(string $string) => new Password($string));
Warning

This is an example. You should not enforce your passwords to have a specific value in it. The strength is based on length. (US and French recommendations)

Primitives

Chars

This Set can generate strings containing a single character.

  • Chars::any() describes any chars that can be returned by the \chr() function
  • Chars::lowercaseLetter() describes the range a..z
  • Chars::uppercaseLetter() describes the range A..Z
  • Chars::number() describes the range 0..9
  • Chars::ascii() describes any character that you can typically find on your keyboard
  • Chars::alphanumerical() describes any character from ::lowercaseLetter(), ::uppercaseLetter() or ::number()

Integers

  • Integers::any() describes any integer between \PHP_INT_MIN and \PHP_INT_MAX
  • Integers::between(min, max) describes any integer between the bounds you specify
  • Integers::above(min)
  • Integers::below(max)

The bounds are included in the values that can be generated

IntegersExceptZero

IntegersExceptZero::any() describes any integer except 0

NaturalNumbers

NaturalNumbers::any() is the same as Integers::above(0)

NaturalNumbersExceptZero

NaturalNumbersExceptZero::any() is the same as Integers::above(1)

Nullable

Nullable::of(Set) describes all the values that can be generated by the Set passed as argument and null

RealNumbers

  • RealNumbers::any() describes any float between \PHP_INT_MIN and \PHP_INT_MAX
  • RealNumbers::between(min, max) describes any float between the bounds you specify
  • RealNumbers::above(min)
  • RealNumbers::below(max)

The bounds are included in the values that can be generated

Strings

  • Strings::any() describes any string of a length between 0 and 128 containing any character from Chars::any()
  • Strings::between(min, max) same as ::any() but you specify the length range
  • Strings::atMost(max)
  • Strings::atLeast(min)
  • Strings::madeOf(Set) describes any string made of the characters you specify (ie Strings::madeOf(Chars::alphanumerical()))
    • you can specify the length range via Strings::madeOf(Set)->between(min, max)

Type

Type::any() describes any type that is supported by PHP. This is useful to prove a code doesn't depend on the type of its arguments.

Unicode

  • Unicode::strings() is the same as Strings::madeOf(Unicode::any())
  • Unicode::any() describes any single unicode character
  • Unicode provides all the unicode blocks

UnsafeStrings

UnsafeStrings::any() describes any string that could break your code. You can use this to test the robustness of your code.

User defined values

Elements

Elements::of(...values) describes all the values that you put in (ie Elements::of(true, false) to describe booleans)

FromGenerator

FromGenerator::of(callable) describes values that you will provide via a Generator

Higher order Sets

Decorate

Decorate::immutable(callable, Set) is a way to transform the values that can be generated by the given Set (ie Decorate::immutable(\chr(...), Integers::between(0, 255)) describes all the strings that can be generated by \chr())

This is the same as Integers::between(0, 255)->map(\chr(...)).

Composite

This Set allows to aggregate multiple values to a new one. Let's say you have a User class, you could desribe it via:

Set\Composite::immutable(
    static fn(string $firstname, string $lastname) => new User(
        $firstname,
        $lastname,
    ),
    Strings::atLeast(1),
    Strings::atLeast(1),
);

Any additionnal Set provided will give access to a new argument to the callable.

Either

You can think of this Set as an OR. Either::any(Integers::any(), Strings::any()) describes any integer or string.

Sequence

Sequence::of(Set) describes a list (an array of consecutive values) of values of the given Set type. Sequence::of(Integers::any()) describes any list of integers.

By default the list contains between 0 and 100 elements, you can change this via Sequence::of(Set)->between(min, max).

The bounds are included.

Tuple

This is a special case of Composite. Both examples does the same thing.

Tuple::of(
    Integers::any(),
    Integers::any(),
)

Composite::immutable(
    static fn(int $a, int $b) => [$a, $b],
    Integers::any(),
    Integers::any(),
)

Call

Call::of(static function() {
    return $someValue;
})

This set is useful when building the Model to tests via properties. If BlackBox shrinks properties it will call the provided callable at each shrinking step. This allows to get rid of any state inside your Model between each run.

Specific types

Email

Email::any() describes any valid email string

Uuid

Uuid::any() describes any valid UUID