What's the preferred way of throwing exceptions in Magento?

Question

All of the following methods are used in Magento core so which one is the preferred (or the latest "best practice") way?

• Mage::throwException('Some Message') - 732 Usages
• throw new Exception('Some Message') - 419 Usages
• throw Mage::exception('Vendor_Module', 'Some Message') - 94 Usages
  _{(need to create a Vendor_Module_Exception class)}

Answer 1

The call Mage::throwException is used to throw exceptions of the specific Mage_Core_Exception variety. These are generally used to present error messages to the end user. For examples of this, do a quick search for Mage::throwException in the Mage_Checkout module, you'll find many instances where the error message is actually being translated before it's thrown, as it's ultimately going to be added to the session object and displayed to the user on the resulting page.

Using new Exception or something like new My_Custom_Exception would normally be where you are throwing errors internal to the application, errors which most likely should never be displayed to the end user. Maybe you catch these and handle them gracefully (good use for a custom exception type in some cases), or other times they end out caught, logged and terminate the request with a more generic error message being displayed to the user.

I've never personally used Mage::exception but it appears to be an attempt to pattern having a unique exception type for each module. There would be no harm done in using it, as it is essentially a factory which returns an exception instance for the given module, although (at the time of this writing) it does not implement any support for such things as overrides.

Answer 2

You've done the hard part, finding out how often they're used :)

tl;dr: IMHO, you should use Mage::throwException most often, falling back to Mage::exception when you need to raise an exception type from outside of the scope of your module, if for no other reason than the session messaging ability and the fact that you don't have to type throw new in front of it.

Here's the breakdown:

• Mage::throwException is essentially a wrapper for Mage_Core_Exception($message) with the additional functionality of being able to add the exception to a session via a getSingleton call chained with addMessage
• new Exception() is the core PHP way to throw an exception, but requires you to use the throw keyword and is probably the slightest big more "performant" as the other two are wrappers with extra functionality.
• As mentioned, Mage::exception is a wrapper as well, but has the benefit of allowing you to instantiate your own exception class. This is really helpful if you're a plugin developer and need to make custom logs for exceptions, separately, without the functionality that logException provides (e.g., no stack trac) or want to make an API call on exception, etc. It's also handy when you want to throw an exception of a differing class type, for instance, what happens in Mage_Paypal, frequently raising a Mage_Core exception type.