vendor/wikimedia/assert/README.md

   1 This package provides an alternative to PHP's `assert()` that allows for an simple and reliable way
   2 to check preconditions and postconditions in PHP code. It was proposed [as a MediaWiki RFC](https://www.mediawiki.org/wiki/Requests_for_comment/Assert),
   3 but is completely generic and can be used by any PHP program or library. It is published under the
   4 MIT license, see the COPYING file.
   5
   6 Usage
   7 -------
   8
   9 The Assert class provides several static methods for checking various kinds of assertions.
  10 The most common kind is to check the type of a parameter, typically in a constructor or a
  11 setter method:
  12
  13     function setFoo( $foo ) {
  14         Assert::parameterType( 'integer', $foo, 'foo' );
  15         Assert::parameter( $foo > 0, 'foo', 'must be greater than 0' );
  16     }
  17
  18     function __construct( $bar, array $bazz ) {
  19         Assert::parameterType( 'Me\MyApp\SomeClass', $bar );
  20         Assert::parameterElementType( 'int', $bazz );
  21     }
  22
  23 Checking parameters, or other assertions such as pre- or postconditions, is not recommended for
  24 performance critical regions of the code, since evaluating expressions and calling the assertion
  25 functions costs time.
  26
  27
  28 Rationale
  29 -----------
  30 The background of this proposal is the recurring discussions about whether PHP's `assert()`
  31 can and should be used in MediaWiki code. Two relevant threads:
  32 * [Using PHP's assert in MediaWiki code](http://www.gossamer-threads.com/lists/wiki/wikitech/275737)
  33 * [Is assert() allowed?](http://www.gossamer-threads.com/lists/wiki/wikitech/378676)
  34
  35 The outcome appears to be that
  36 * assertions are generally a good way to improve code quality
  37 * but PHP's ''assert()'' is broken by design
  38
  39 Following a [suggestion by Tim Starling](http://www.gossamer-threads.com/lists/wiki/wikitech/378815#378815),
  40 this package provides an alternative to PHP's built in `assert()`.
  41
  42 [![Build Status](https://secure.travis-ci.org/wmde/Assert.svg)](https://travis-ci.org/wmde/Assert)
  43 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/wmde/Assert/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/wmde/Assert/?branch=master)