[dev] API Interface Rewrite

[Chuck Hagenbuch]

Quoting Michael M Slusarz <slusarz at horde.org>:

>> I think what you are describing is a Horde_Application_Base class -  
>> a base for what makes a Horde application a Horde application. I  
>> don't think this is the same thing as most of the current registry  
>> API methods; I think those would go in a Horde_Application_Api tree  
>> instead.
>
> At an abstract level, I agree with you.  But at an implementation  
> level, I don't.
>
> Take perms().  That is an example of a function that should be the  
> same across all applications.  However, calling code shouldn't have  
> to call that method any different from an application specific  
> method (they should both be callable via call() or callByPackage()).  
>  Which makes sense because these calls are no different than an  
> application's API calls.

But they are different - you could make an argument that the only  
place a list of permissions should be exposed through the API is at  
the Horde level, where you could request the full tree. Same thing for  
prefs callbacks - there could be a system API to get at them, but they  
don't belong at all in a regular application's API. And because of  
that I don't agree that they should be callable the same way.

> So that means that these functions now have to parse yet another  
> file to determine where the function call lies (more overhead).  And  
> we have to create this 'Applicaion_Base' file, which is going to  
> look identical to the API file since it needs $services and $types  
> declarations (more overhead, both processing and in code maintenance).

It shouldn't be necessary to guess where the function call is. There  
should be two distinct kinds.

Also, one or two PHP class files should not involve performance  
overhead; if it matters to a specific install they should be using a  
PHP opcode cache, which should make the overhead negligible on one or  
two files.

Also, the $services and $types arrays should go away in favor of  
well-documented and marked up PHP classes.

> I think a well-commented API file is much preferable then trying to  
> break this out into 2 separate libraries.

I still disagree, so I'm interested in whether this changes your mind or not.

-chuck