php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #31250 "Try" is a Control Structure, not an Object
Submitted: 2004-12-22 17:22 UTC Modified: 2007-08-20 14:26 UTC
From: rampant at gmail dot com Assigned:
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS: WinXP
Private report: No CVE-ID: None
Anyone can comment on a bug. Have a simpler test case? Does it work for you on a different platform? Let us know!
Just going to say 'Me too!'? Don't clutter the database with that please !
Your email address:
MUST BE VALID
Solve the problem:
1 + 12 = ?
Subscribe to this entry?

 
 [2004-12-22 17:22 UTC] rampant at gmail dot com
Description:
------------
The documentation for "try" and "catch" is in the "Classes and Objects" chapter of the manual. Throw, Try and Catch control the flow of execution much like "if" does. They make use of the Exception class, just as "if" works on booleans - and just as if is not put into the "Types" chapter, we shouldn't expect to find try and catch in the "Classes and Objects" chapter.

Expected result:
----------------
http://www.php.net/manual/en/language.control-structures.php

try, catch and throw would ba added to the list on the above page, and the exceptions content would be moved there from the http://www.php.net/manual/en/language.oop5.exceptions.php page.



Actual result:
--------------
Exceptions are hidden away in the Classes and Objects chapter.

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2004-12-29 13:47 UTC] vrana@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.

Moved directly under the Language Reference.

(Leaving open to not forget to move user notes after manual rebuild.)
 [2005-01-04 09:29 UTC] vrana@php.net
Notes moved.
 [2006-08-08 09:43 UTC] cynic@php.net
try/catch is still not documented in the Control Structures chapter. I believe it should be there as it /is/ a control structure, and I looked for it in that section. Can we reopen the bug?

Also, what is present in the Exceptions chapter just scratches on the surface. Contrary to my expectations (and I'm inclined to believe this is a common mistake), try doesn't introduce a new scope. This means that this works (for some definition of works):

try {
 $x = new x;
 $x->throwsSometimes();
} catch (Exception $e) {}
$x->stillExistsInUnknownState();

as opposed to scoped locks, which require an intermediate function (because of that separate scope).

Also, the existing documentation completely bypasses the issue of exceptions thrown while the stack is unwinding (or whatever the PHP equivalent is). Which part of the reference says what will happen here?

class x0 extends Exception {};
class x1 extends Exception {};
class throwsindestructor { 
 function __destruct() {
  throw new x0;
 }
}
function f() { 
 $t = new throwsindestructor; 
 throw new x1; 
}
f(); 

Point being, a handful of examples cannot replace a reference manual, and a reference must be complete. A handful of examples is just that, you'll never cover enough ground, there'll be a lot of redundancy, and too much ambiguity. See the user notes at http://www.php.net/manual/en/language.exceptions.php for a list of things programmers look for in the (absent) try/catch reference.
 [2007-08-20 14:26 UTC] vrana@php.net
Variables scope is described at http://www.php.net/manual/en/language.variables.scope.php.
Description of exceptions inside descructors are at http://www.php.net/manual/en/language.oop5.decon.php.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Thu Oct 31 23:01:28 2024 UTC