{"id":28360051,"url":"https://github.com/respect/assertion","last_synced_at":"2025-07-20T15:02:32.707Z","repository":{"id":62534975,"uuid":"140954715","full_name":"Respect/Assertion","owner":"Respect","description":"The power of Respect\\Validation into an assertion library with more than 1.5k assertions.","archived":false,"fork":false,"pushed_at":"2023-04-11T21:49:54.000Z","size":279,"stargazers_count":29,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-11T04:01:50.858Z","etag":null,"topics":["assert","assertions","php","respect","respect-validation"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Respect.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-07-14T14:59:42.000Z","updated_at":"2025-05-23T23:57:49.000Z","dependencies_parsed_at":"2025-06-22T20:42:09.232Z","dependency_job_id":null,"html_url":"https://github.com/Respect/Assertion","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Respect/Assertion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Respect%2FAssertion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Respect%2FAssertion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Respect%2FAssertion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Respect%2FAssertion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Respect","download_url":"https://codeload.github.com/Respect/Assertion/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Respect%2FAssertion/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266143941,"owners_count":23883069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assert","assertions","php","respect","respect-validation"],"created_at":"2025-05-28T10:11:10.072Z","updated_at":"2025-07-20T15:02:32.674Z","avatar_url":"https://github.com/Respect.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Respect\\Assertion\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/Respect/Assertion/continuous-integration.yml?branch=master\u0026style=flat-square)](https://github.com/Respect/Assertion/actions/workflows/continuous-integration.yml)\n[![Code Coverage](https://img.shields.io/codecov/c/github/Respect/Assertion?style=flat-square)](https://codecov.io/gh/Respect/Assertion)\n[![Latest Stable Version](https://img.shields.io/packagist/v/respect/assertion.svg?style=flat-square)](https://packagist.org/packages/respect/assertion)\n[![Total Downloads](https://img.shields.io/packagist/dt/respect/assertion.svg?style=flat-square)](https://packagist.org/packages/respect/assertion)\n[![License](https://img.shields.io/packagist/l/respect/assertion.svg?style=flat-square)](https://packagist.org/packages/respect/assertion)\n\nThe power of [Validation][] into an assertion library.\n\n* More than 1.5k assertions\n* Support for custom messages\n* Support for custom exceptions\n\nFor a complete list of assertions, check all the [mixin interfaces][], and read\n[Validation][] to understand how each rule/assertion works.\n\n## Installation\n\nThis package is available on [Packagist][], and you can install it using\n[Composer][].\n\n```shell\ncomposer require respect/assertion\n```\n\nWorks on PHP 8.1 or above.\n\n## Another assertion library\n\nThere are PHP assertion libraries that a lot of people in the PHP the community\nuse:\n\n- [beberlei/assert][]\n- [webmozart/assert][]\n\nThey are both straightforward to use and have a lot of assertions, so there\nwould be no reason to create yet another one. On the other hand, they have fewer\nassertions than [Validation][] does.\n\nThe main idea of [Validation][] is to make it easy to create chain of\nvalidations, but when it can get verbose when you want to make a simple\nassertion.\n\nThis library offers a more straightforward assertion API for [Validation][],\nwhich means that you can use all [Validation][]'s rules plus your own rules.\n\n## Usage\n\nThe examples in the document will assume that this library is available in the\nautoload and that the class `Respect\\Assertion\\Assert` is imported.\n\nThe `Assert` class can use any rule from [Validation][] with the input as its\nfirst argument:\n\n```php\n// will throw an exception =\u003e 1 must be equals 5\nAssert::equals(1, 5);\n\n// will throw an exception =\u003e \"string\" must be of type integer\nAssert::intType('string');\n\n// will not throw an exception\nAssert::odd(5);\n```\n\nBy default, it throws exceptions that are instances of [ValidationException][],\nwhich means you can catch [InvalidArgumentException][] (or [LogicException][]).\n\n### Custom messages\n\nThe exceptions that `Assert` throws are the same that [Validation][] throws.\nThat allows you to customize the error messages using templates:\n\n```php\n// will throw an exception =\u003e I was expecting 5, but you gave be 1\nAssert::equals(1, 5, 'I was expecting {{compareTo}}, but you gave be {{input}}');\n```\n\n### Custom exceptions\n\nInstead of throwing [Validation][] exceptions, you can use your exceptions:\n\n```php\n// will throw the defined DomainException\nAssert::between(42, 1, 10, new DomainException('Something is not right'));\n```\n\nThat can be very useful if you want to throw specific exceptions for your\napplication. That was a great idea from [Malukenho][]!\n\n### Chained assertions (`that()`)\n\nYou can chain assertions using `Assert::that($input)`, which allows you to\nperform multiple assertions to the same input with less duplication.\n\n```php\n// will throw an exception =\u003e I expected a positive number\nAssert::that(-1)\n    -\u003eintVal('The number {{input}} must be an integer')\n    -\u003epositive('The number must be positive')\n    -\u003elessThan(4);\n```\n\nIn the example above, as soon as any assertion fails, it will throw an\nexception. If you wish to chain validations and only check them all\nsimultaneously, we suggest you use the API from [Validation][].\n\nYou can also customize a message or exception for the whole chain.\n\n```php\n// will throw an exception =\u003e The number must be valid\nAssert::that(0, new DomainException('The number must be valid'))\n        -\u003epositive()\n        -\u003egreaterThan(5);\n\n// will throw an exception =\u003e But it is not greater than 5, though\nAssert::that(3, 'The number must be valid')\n        -\u003epositive()\n        -\u003egreaterThan(5, 'But it is not greater than 5, though');\n```\n\nNote that the customization on a specific assertion will overwrite the\ncustomization on the whole chain.\n\nYou can also apply the effect of the prefixes listed below to the whole chain.\n\n```php\n// will throw an exception =\u003e 3 (the length of the input) must equal 4\nAssert::that(['names' =\u003e ['Respect', 'Assertion'], 'options' =\u003e [1, 2, 3]])\n    -\u003eall()-\u003earrayType()\n    -\u003ekey('names')-\u003eallStringType()\n    -\u003ekey('options')-\u003elengthEquals(4);\n```\n\nThere are also some special methods that allow you to create a chain of\nassertions.\n\n* `thatAll()`: assert all elements in the input with the subsequent assertions.\n* `thatNot()`: assert the input inverting the subsequent assertions.\n* `thatNullOr()`: assert the input if it is not `null` with the subsequent assertions.\n* `thatKey()`: assert a key from the input with the subsequent assertions.\n* `thatProperty()`: assert a property from the input with the subsequent assertions.\n\n## Prefixes\n\nWith Assertion, you can use any [Validation][] rule, but it also allows\nyou to use them with prefixes that simplify some operations.\n\n### `all*()`: asserting all elements in an input\n\nAssertions can be executed with the `all` prefix which will assert all elements\nin the input with the prefixed assertion:\n\n```php\n// will throw an exception =\u003e \"3\" (like all items of the input) must be of type integer\nAssert::allIntType([1, 2, '3']);\n```\n\nIn some cases, you might want to perform multiple assertions to all elements. You\ncan use `thatAll()` chain of assertions that will assert all elements in the input\nwith the subsequent assertions:\n\n```php\n// will throw an exception =\u003e 3 (like all items of the input) must be between 1 and 2\nAssert::thatAll([1, 2, 2, 1, 3])\n    -\u003eintVal()\n    -\u003ebetween(1, 2);\n```\n\nIf you want to perform multiple assertions to all elements, but you also want to\nperform other assertions to the input, you can `that()-\u003eall()`:\n\n```php\n// will throw an exception =\u003e 5 (the length of the input) must be less than 4\nAssert::that([1, 2, 2, 1, 3])\n    -\u003earrayType()\n    -\u003enotEmpty()\n    -\u003elengthGreaterThan(3)\n    -\u003eall()-\u003eintVal()-\u003ebetween(1, 2);\n```\n\n### `nullOr*()`: asserting the value of an input or null\n\nAssertions can be executed with the `nullOr` prefix which will assert only if\nthe value of the input it not null.\n\n```php\n// will throw an exception =\u003e 42 must be negative\nAssert::nullOrNegative(42);\n\n// will not throw an exception\nAssert::nullOrNegative(null);\n\n// will throw an exception =\u003e 5 must be between 1 and 4\nAssert::nullOrBetween(5, 1, 4);\n\n// will not throw an exception\nAssert::nullOrBetween(null, 1, 4);\n```\n\nIn some cases, you might want to perform multiple assertions to a value in case\nit is not null. In this case, you can use `thatNullOr()`:\n\n```php\n// will throw an exception =\u003e 6 must be a valid prime number\nAssert::thatNullOr(6)\n        -\u003epositive()\n        -\u003ebetween(1, 10)\n        -\u003eprimeNumber();\n\n// will not throw an exception\nAssert::thatNullOr(null)\n        -\u003epositive()\n        -\u003ebetween(1, 10)\n        -\u003eprimeNumber();\n```\n\nFor convenience, you might also use the `that()-\u003enullOr()`:\n\n```php\nAssert::that(6)\n    -\u003enullOr()-\u003epositive()-\u003ebetween(1, 10)-\u003eprimeNumber();\n```\n\n### `not*()`: inverting assertions\n\nYou can execute assertions with the `not` prefix, which will assert the opposite\nof the prefixed assertion:\n\n```php\n// will throw an exception =\u003e 2 must not be an even number\nAssert::notEven(2);\n\n// will throw an exception =\u003e 3 must not be in `{ 1, 2, 3, 4 }`\nAssert::notIn(3, [1, 2, 3, 4]);\n```\n\nIf you need to invert more than a few rules, it might be easier to use `thatNot()`\nand `that()-\u003enot()`:\n\n```php\n// will throw an exception =\u003e \"1\" must not be positive\nAssert::thatNot('1')\n        -\u003eintType()\n        -\u003epositive()\n        -\u003ebetween(1, 3);\n\n\n// will throw an exception =\u003e \"1\" must not be positive\nAssert::that('1')\n        -\u003enot()-\u003eintType()-\u003epositive()-\u003ebetween(1, 3);\n```\n\n### `key*()`: asserting a key in an array\n\nYou can use `keyPresent` to check whether a key is present in an array.\n\n```php\n// will throw an exception =\u003e bar must be present\nAssert::keyPresent(['foo' =\u003e true], 'bar');\n```\n\nYou can use `keyNotPresent` to check whether a key is present in an array.\n\n```php\n// will throw an exception =\u003e bar must not be present\nAssert::keyNotPresent(['bar' =\u003e 2], 'bar');\n```\n\nAlso, with the `key` prefix it will assert the value of the array that contains\nthe specified key.\n\n```php\n// will throw an exception =\u003e foo must equal 3\nAssert::keyEquals(['foo' =\u003e 2], 'foo', 3);\n\n// will throw an exception =\u003e bar must be negative\nAssert::keyNegative(['bar' =\u003e 2], 'bar');\n\n// will throw an exception =\u003e bar must not be of type integer\nAssert::keyNotIntType(['bar' =\u003e 2], 'bar');\n\n// will throw an exception =\u003e baz must be present\nAssert::keyNegative(['foo' =\u003e 2], 'baz');\n\n// will throw an exception =\u003e foo must exist\nAssert::keyExists(['foo' =\u003e '/path/to/file.txt'], 'foo');\n```\n\nNot that `keyExists` assertion, will assert whether the value of key `foo` exists\nin the Filesystem.\n\nIf you want to perform multiple assertions to the key of an input, you can use\n`thatKey()`:\n\n```php\n// will throw an exception =\u003e 9 (the length of the input) must be less than 4\nAssert::thatKey(['foo' =\u003e 'my-string'], 'foo')\n        -\u003estringType()\n        -\u003estartsWith('my-')\n        -\u003elengthLessThan(4);\n```\n\nIf you want to perform multiple key assertions to the same input, you can use\n`that()-\u003ekey()`:\n\n```php\n// will throw an exception =\u003e bar must be less than 40\nAssert::that(['foo' =\u003e 'my-string', 'bar' =\u003e 42])\n        -\u003earrayType()\n        -\u003ekey('foo')-\u003estringType()-\u003estartsWith('my-')\n        -\u003ekey('bar')-\u003eintType()-\u003epositive()-\u003elessThan(40);\n```\n\n### `property*()`: asserting a property in an object\n\nWe'll use the object below as input in the examples that follow.\n\n```php\n$input = new stdClass();\n$input-\u003efoo = 1;\n```\n\nYou can use `propertyPresent` to check whether a property is present in an object.\n\n```php\n// will throw an exception =\u003e Attribute bar must be present\nAssert::propertyPresent($input, 'bar');\n```\n\nYou can use `propertyNotPresent` to check whether a property is *not* present in\nan object.\n\n```php\n// will throw an exception =\u003e Attribute foo must not be present\nAssert::propertyNotPresent($input, 'foo');\n```\n\nWith the `property` prefix, you can make assertions with the value of a specific\nobject's property.\n\n```php\n// will throw an exception =\u003e foo must equal 3\nAssert::propertyEquals($input, 'foo', 3);\n\n// will throw an exception =\u003e foo must be negative\nAssert::propertyNegative($input, 'foo');\n\n// will throw an exception =\u003e foo must not be of type integer\nAssert::propertyNotIntType($input, 'foo');\n\n// will throw an exception =\u003e Attribute baz must be present\nAssert::propertyNegative($input, 'baz');\n\n// will throw an exception =\u003e foo must exists\nAssert::propertyExists($input, 'foo');\n```\n\nNote that the `propertyExists` assertion will assert whether the value of\nproperty `foo` exists in the FileSystem.\n\nIf you want to perform multiple assertions to a property of an object, you can\nuse `thatProperty()`:\n\n```php\n// will throw an exception =\u003e foo must be greater than 5\nAssert::thatProperty($input, 'foo')\n        -\u003eintType()\n        -\u003epositive()\n        -\u003egreaterThan(5);\n```\n\nIf you want to perform multiple key assertions to the same input, you can use\n`that()-\u003eproperty()`:\n\n```php\n// will throw an exception =\u003e foo must be greater than 5\nAssert::that($input)\n        -\u003einstance(stdClass::class)\n        -\u003eproperty('foo')-\u003eintType()-\u003epositive()-\u003egreaterThan(5);\n```\n\n### `length*()`: asserting the length of an input\n\nAssertions can be executed with the `length` prefix which will assert the length\nof the input with the prefixed assertion:\n\n```php\n// will throw an exception =\u003e 6 (the length of the input) must be between 10 and 15\nAssert::lengthBetween('string', 10, 15);\n```\n\nThe `length` prefix can also be used with arrays and instances of [Countable][]:\n\n```php\n// will throw an exception =\u003e 4 (the length of the input) must be an odd number\nAssert::lengthOdd([1, 2, 3, 4]);\n\n// will throw an exception =\u003e 3 (the length of the input) must be an even number\nAssert::lengthEven(new ArrayObject([1, 2, 3]));\n```\n\nThis library also allows you to use the `not` prefix after the `length` prefix:\n\n```php\n// will throw an exception =\u003e 2 (the length of the input) must not be multiple of 2\nAssert::lengthNotMultiple([1, 2], 2);\n```\n\n### `max*()`: asserting the maximum of an input\n\nAssertions can be executed with the `max` prefix which will assert the maximum\nvalue of the input with the prefixed assertion:\n\n```php\n// will throw an exception =\u003e 3 (the maximum of the input) must be between 5 and 10\nAssert::maxBetween([1, 2, 3], 5, 10);\n```\n\nThe `max` prefix can be used with any [iterable][] value:\n\n```php\n// will throw an exception =\u003e 3 (the maximum of the input) must be an even number\nAssert::maxEven([1, 2, 3]);\n\n// will throw an exception =\u003e 60 (the maximum of the input) must be a valid perfect square\nAssert::maxPerfectSquare(new ArrayObject([45, 60, 20]));\n```\n\nThis library also allows you to use the `not` prefix after the `max` prefix:\n\n```php\n// will throw an exception =\u003e 23 (the maximum of the input) must not be positive\nAssert::maxNotPositive([23, 7, 20]);\n```\n\n### `min*()`: asserting the minimum of an input\n\nAssertions can be executed with the `min` prefix which will assert the minimum\nvalue of the input with the prefixed assertion:\n\n```php\n// will throw an exception =\u003e 1 (the minimum of the input) must be between 5 and 10\nAssert::minBetween([1, 2, 3], 5, 10);\n```\n\nThe `min` prefix can be used with any [iterable][] value:\n\n```php\n// will throw an exception =\u003e 1 (the minimum of the input) must be an even number\nAssert::minEven([1, 2, 3]);\n\n// will throw an exception =\u003e 20 (the minimum of the input) must be a valid perfect square\nAssert::minPerfectSquare(new ArrayObject([45, 60, 20]));\n```\n\nThis library also allows you to use the `not` prefix after the `min` prefix:\n\n```php\n// will throw an exception =\u003e 7 (the minimum of the input) must not be positive\nAssert::minNotPositive([23, 7, 20]);\n```\n\n[beberlei/assert]: https://github.com/beberlei/assert\n[Composer]: http://getcomposer.org\n[Countable]: http://php.net/countable\n[InvalidArgumentException]: https://www.php.net/InvalidArgumentException\n[iterable]: http://php.net/types.iterable\n[LogicException]: https://www.php.net/LogicException\n[Malukenho]: https://github.com/malukenho\n[mixin interfaces]: src/Mixin/Static\n[Packagist]: http://packagist.org/packages/respect/assertion\n[Validation]: https://github.com/Respect/Validation\n[ValidationException]: https://github.com/Respect/Validation/blob/master/library/Exceptions/ValidationException.php\n[webmozart/assert]: https://github.com/webmozart/assert\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frespect%2Fassertion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frespect%2Fassertion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frespect%2Fassertion/lists"}