php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

Doc Bug #63845 Misleading example code
Submitted: 2012-12-24 10:08 UTC Modified: 2013-01-11 11:11 UTC
Votes:1
Avg. Score:1.0 ± 0.0
Reproduced:1 of 1 (100.0%)
Same Version:1 (100.0%)
Same OS:1 (100.0%)
From: kander at gmail dot com Assigned: googleguy (profile)
Status: Closed Package: Documentation problem
PHP Version: 5.4.10 OS:
Private report: No CVE-ID: None
View Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
If you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: kander at gmail dot com
New email:
PHP Version: OS:

 

 [2012-12-24 10:08 UTC] 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.

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2012-12-24 23:35 UTC] googleguy@php.net
-Assigned To: +Assigned To: googleguy
 [2012-12-24 23:35 UTC] 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-27 14:39 UTC] 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-30 00:00 UTC] googleguy@php.net 
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.
 [2013-01-11 11:09 UTC] googleguy@php.net 
Automatic comment from SVN on behalf of googleguy
Revision: http://svn.php.net/viewvc/?view=revision&amp;revision=329077
Log: Updated PDO error handling chapter with new example and added note to reflect PDO::__construct behavior.

This fixes Bug #63845 in that a note is added to inform the user that PDO::__construct will always throw an exception if the connection fails.
A new example is also added to reflect that even when the PDO::ATTR_ERRMODE is set in the constructor, and the connection fails, a PDOException will still be thrown.
 [2013-01-11 11:11 UTC] googleguy@php.net 
This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.
 [2013-01-11 11:11 UTC] googleguy@php.net
-Status: Assigned +Status: Closed
 
PHP Copyright © 2001-2026 The PHP Group
All rights reserved. 		Last updated: Tue Oct 06 09:00:02 2026 UTC