In the last chapter, we discussed about ‘CSPRNG’ functions with examples. In this chapter, we are going to discuss about PHP 7 Exceptions with Expectations that are added to PHP 7. ‘Expectations’ are the enhancements, which are backward compatible with the existing ‘assert ()’ function of PHP 5.x.
Expectations in PHP7
Expectations are enhancements to the existing ‘assert ()’ function. They permit for zero-cost assertions in code i.e. into production and help to throw custom exceptions when the assertion fails. The old API i.e. the ‘assert ()’ function is now a language construct in PHP 7 that allows the first parameter to be an expression as compared to being a string to be evaluated or a Boolean value that is to be tested.
Directives for assert () function and its configuration
| S No. | Directive | Default Value | Description of Possible Values |
| 1. | zend.assertions | 1 | Value as 1 à It will generate and execute code i.e. in development mode. Value as 0 à It will generate code but act only at runtime. Value as -1 àIt will not generate code at all i.e. in production mode. |
| 2. | assert.exception | 0 | Value as 1 à It will throw an exception when the assertion fails. It will either throw an object that is provided as the exception or throw a new AssertionError object in case an exception was not provided. Value as 0 à It will use or generate a Throwable object as described above, but in this case it will only generate a warning based on that object rather than throwing it as exception. It is compatible with PHP 5.x behaviour. |
Parameters
- Assertion à In PHP 5.x, it must be either a Boolean value under test or a string to be evaluated. However in PHP 7, it may also be any expression that returns a value. This returned value is executed to procure the result that decides whether the assertion test has passed or failed.
- Description à If the assertion fails, it is an optional description that can be included to display in the failure message as shown below.
- Exception à In PHP 7, the second parameter of the assert function can be a Throwable object instead of a description string as shown below. When the assertion fails and the exception configuration directive is enabled, then this object in the second parameter will be thrown. We can understand this better with the help of following example.
Return Values
- The return value is FALSE, if the assertion is false.
- The return value is TRUE otherwise.
PHP 7 Example to throw Exception where assert.exception directive is enabled (i.e. value is 1)
Explanation of Code
- Here, first of all we are enabling ‘exception’ directive after assigning it a value of 1.
- Next, we are defining a ‘CustomExceptionClass’ class that extends the AssertionError class which is a Throwable exception class. This class has a function ‘printError ()’ that prints strings as “This is CustomExceptionClass that extends AssertionError.\n” when called through a class object.
- Lastly, we are using ‘assert (arg1, arg2)’ function where we are passing two parameters. The first parameter is the Boolean value as ‘false’ that is passed so that the assertion fails and the second parameter is the Throwable class (here ‘CustomExceptionClass’) that has a custom message as “This is a custom exception Message!”. This Throwable class was defined in the previous step.
Output
When we execute the above PHP 7 program, we will observe the following output. In the output, we can see the custom message displayed along with the Assertion failure stack trace details.
PHP 7 Example to display Description where assert.exception is enabled (i.e. value is 1)
Explanation of Code
- Here, first of all we are enabling ‘exception’ directive after assigning it a value of 1.
- Lastly, we are using ‘assert (arg1, arg2)’ function, where we are passing two parameters. The first parameter is the Boolean value as ‘false’, so that the assertion fails and the second parameter is the string that is a custom message as “This is a custom exception Message!”. This description should be displayed when the assertion fails.
Output
When we execute the above PHP 7 program, we will observe the following output. In the output, we can see the custom message displayed along with the Assertion failure stack trace details.
PHP 7 Example to throw Exception where zend.assertions directive is enabled (i.e. value is 1)
Explanation of Code
- Here, first of all we are enabling ‘assertions’ directive after assigning it the value as 1.
- Next, we are defining a ‘CustomExceptionClass’ class that extends AssertionError class which is a Throwable exception class. This class has a function ‘printError ()’ that prints string as “This is CustomExceptionClass that extends AssertionError.\n” when called through a class object.
- Lastly, we are using ‘assert (arg1, arg2)’ function where we are passing two parameters. The first parameter is the Boolean value as ‘false’ that is passed so that the assertion fails and the second parameter is the Throwable class (here ‘CustomExceptionClass’) that has a custom message as “This is a custom exception Message!”. This Throwable class was defined in the previous step.
Output
When we execute the above PHP 7 program, we will observe the following output. In the output, we can see the custom message displayed along with the Assertion failure stack trace details.
PHP 7 Example to display Description where zend.assertions is enabled (i.e. value is 1)
Explanation of Code
- Here, first of all we are enabling ‘assertions’ directive after assigning it the value as 1.
- Lastly, we are using ‘assert (arg1, arg2)’ function where we are passing two parameters. The first parameter is the Boolean value as ‘false’ that is passed so that the assertion fails and the second parameter is the string that is a custom message as “This is a custom exception Message!”. This description should be displayed when the assertion fails.
Output
When we execute the above PHP 7 program, we will observe the following output. In the output, we can see the custom message displayed on the console. This is to be noted that there is a not stack trace displayed as in the case of ‘assert.exception’ directive.
PHP 7 Example to throw Exception where zend.assertions directive is disabled (i.e. value is 0)
Explanation of Code
- Here, first of all we are disabling ‘assertions’ directive after assigning it a value of 0.
- Next, we are defining a ‘CustomExceptionClass’ class that extends AssertionError class, which is a Throwable exception class. This class has a function ‘printError ()’ that prints string as “This is CustomExceptionClass that extends AssertionError.\n” when called through a class object.
- Lastly, we are using ‘assert (arg1, arg2)’ function, where we are passing two parameters. The first parameter is the Boolean value as ‘false’ that is passed so that the assertion fails and the second parameter is the Throwable class (here ‘CustomExceptionClass’) that has a custom message as “This is a custom exception Message!”. This Throwable class was defined in the previous step.
Output
When we execute the above PHP 7 program, we will observe the following output. In the output, we can see the message which is printed by the function ‘printError ()’. Here, no exception was thrown as zend.assertions directive was disabled.
We can observe the similar output in case we disable the assert.exception directive i.e. we are setting the value as zero.
Source Code for this article is here Expectation Handling in PHP7
Conclusion
In this chapter, we explored ‘Expectations’ along with AssertionError Throwable exception class and description string that is added to PHP 7 as oppose to PHP 5.x. In the coming chapter of this tutorial, we are going to discuss errors handling that has been added to PHP7.
