PHPackages                             bound1ess/essence - 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. [Framework](/categories/framework)
4. /
5. bound1ess/essence

ActiveLibrary[Framework](/categories/framework)

bound1ess/essence
=================

Highly opinionated PHP assertion framework providing clean and flexible BDD style API.

1.5.1(11y ago)2652MITPHPPHP >=5.4.0

Since Feb 9Pushed 11y agoCompare

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

READMEChangelogDependencies (5)Versions (11)Used By (2)

Essence 1.5.1 [![Build Status](https://camo.githubusercontent.com/5d02fe30a5f92e4a6f52bff5550a51b7ef3e4aec4471e215321c7aef96402651/68747470733a2f2f7472617669732d63692e6f72672f626f756e64316573732f657373656e63652e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/bound1ess/essence)
================================================================================================================================================================================================================================================================================================

[](#essence-151-)

Essence is a very flexible BDD style assertion framework for PHP that fits into existing PHPUnit projects nicely.

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

[](#installation)

```
composer require --dev bound1ess/essence

```

The Idea
--------

[](#the-idea)

In most PHP testing frameworks, you are tied to *concrete matcher names* (e.g., `assertEqual`, `shouldHaveType`). I don't like that. That's why I created Essence.

Usage
-----

[](#usage)

In order to run a matcher you need to specify it in the *query string*. So what is a query string? Have a look:

```
this("someValue")->should_have_length_of(10); # => "someValue should have length of 10"
expect(123)->toBeAbove(120); # => "expect 123 to be above 120"

$elements = [1, 2, 3, 4, 5];
these($elements)->values->should_contain(5); # => "these elements should contain a value '5'"

expect(null)->not()->to()->beNull(); => "expect NULL not to be NULL"
```

Yes, Essence is smart enough to handle all these cases just as you would expect it to do. So, how do you build a query string (or *assertion*)?

1. Decide if you need to configure a matcher you plan to use. As for now there are two only matchers that can be used in *configuration* mode - `ValuesMatcher` and `KeysMatcher`.
2. Determine what matcher you will need to use to get the job done. Is it `ThrowMatcher`, or, say, `RespondMatcher`?
3. Add some *links* to make the assertion **readable**.
4. Choose an appropriate entry point (`expect`, `this`, `these` etc).
5. Pass a proper value and arguments.
6. If you want to, add `->go()` to immediately perform validation. I'll tell you more about that later.

### Configuration

[](#configuration)

First of all, Essence leverages the singleton pattern to persist all its important data during the runtime. It means that this expression will always be equal to `true`:

```
spl_object_hash(essence()) == spl_object_hash(essence());
```

You can configure Essence by using `configure` method:

```
essence()->configure(function($config) {
    return array_merge($config, [
        "exception" => "Your\Custom\AssertionException",
    ]);
});
```

Available configuration options:

NamePossible valueexceptionfully qualified class name (as a string)implicit\_validationa boolean value (`true` or `false`)linksan array (won't be merged automatically)matchersan associative array *name => aliases* (won't be merged automatically)### Explicit and implicit, validateAll and PHPUnit extension

[](#explicit-and-implicit-validateall-and-phpunit-extension)

If you don't want to write `->validate()` or `->go()` every time, you can enable *implicit validation*:

```
essence()->configure(function() {
    return [
        "implicit_validation" => true,
    ];
});
```

It will validate the last (previous) assertion when you create a new one. Or, even better, just use the PHPUnit extension as shown below:

```
class MyTestCase extends Essence\Extensions\PhpunitExtension
{

    // Your assertions here.
}
```

It'll do the job for you, no need to configure anything or call `go/validate`.

### Verbose mode

[](#verbose-mode)

This line of code will throw an `Essence\Exceptions\AssertionException` by default:

```
expect(10)->to_be_equal_to(15)->validate(); // You can also use "go" instead of "validate".
```

However, if you pass `true` to `validate/go`, Essence will dump all important data and just `exit`.

```
expect(10)->to_be_equal_to(15)->validate(true);
```

```
vendor/bin/phpunit
# ........
Value: 10
Arguments:
  #1: 15
```

Cheatsheet
----------

[](#cheatsheet)

### Entry points

[](#entry-points)

- essence
- it
- that
- this
- these
- those

### Links

[](#links)

- of
- have
- be
- at
- to

### Matchers

[](#matchers)

NameAliasesTypeMatcheran, a, typeContainMatchercontain, includePositiveMatcherok, fineTrueMatchertrueFalseMatcherfalseNullMatchernullEmptyMatcheremptyEqualMatcherequalLikeMatcherlikeAboveMatcheraboveBelowMatcherbelowLeastMatcherleastMostMatchermostWithinMatcherwithinLengthMatcherlengthMatchMatchermatchKeysMatcherkey, keysValuesMatchervalue, valuesThrowMatcherthrow, raiseRespondMatcherrespondCloseMatchercloseLicense
-------

[](#license)

The MIT License (MIT).

Development
-----------

[](#development)

The `Makefile` contains all sorts of useful tasks.

### Running tests

[](#running-tests)

```
make run-tests
```

### Creating code coverage report

[](#creating-code-coverage-report)

```
make coverage-report coverage-report-server
```

### Building documentation

[](#building-documentation)

```
make build-docs docs-server
```

###  Health Score

29

—

LowBetter than 59% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity64

Established project with proven stability

 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 ~6 days

Recently: every ~11 days

Total

10

Last Release

4060d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/270a6b451bb75c99beae25836d16453daf58531cfac6baecd8d0a72059baa44b?d=identicon)[bound1ess](/maintainers/bound1ess)

---

Top Contributors

[![bound1ess](https://avatars.githubusercontent.com/u/10074992?v=4)](https://github.com/bound1ess "bound1ess (178 commits)")

---

Tags

testingframeworkBDDassertion

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/bound1ess-essence/health.svg)

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

###  Alternatives

[pestphp/pest-plugin

The Pest plugin manager

4558.2M109](/packages/pestphp-pest-plugin)[pestphp/pest-plugin-drift

The Pest Drift Plugin

734.0M74](/packages/pestphp-pest-plugin-drift)[defstudio/pest-plugin-laravel-expectations

A plugin to add laravel tailored expectations to Pest

98548.9k4](/packages/defstudio-pest-plugin-laravel-expectations)[pestphp/pest-plugin-type-coverage

The Type Coverage plugin for Pest PHP.

343.3M732](/packages/pestphp-pest-plugin-type-coverage)[pestphp/pest-plugin-stressless

Stressless plugin for Pest

67792.6k16](/packages/pestphp-pest-plugin-stressless)[silverstripe/behat-extension

SilverStripe framework extension for Behat

32564.2k5](/packages/silverstripe-behat-extension)

PHPackages © 2026

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