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

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

Post Reply
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

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

Post 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.
User avatar
Jenk
DevNet Master
Posts: 3587
Joined: Mon Sep 19, 2005 6:24 am
Location: London

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

Post by Jenk »

My choice would be flag as deprecated for a release or two, then remove it.
User avatar
Maugrim_The_Reaper
DevNet Master
Posts: 2704
Joined: Tue Nov 02, 2004 5:43 am
Location: Ireland

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

Post 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!
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

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

Post 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 :)
User avatar
Jenk
DevNet Master
Posts: 3587
Joined: Mon Sep 19, 2005 6:24 am
Location: London

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

Post 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?
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

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

Post 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.
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

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

Post 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.
Post Reply