25

I was going through the list of predefined Exceptions in PHP and I noticed the DomainException. Anyone know what does DomainException mean? Does it mean failed data model validation?

oscarkuo
  • 10,431
  • 6
  • 49
  • 62

3 Answers3

24

There's a pretty hilarious discussion here about how no one seems to know what is means:

http://bugs.php.net/bug.php?id=47097

From the end of that link:

Domain means data domain here. That is a DomainException shall be thrown whenever a value does not adhere to a defined valid data domain. Examples:

  • 0 is not in the domain for division.
  • Foo is not in the domain for weekdays.

The first is different from out of range and alike, but you could use InvalidParameter in case it is actually a parameter to the function that performs the division. If it is a value calculated inside the function prior to executing the division and then a pre-conditon check throws instead of executing the division, then it becomes a DomainException.

Timo Tijhof
  • 10,032
  • 6
  • 34
  • 48
karim79
  • 339,989
  • 67
  • 413
  • 406
  • I like throw it in a `default` path of a switch case that has no defaults. Say I have a factory of "pieces" for a board game, and I can create either an "emperor piece" or an "ambassador" or a "pawn piece". In the factory class I have the `->create( $typeAsString )` method. Then I have a switch for "emperor", "ambassador", "pawn" and default. In the default I throw a DomainException. – Xavi Montero May 22 '14 at 22:04
7

The description of RangeException is a bit more helpful:

Exception thrown to indicate range errors during program execution. Normally this means there was an arithmetic error other than under/overflow. This is the runtime version of DomainException.

I think it is applicable to non-arithmetic too, e.g. see this user comment.

For example, if you expect a value to be in the set {'jpeg', 'png', 'gif', 'bmp'} and you receive something else like 'foo', it's a good candidate for a DomainException (logic) / RangeException (runtime). I'm pretty sure you could think of many other use cases.


Also, I just found this useful article, which provide more thorough explanations than php.net: How to use built-in SPL exception classes for better error handling

Gras Double
  • 15,901
  • 8
  • 56
  • 54
  • I’d use `InvalidArgumentException` here. – Martin Bean Sep 16 '18 at 12:00
  • 1
    @MartinBean I wouldn't: `InvalidArgumentException` extends `LogicException`. [`LogicException` should lead directly to a fix in your code](https://secure.php.net/manual/en/class.logicexception.php); that is not the case here, since `'foo'` is a valid type of input (string); it is acceptable code-wise, but it is not acceptable domain-wise, because it is not in included in the set of values defined by our domain rules (*our images can be just: jpeg, png, gif, bmp*) and doesn't mean anything for us. There is no bug to fix in the code, but just edge-cases to care of. – Kamafeather Nov 28 '18 at 18:33
  • @Kamafeather _but just edge-cases to care of._ That sounds like something that needs fixing to me (validation)… – Martin Bean Nov 29 '18 at 11:15
  • Mmmh ... Then I probably can't wrap my head around what's the difference between `LogicException` and `RuntimeException`. PHP documentation is quite brief/subtle/unclear to me; if this one is a `LogicException`, as you say, when should one use `RuntimeException`s like `RangeException`? – Kamafeather Nov 29 '18 at 12:37
  • Trying to rephrase: if `'foo'` is an invalid value (that e.g. comes from outside and we have no control on) that is created&provided at **runtime**, you say a `LogicException` should be used; what are `RuntimeException`s for then? – Kamafeather Nov 29 '18 at 12:39
  • As a dynamically typed language, PHP allows pretty much anything to be passed as an argument. You would use an `InvalidArgumentException` to type-check that you're not, for example, being passed a string where you expect an array, assuming that type coercion is not appropriate. Type-hinting with strict declarations somewhat obviates the need for this. A string is a valid argument, so `DomainException` is probably more appropriate. If PHP allowed us to define enumerated types, then 'foo' would be an invalid argument, but then arguably so would 'jpeg' be as a string. – Duncan Apr 09 '19 at 03:49
  • Bear in mind that both `DomainException` and `InvalidArgumentException` extend `LogicException` so both of them indicate something that needs to be fixed in code, and it is pointless to debate the correct usage based on that. Generally, just pick the one that you feel fits your use case better and be consistent about it. It's not like these exceptions are ever going to be thrown in production, right? ;) – Duncan Apr 09 '19 at 03:54
  • @Kamafeather `LogicException` is for checking pre-conditions of your function, `RuntimeException` is for errors during program execution. The difference lies in where the data comes from. If your function is called with unexpected data, it's logic; if unexpected data is returned to your function, it's runtime. In your example, if `'foo'` came from user input or a web service, it would be a `RangeException` because you have no control over it. If you then blindly passed that value to another piece of code, it would be a `DomainException` in *that* function because you forgot to validate it. – Duncan Apr 09 '19 at 04:07
3

This kind of exception should be used to inform about domain errors in mathematical sense.

See domain of a function.

For example, the square root function will only be defined for positive numbers (unless you're using complex numbers...)

Greg
  • 316,276
  • 54
  • 369
  • 333