[dev] BC break IMP_6_2 API.

[Michael M Slusarz]

Quoting Michael J Rubinsky <mrubinsk at horde.org>:

> I hear what you are saying, but this is still an API break. I could  
> easily add phpdoc to that API method explaining the value of the  
> bitmask in IMP 6.1.x before IMP 6.2 is released. Regardless if it  
> was the correct way to originally implement it or that it wasn't  
> documented fully doesn't make it NOT a BC break.

This is probably a fundamental disagreement between you and I when it  
comes to what makes an API then.  For me, the API is what is defined  
in the documentation.  It doesn't matter what was actually returned as  
of 6.0.0.  Because it most certainly is not the job of someone using  
the API to have to go back and trace the code manually to figure this  
value out.

>> but allows existing code to function until that code can be fixed.
>>
>> As a replacement, the question becomes: is this data obtainable  
>> through other existing API means (e.g. through the Imap_Client  
>> object)?  Or do we need to add an additional array key - such as  
>> 'subscribed' - to the return of mailboxList?
>
> I need to be able to determine if the mailbox is subscribed or not.  
> Reading the phpdoc of Horde_Imap_Client_Mailbox I don't see any way  
> to get that data from the object. Besides, we shouldn't be relying  
> on objects being passed via the API when at all possible. So, how  
> about a 's' array key?

I'm not talking about Horde_Imap_Client_Mailbox.  I'm talking about  
Horde_Imap_Client.  This object is used elsewhere in the ActiveSync  
code (which, btw, sort of goes against the whole "APIs shouldn't be  
returning objects" argument.  How is ActiveSync supposed to work if  
IMP's API doesn't return this object?  But that's another thread...)

I'm wary of returning subscribed information directly from IMP, since  
the subscribe status can be influenced by UI specific IMP preferences  
that.  i.e IMP has the 'subscribe' preference that determines whether  
unsubscribed mailboxes are displayed by default.  But I'm not sure  
that's the purpose of mailboxList.  Is it supposed to be returning the  
mailbox listing as defined by IMP or is it supposed to be returning  
the mailbox listing as defined on the IMAP server?  (That being said,  
I think it is the former, so I'm not sure whether that is correct.)

If we are going to add an entry to the return, I would rather make it  
'subscribed' rather than 's'.

michael

___________________________________
Michael Slusarz [slusarz at horde.org]