{"id":13518952,"url":"https://github.com/webmozarts/assert","last_synced_at":"2026-01-08T13:16:49.866Z","repository":{"id":28499435,"uuid":"32015820","full_name":"webmozarts/assert","owner":"webmozarts","description":"Assertions to validate method input/output with nice error messages.","archived":false,"fork":false,"pushed_at":"2024-11-19T17:26:00.000Z","size":506,"stargazers_count":7605,"open_issues_count":44,"forks_count":148,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-05-05T16:04:43.764Z","etag":null,"topics":["hacktoberfest"],"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/webmozarts.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-03-11T12:14:36.000Z","updated_at":"2025-04-30T19:22:55.000Z","dependencies_parsed_at":"2023-02-16T22:45:24.445Z","dependency_job_id":"f5d7ca77-05e4-474d-9b81-87c7aea7679b","html_url":"https://github.com/webmozarts/assert","commit_stats":{"total_commits":194,"total_committers":71,"mean_commits":2.732394366197183,"dds":0.8041237113402062,"last_synced_commit":"f23349fa116314ad78d0cfb51228c43793860857"},"previous_names":["webmozart/assert"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webmozarts%2Fassert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webmozarts%2Fassert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webmozarts%2Fassert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webmozarts%2Fassert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webmozarts","download_url":"https://codeload.github.com/webmozarts/assert/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253817851,"owners_count":21969053,"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":["hacktoberfest"],"created_at":"2024-08-01T05:01:51.237Z","updated_at":"2026-01-08T13:16:49.860Z","avatar_url":"https://github.com/webmozarts.png","language":"PHP","funding_links":[],"categories":["PHP","Libraries"],"sub_categories":["PHP Libraries","Libraries"],"readme":"Webmozart Assert\n================\n\n[![Latest Stable Version](https://poser.pugx.org/webmozart/assert/v/stable.svg)](https://packagist.org/packages/webmozart/assert)\n[![Total Downloads](https://poser.pugx.org/webmozart/assert/downloads.svg)](https://packagist.org/packages/webmozart/assert)\n\nThis library contains efficient assertions to test the input and output of\nyour methods. With these assertions, you can greatly reduce the amount of coding\nneeded to write a safe implementation.\n\nAll assertions in the [`Assert`] class throw an `Webmozart\\Assert\\InvalidArgumentException` if\nthey fail.\n\nFAQ\n---\n\n**What's the difference to [beberlei/assert]?**\n\nThis library is heavily inspired by Benjamin Eberlei's wonderful [assert package],\nbut fixes a usability issue with error messages that can't be fixed there without\nbreaking backwards compatibility.\n\nThis package features usable error messages by default. However, you can also\neasily write custom error messages:\n\n```\nAssert::string($path, 'The path is expected to be a string. Got: %s');\n```\n\nIn [beberlei/assert], the ordering of the `%s` placeholders is different for\nevery assertion. This package, on the contrary, provides consistent placeholder\nordering for all assertions:\n\n* `%s`: The tested value as string, e.g. `\"/foo/bar\"`.\n* `%2$s`, `%3$s`, ...: Additional assertion-specific values, e.g. the\n  minimum/maximum length, allowed values, etc.\n\nCheck the source code of the assertions to find out details about the additional\navailable placeholders.\n\nInstallation\n------------\n\nUse [Composer] to install the package:\n\n```bash\ncomposer require webmozart/assert\n```\n\nExample\n-------\n\n```php\nuse Webmozart\\Assert\\Assert;\n\nclass Employee\n{\n    public function __construct($id)\n    {\n        Assert::integer($id, 'The employee ID must be an integer. Got: %s');\n        Assert::greaterThan($id, 0, 'The employee ID must be a positive integer. Got: %s');\n    }\n}\n```\n\nIf you create an employee with an invalid ID, an exception is thrown:\n\n```php\nnew Employee('foobar');\n// =\u003e Webmozart\\Assert\\InvalidArgumentException:\n//    The employee ID must be an integer. Got: string\n\nnew Employee(-10);\n// =\u003e Webmozart\\Assert\\InvalidArgumentException:\n//    The employee ID must be a positive integer. Got: -10\n```\n\nAssertions\n----------\n\nThe [`Assert`] class provides the following assertions:\n\n### Type Assertions\n\nMethod                                                   | Description\n-------------------------------------------------------- | --------------------------------------------------\n`string($value, $message = '')`                          | Check that a value is a string\n`stringNotEmpty($value, $message = '')`                  | Check that a value is a non-empty string\n`integer($value, $message = '')`                         | Check that a value is an integer\n`integerish($value, $message = '')`                      | Check that a value casts to an integer\n`positiveInteger($value, $message = '')`                 | Check that a value is a positive (non-zero) integer\n`negativeInteger($value, $message = '')`                 | Check that a value is a negative integer\n`notNegativeInteger($value, $message = '')`              | Check that a value is a non-negative integer\n`float($value, $message = '')`                           | Check that a value is a float\n`numeric($value, $message = '')`                         | Check that a value is numeric\n`natural($value, $message = '')`                         | Check that a value is a non-negative integer\n`boolean($value, $message = '')`                         | Check that a value is a boolean\n`scalar($value, $message = '')`                          | Check that a value is a scalar\n`object($value, $message = '')`                          | Check that a value is an object\n`objectish($value, $message = '')`                       | Check that a value is an object or a string of a class that exists\n`resource($value, $type = null, $message = '')`          | Check that a value is a resource\n`isInitialized($value, $property, $message = '')`        | Check that a value has an initialized property\n`isCallable($value, $message = '')`                      | Check that a value is a callable\n`isArray($value, $message = '')`                         | Check that a value is an array\n`isIterable($value, $message = '')`                      | Check that a value is an array or a `\\Traversable`\n`isCountable($value, $message = '')`                     | Check that a value is an array or a `\\Countable`\n`isInstanceOf($value, $class, $message = '')`            | Check that a value is an `instanceof` a class\n`isInstanceOfAny($value, array $classes, $message = '')` | Check that a value is an `instanceof` at least one class on the array of classes\n`notInstanceOf($value, $class, $message = '')`           | Check that a value is not an `instanceof` a class\n`isAOf($value, $class, $message = '')`                   | Check that a value is of the class or has one of its parents\n`isAnyOf($value, array $classes, $message = '')`         | Check that a value is of at least one of the classes or has one of its parents\n`isNotA($value, $class, $message = '')`                  | Check that a value is not of the class or has not one of its parents\n`isArrayAccessible($value, $message = '')`               | Check that a value can be accessed as an array\n`uniqueValues($values, $message = '')`                   | Check that the given array contains unique values\n\n### Comparison Assertions\n\nMethod                                                | Description\n----------------------------------------------------- | ------------------------------------------------------------------\n`true($value, $message = '')`                         | Check that a value is `true`\n`false($value, $message = '')`                        | Check that a value is `false`\n`notFalse($value, $message = '')`                     | Check that a value is not `false`\n`null($value, $message = '')`                         | Check that a value is `null`\n`notNull($value, $message = '')`                      | Check that a value is not `null`\n`isEmpty($value, $message = '')`                      | Check that a value is `empty()`\n`notEmpty($value, $message = '')`                     | Check that a value is not `empty()`\n`eq($value, $value2, $message = '')`                  | Check that a value equals another (`==`)\n`notEq($value, $value2, $message = '')`               | Check that a value does not equal another (`!=`)\n`same($value, $value2, $message = '')`                | Check that a value is identical to another (`===`)\n`notSame($value, $value2, $message = '')`             | Check that a value is not identical to another (`!==`)\n`greaterThan($value, $value2, $message = '')`         | Check that a value is greater than another\n`greaterThanEq($value, $value2, $message = '')`       | Check that a value is greater than or equal to another\n`lessThan($value, $value2, $message = '')`            | Check that a value is less than another\n`lessThanEq($value, $value2, $message = '')`          | Check that a value is less than or equal to another\n`range($value, $min, $max, $message = '')`            | Check that a value is within a range\n`inArray($value, array $values, $message = '')`       | Check that a value is one of a list of values\n`notInArray($value, array $values, $message = '')`    | Check that a value is not one of a list of values\n`oneOf($value, array $values, $message = '')`         | Check that a value is one of a list of values (alias of `inArray`)\n`notOneOf($value, array $values, $message = '')`      | Check that a value is not one of a list of values (alias of `notInArray`)\n\n### String Assertions\n\nYou should check that a value is a string with `Assert::string()` before making\nany of the following assertions.\n\nMethod                                              | Description\n--------------------------------------------------- | -----------------------------------------------------------------\n`contains($value, $subString, $message = '')`       | Check that a string contains a substring\n`notContains($value, $subString, $message = '')`    | Check that a string does not contain a substring\n`startsWith($value, $prefix, $message = '')`        | Check that a string has a prefix\n`notStartsWith($value, $prefix, $message = '')`     | Check that a string does not have a prefix\n`startsWithLetter($value, $message = '')`           | Check that a string starts with a letter\n`endsWith($value, $suffix, $message = '')`          | Check that a string has a suffix\n`notEndsWith($value, $suffix, $message = '')`       | Check that a string does not have a suffix\n`regex($value, $pattern, $message = '')`            | Check that a string matches a regular expression\n`notRegex($value, $pattern, $message = '')`         | Check that a string does not match a regular expression\n`unicodeLetters($value, $message = '')`             | Check that a string contains Unicode letters only\n`alpha($value, $message = '')`                      | Check that a string contains letters only\n`digits($value, $message = '')`                     | Check that a string contains digits only\n`alnum($value, $message = '')`                      | Check that a string contains letters and digits only\n`lower($value, $message = '')`                      | Check that a string contains lowercase characters only\n`upper($value, $message = '')`                      | Check that a string contains uppercase characters only\n`length($value, $length, $message = '')`            | Check that a string has a certain number of characters\n`minLength($value, $min, $message = '')`            | Check that a string has at least a certain number of characters\n`maxLength($value, $max, $message = '')`            | Check that a string has at most a certain number of characters\n`lengthBetween($value, $min, $max, $message = '')`  | Check that a string has a length in the given range\n`uuid($value, $message = '')`                       | Check that a string is a valid UUID\n`ip($value, $message = '')`                         | Check that a string is a valid IP (either IPv4 or IPv6)\n`ipv4($value, $message = '')`                       | Check that a string is a valid IPv4\n`ipv6($value, $message = '')`                       | Check that a string is a valid IPv6\n`email($value, $message = '')`                      | Check that a string is a valid e-mail address\n`notWhitespaceOnly($value, $message = '')`          | Check that a string contains at least one non-whitespace character\n\n### File Assertions\n\nMethod                              | Description\n----------------------------------- | --------------------------------------------------\n`fileExists($value, $message = '')` | Check that a value is an existing path\n`file($value, $message = '')`       | Check that a value is an existing file\n`directory($value, $message = '')`  | Check that a value is an existing directory\n`readable($value, $message = '')`   | Check that a value is a readable path\n`writable($value, $message = '')`   | Check that a value is a writable path\n\n### Object Assertions\n\nMethod                                                | Description\n----------------------------------------------------- | --------------------------------------------------\n`classExists($value, $message = '')`                  | Check that a value is an existing class name\n`subclassOf($value, $class, $message = '')`           | Check that a class is a subclass of another\n`interfaceExists($value, $message = '')`              | Check that a value is an existing interface name\n`implementsInterface($value, $class, $message = '')`  | Check that a class implements an interface\n`propertyExists($value, $property, $message = '')`    | Check that a property exists in a class/object\n`propertyNotExists($value, $property, $message = '')` | Check that a property does not exist in a class/object\n`methodExists($value, $method, $message = '')`        | Check that a method exists in a class/object\n`methodNotExists($value, $method, $message = '')`     | Check that a method does not exist in a class/object\n\n### Array Assertions\n\nMethod                                             | Description\n-------------------------------------------------- | ------------------------------------------------------------------\n`keyExists($array, $key, $message = '')`           | Check that a key exists in an array\n`keyNotExists($array, $key, $message = '')`        | Check that a key does not exist in an array\n`validArrayKey($key, $message = '')`               | Check that a value is a valid array key (int or string)\n`count($array, $number, $message = '')`            | Check that an array contains a specific number of elements\n`minCount($array, $min, $message = '')`            | Check that an array contains at least a certain number of elements\n`maxCount($array, $max, $message = '')`            | Check that an array contains at most a certain number of elements\n`countBetween($array, $min, $max, $message = '')`  | Check that an array has a count in the given range\n`isList($array, $message = '')`                    | Check that an array is a non-associative list\n`isNonEmptyList($array, $message = '')`            | Check that an array is a non-associative list, and not empty\n`isMap($array, $message = '')`                     | Check that an array is associative and has strings as keys\n`isNonEmptyMap($array, $message = '')`             | Check that an array is associative and has strings as keys, and is not empty\n\n### Function Assertions\n\nMethod                                    | Description\n------------------------------------------| -----------------------------------------------------------------------------------------------------\n`throws($closure, $class, $message = '')` | Check that a function throws a certain exception. Subclasses of the exception class will be accepted.\n`isStatic($closure, $message = '')`       | Check that a function is static.\n`notStatic($closure, $message = '')`    | Check that a function is not static.\n\n### Collection Assertions\n\nAll of the above assertions can be prefixed with `all*()` to test the contents\nof an array or a `\\Traversable`:\n\n```php\nAssert::allIsInstanceOf($employees, 'Acme\\Employee');\n```\n\n### Nullable Assertions\n\nAll of the above assertions can be prefixed with `nullOr*()` to run the\nassertion only if the value is not `null`:\n\n```php\nAssert::nullOrString($middleName, 'The middle name must be a string or null. Got: %s');\n```\n\n### Extending Assert\n\nThe `Assert` class comes with a few methods, which can be overridden to change the class behaviour. You can also extend it to\nadd your own assertions.\n\n#### Overriding methods\n\nOverriding the following methods in your assertion class allows you to change the behaviour of the assertions:\n\n* `public static function __callStatic($name, $arguments)`\n  * This method is used to 'create' the `nullOr` and `all` versions of the assertions.\n* `protected static function valueToString($value)`\n  * This method is used for error messages, to convert the value to a string value for displaying. You could use this for representing a value object with a `__toString` method for example.\n* `protected static function typeToString($value)`\n  * This method is used for error messages, to convert a value to a string representing its type.\n* `protected static function strlen($value)`\n  * This method is used to calculate string length for relevant methods, using the `mb_strlen` if available and useful.\n* `protected static function reportInvalidArgument($message)`\n  * This method is called when an assertion fails, with the specified error message. Here you can throw your own exception, or log something.\n\n## Static analysis support\n\nWhere applicable, assertion functions are annotated to support Psalm's\n[Assertion syntax](https://psalm.dev/docs/annotating_code/assertion_syntax/).\nA dedicated [PHPStan Plugin](https://github.com/phpstan/phpstan-webmozart-assert) is\nrequired for proper type support.\n\nAuthors\n-------\n\n* [Bernhard Schussek] a.k.a. [@webmozart]\n* [The Community Contributors]\n\nContribute\n----------\n\nContributions to the package are always welcome!\n\n* Report any bugs or issues you find on the [issue tracker].\n* You can grab the source code at the package's [Git repository].\n\nLicense\n-------\n\nAll contents of this package are licensed under the [MIT license].\n\n[beberlei/assert]: https://github.com/beberlei/assert\n[assert package]: https://github.com/beberlei/assert\n[Composer]: https://getcomposer.org\n[Bernhard Schussek]: https://webmozarts.com\n[The Community Contributors]: https://github.com/webmozart/assert/graphs/contributors\n[issue tracker]: https://github.com/webmozart/assert/issues\n[Git repository]: https://github.com/webmozart/assert\n[@webmozart]: https://twitter.com/webmozart\n[MIT license]: LICENSE\n[`Assert`]: src/Assert.php\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebmozarts%2Fassert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebmozarts%2Fassert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebmozarts%2Fassert/lists"}