Project

Profile

Help

Feature #4789

Throw exceptions instead of silently returning null

Added by Peter Jan 14 days ago. Updated 7 days ago.

Status:
New
Priority:
Normal
Category:
Documentation
Start date:
2020-10-08
Due date:
% Done:

0%

Estimated time:
Found in version:
1.2.1
Fixed in version:

Description

I'm trying to find the namespace of an XML file with:

$saxonProc = new SaxonProcessor();
$xPathProcessor = $saxonProc->newXPathProcessor();
$xPathProcessor->setContextFile($file->getPathname());
$item = $xPathProcessor->evaluateSingle('/*/namespace::*[name()=\'\']');

According to the documentation:

evaluateSingle(string $xpathStr)
Compile and evaluate an XPath expression whose result is expected to be a single item, with a given context item. The expression is supplied as a character string, and the result returned as an XdmItem.

So the return value is expected to be an XdmItem. However, when the expression could not be evaluated, it can also return null.

It would be great if exceptions can be thrown when these situations occur. (I expect these can be applied on other functions as well?), so these exceptions can be caught with a try-catch block. Now, the return type is not documented, but 'silently' returning a null value is also not desirable.

History

#1 Updated by Michael Kay 14 days ago

  • Assignee set to O'Neil Delpratt

I think this is more of a documentation issue than anything else. Your XPath expression is perfectly valid and returns an empty sequence. The interface documentation for evaluateSingle should be clearer about exactly what happens when the XPath result is not a single item (i.e. when it's empty, or when there's more than one item in the result).

#2 Updated by O'Neil Delpratt 14 days ago

  • Category set to Documentation

Hi, in the first instance I will follow through with comment #1 by updating the documentation for this method:

return null if the expression returns an empty sequence. If the expression returns a sequence of more than one item, any items after the first are ignored.

If I was to always expect to find a value, then maybe throwing an exception would be more useful. We do welcome suggestions, but I would think that returning a null is valid in this situaton as it is not an error for the XPath expression nothing is selected. Here we represent the empty sequence with a null.

#3 Updated by Peter Jan 7 days ago

Hi, thank you both for your response.

Im perfectly fine with just updating the documentation, that will help. I'm not sure if this is limited to the evaluateSingle method, but ill leave that to your estimate.

If you can let me know when this has been resolved, Ill send a PR to https://github.com/JetBrains/phpstorm-stubs.

Please register to edit this issue

Also available in: Atom PDF