Page 1 of 1

Renaming Exceptions in a public domain project (= PITA!)

Posted: Sun May 11, 2008 5:23 am
by Chris Corbyn
I guess this is a straight answer of "sucks to be you" but if you've got a product that thousands of people are using and you rename an Exception how best would you deprecate the old name?

Since a catch() block requires a type-hint you basically have to make your *new* exception subclass the old one to avoid breaking peoples' code. If the aim was to deprecate the old name then this is pretty hypocritical (I'm having a blonde day and can't think of a better word!).

So are the only two choices really:

a) Just get rid of the old one with immediate effect and let people change their code when it breaks.
b) Subclass the old Exception for a while and tag it as deprecated.

Every other sort of refactoring is easy as far as deprecation is concerned since you can keep the old method/class marked as @deprecated but add "wrapper code" to it in the interim.

Re: Renaming Exceptions in a public domain project (= PITA!)

Posted: Sun May 11, 2008 9:28 pm
by Jenk
My choice would be flag as deprecated for a release or two, then remove it.

Re: Renaming Exceptions in a public domain project (= PITA!)

Posted: Mon May 12, 2008 3:12 am
by Maugrim_The_Reaper
Flag as deprecated for a very long time...preferably until at least one new major release with major version number increment is released. Then they can't complain so much ;).

Adding it to the release notes would be polite!

Re: Renaming Exceptions in a public domain project (= PITA!)

Posted: Tue May 13, 2008 3:16 am
by Chris Corbyn
This relates to Swift Mailer. In the current version there was the concept of "Connection" objects. In the new version they have been replaced with broader-scoped "Transport" objects. As a result ConnectionException is now called TransportException.

This is a major release and a lot has changed so I'm not so worried. What I am concerned about is the ability (or lack thereof) to provide compatability stubs where this is concerned. Classes which existed in v3 but not in v4 will be provided in a series of compat stubs and will simply "wrap" the new functionality into the old API. But exceptions are the one thing you can't make wrappers for like that. I guess I'll just have to note the few things the compat stubs cannot cover.

Cheers :)

Re: Renaming Exceptions in a public domain project (= PITA!)

Posted: Thu May 15, 2008 4:54 am
by Jenk
Can you not just renamed the current ConnectionException to TransportException, then extend with:

Code: Select all

class ConnectionException extends TransportException {
  public function __construct ($fooArgIfNeeded) {
    $this->deprecated();
    parent::__construct($fooArgIfNeeded);
  }
}
Or override the message setter?

Re: Renaming Exceptions in a public domain project (= PITA!)

Posted: Thu May 15, 2008 5:02 am
by Chris Corbyn
That won't work unfortunately.

Code: Select all

class ConnectionException extends TransportException {
}
 
try {
  throw new TransportException('Foo');
} catch (ConnectionException $e) {
  //No thanks, nothing caught
}


I'm using autoloading in the new version so may take advantage. If the compat file is included (which it will need to be if the stubs can be used) then I'll just declare:

Code: Select all

class ConnectionException extends Exception {
}
 
class TransportException extends ConnectionException {
}
If I can intercept what the autoloader *would* load by explicitly declaring these classes in the compat stub then I can probably solve the issue.

Re: Renaming Exceptions in a public domain project (= PITA!)

Posted: Thu May 15, 2008 6:26 pm
by Ambush Commander
Compatibility stub sounds like the best way to go. Be sure to have your code throw E_NOTICEs if the deprecated stub is being used. Nothing like an exception that's been silently deprecated for the last four releases.