[development] Possibility of API *additions* post-code freeze?

[Angela Byron]

On 20-Aug-06, at 2:06 AM, Boris Mann wrote:
>
> I don't know what the best approach is here, but if, as Angie says,  
> we can make functions a bit more modular so that they CAN be called  
> externally with predictable results...it's a good thing.

Let me elaborate for a moment what my current train of thought is.

Let's take user_admin_role() as an example. This ~50 line function  
encompasses full CRUD (create, read, update, delete) and then some on  
user roles. However, it takes no parameters, so there is no way to  
get in there and pull out specific pieces to do just one of the  
things it does.

I was thinking we could go one of two ways on this. Either a series  
of functions like:

user_role_create() // or user_role_insert or user_role_add
user_role_read() // or user_role_get
user_role_update() // or user_role_save
user_role_delete()
user_role_list() // retrieve a list of all user roles as an array of  
objects or whatever

Or one "mega" function which incorporates the logic like:

function api_user_role($op, $name = NULL, $id = 0) {
   switch ($op) {
     case 'create':
       db_query("INSERT INTO {role} (name) VALUES ('%s')", $name);
       break;
     case 'delete':
       db_query('DELETE FROM {role} WHERE rid = %d', $id);
       db_query('DELETE FROM {permission} WHERE rid = %d', $id);
       // Update the users who have this role set:
       db_query('DELETE FROM {users_roles} WHERE rid = %d', $id);
       break;
     // etc.
   }
}

(I named it "api" because it would be nice if all such functions were  
grouped together so you could find them easily, a better prefix  
probably exists :))

Then, user_role would be changed internally to call:

api_user_role('create', $edit['name']); // or user_role_add($edit 
['name']);

but at the same time I could put in my install file:

api_user_role('create', 'Seamonkey'); // or user_role_add('Seamonkey');

 From a calling module's point of view, there's no difference;  
user_admin_role() still takes no parameters, and it still encompasses  
all of the functionality it ever did. The difference is that now we  
can actually get at that functionality in bite-sized chunks to do  
specific things.

Obviously, each "thing" in Drupal should get its own set of functions/ 
mega function. I don't know which approach is better... I lean  
towards the micro-functions though rather than the mega-function,  
even though it will add to the number of functions Drupal has. Open  
to ideas on this point. :)

-Angie