Doc #63845 [Asn]: Misleading example code

Edit report at https://bugs.php.net/bug.php?id=63845&edit=1 ID: 63845 Updated by: googleguy@php.net Reported by: kander at gmail dot com Summary: Misleading example code Status: Assigned Type: Documentation Problem Package: Documentation problem PHP Version: 5.4.10 Assigned To: googleguy Block user comment: N Private report: N New Comment: How are they not handled in the case of a connection failure, exactly? The constructor throws exceptions despite the default error mode because if the connection fails its important for the user to be made aware of that rather than failing silently. Beyond that the error mode is taken into consideration with each call to PDO and its extending classes. In the example provided the Exception is caught if the connection fails. So I'm not sure what you mean by it not being handled properly. Previous Comments: ------------------------------------------------------------------------ [2012-12-27 14:39:22] kander at gmail dot com I'm not sure your comment covers the behaviour of PDO::__construct fully. You point out that its behavior is a combination of always throwing an exception, and observing PDO's default error mode of PDO::ERRMODE_SILENT. However what I'm seeing is that in addition to throwing the exception, it also raises a regular PHP warning. This means that the error mode is not yet respected during the construction phase. Following the examples in the manual (wrapping the constructor in a try/catch block) leads to these warnings not being handled properly in case of a connection failure. ------------------------------------------------------------------------ [2012-12-24 23:35:06] googleguy@php.net While I can understand that you may feel the example is misleading, the information you're asking for is documented in the PDO::__construct() method page at http://php.net/pdo.construct.php#refsect1-pdo.construct- errors. So it's incomplete, but not really misleading the user since the behavior is correct. The Errors/Exceptions section of that page does state "PDO::__construct() throws a PDOException if the attempt to connect to the requested database fails.", which by itself may seem confusing until coupled with the first line of the second paragraph on the page http://php.net/pdo.error-handling where it is stated that PDO::ERRMODE_SILENT is the default error mode for PDO. Meaning that while the construct will always throw an exception if the connection fails PDO is by default not going to throw exceptions from anywhere else unless you specifically put it in exception mode. This could certainly be clarified further in the "Errors and error handling" page for PDO. I too found it a bit confusing at first. So this is a good point. I will assign this ticket to myself and review the page for better examples and to reiterate that PDO will throw an exception from the construct if the connection fails. ------------------------------------------------------------------------ [2012-12-24 10:08:01] kander at gmail dot com Description: ------------ --- From manual page: http://www.php.net/pdo.error-handling --- The example presented does not match the actual behavior. Since setting the error mode happens AFTER the construction of the object, it has no influence on what happens during the construction of the object. In fact, PDO always (as far as I can see) throws an exception AND emits a warning upon connection failure. Only after that does setting the error mode influence the behavior. Test script: --------------- <?php // Literally the example as presented on the manual page, with comments. $dsn = 'mysql:dbname=testdb;host=127.0.0.1'; $user = 'dbuser'; $password = 'dbpass'; try { // Exception is thrown and warning is raised: $dbh = new PDO($dsn, $user, $password); // We never get to the next line: $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); } catch (PDOException $e) { // Instead, we end up handling the exception. echo 'Connection failed: ' . $e->getMessage(); } ?> Expected result: ---------------- I expect the manual to explain that PDO::__construct() always throws an exception and raises a warning, and that only behavior subsequent to the setAttribute call is affected (obviously). A recommendation on how to handle connection errors would be appreciated. Actual result: -------------- See the test script's comments. ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=63845&edit=1