Getting Started With Contracts - axiom82/PHP-Contract GitHub Wiki

PHP-Contract is a simple solution for the lack of type-hinting capabilities found in PHP. It has a broad spectrum of use-cases, and can be used with versatility throughout your PHP applications.

PHP-Contract allows the developer to require certain data at each step of a process. It’s a formal introduction to forming an agreement between your application and its class methods, in order to ensure the proper flow and function inside of each individual scope.

The library offers method chaining for a simple and sleek integration within your existing code, and the power of the code can make a big impact on the size and stability of your checks. Really what the library does is put the power of confidence in your hands, for you, the developer, and your company, who demands the best in your programming patterns.

Let’s take a quick look at the beginning. In order to get started, let’s make a contract.

<?php

require_once('./contract.php');
$contract = new Contract();

?>

Naturally, a contract relies on creating terms in order to form meaningful agreements. One of your goals may be to check for a valid email address. Here is what you can do.

<?php

$contract = new Contract();
$contract->term('email', '[email protected]')->email();

?>

In the above code, we created a contract and assigned the newly instantiated Contract object into a variable for later usage. Right away, we use the object, via $contract, to create a new term for our contract. In this case, we created a term named email and supplied a value in the second parameter. Typically, we would be specifying a value stored in a variable, such as in this code:

<?php

$email = '[email protected]';
$contract = new Contract();
$contract->term('email', $email)->email();

?>

In most use cases, variables are used, including local variables and variables passed through the arguments of a method. Here is a more formal example, using the same Contract above, but inside of a class method.

<?php

class Test {

    public function checkUserEmail($userEmail){

        $contract = new Contract();
        $contract->term('userEmail')->email();
        $contract->metOrThrow();

    }

}

?>

Notice that when a Contract is formed inside of a method, those variables found in the arguments list of the method are already creating for you; the Contract creates a Term for each of the method’s arguments. This is very useful in coding contracts, because the majority of terms are prepared for you – just add your definitions.

And, for creating terms based on your own variables, simply supply the second parameter of the Contract::term() method your value:

<?php

$contract->term('myTerm', $myTermValue);

?>

Working with PHP-Contract is elegant, in that you can chain your term definitions in a logical sequence. For example:

<?php

$value = 'not 12';
$contract = new Contract();
$contract->term('dozen', $value)->required()->natural()->equals(12);
$contract->metOrThrow(); /* Throws an exception on Contract_Term::equals(); */

?>

In the above example, we created a term named dozen, and specified definitions for its value to be required, that it be a natural number, and that the value equals 12. The contract fails on the equals test, because the value does not equal 12, as specified in the term.

Also, notice how the Contract is calling another method, Contract::metOrThrow(). This method scans each and every term and its definitions, and throws an exception when the value of a term has not met its term definitions.

Next, we’ll be talking about the types of terms and creating terms with PHP-Contract.