[RFC|Rejected] [API] API functions accept arrays as arguments

These RFCs were either rejected or have been replaced by an alternative proposal. They will not be included in phpBB.
User avatar
callumacrae
Former Team Member
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

[RFC|Rejected] [API] API functions accept arrays as arguments

Post by callumacrae »

Instead of the traditional horrific amount of arguments that phpBB uses:

Code: Select all

function user_ban($mode, $ban, $ban_len, $ban_len_other, $ban_exclude, $ban_reason, $ban_give_reason = '')
{
	// ...
}
phpBB should use arrays instead:

Code: Select all

function user_ban($info)
{
	// ...
}

user_ban(array(
	'mode'	=> $mode,
	// ...
));
This prevents code with a large number of arguments and no indication of what they actually do.

Problems that I can see with this:
  • Backwards compatibility would be broken (but better in the long run, in theory).
  • DocBlocks aren't designed for this
  • Overkill for smaller functions - perhaps only for functions with more than three arguments?
Made by developers, for developers!
My blog

User avatar
EXreaction
Registered User
Posts: 1555
Joined: Sat Sep 10, 2005 2:15 am

Re: [RFC] [API] API functions accept arrays as arguments

Post by EXreaction »

Well, there are ways to do it that would not break backwards compatibility (func_get_args with some logic).

I think a lot of our functions should be redesigned to be nicer and allow greater flexibility like that, but it would require significant work, documentation, and tests.

User avatar
callumacrae
Former Team Member
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

Re: [RFC] [API] API functions accept arrays as arguments

Post by callumacrae »

Wouldn't need func_get_args, would just need an array hack and an explode call. Seems a bit hacky, though.

EDIT: disregard that, wrong way round...
Made by developers, for developers!
My blog

User avatar
imkingdavid
Registered User
Posts: 1050
Joined: Thu Jul 30, 2009 12:06 pm

Re: [RFC] [API] API functions accept arrays as arguments

Post by imkingdavid »

No need to change the current functions. Just create wrapper functions for the API that accepts an array and passes that as arguments? Of course, we would need to validate the array to ensure it contains all of the required arguments.

Here's something that I mocked up. It may be a little more complicated than we need but I just figured I'd put it out there. The arrays of arguments would have to be in order, since they will be passed to call_user_func_array in that order.

Code: Select all

function phpbb_user_ban_api(array $arguments)
{
    //These are the arguments that do not have a default value, and must be specified
    $required_args = array(
        'mode',
        'ban',
        'ban_len',
        'ban_len_other',
        'ban_exclude',
        'ban_reason',
    );

    // Optional arguments have a default value, so it is in the form of: 'argument' => 'default'
    $optional_args = array(
        'ban_give_reason' => '',
    );

    return phpbb_api_call('user_ban', $arguments, $required_args, $optional_args)
}

function phpbb_api_call($function_name, $given = array(), $required = array(), $optional = array())
{
    if (!function_exists($function_name))
    {
        trigger_error('<strong>' . $function_name . '</strong> is undefined.');
    }

    $arguments = array();
    foreach ($required as $arg)
    {
        if (!isset($given[$arg]))
        {
            trigger_error('<strong>' . $function_name . '()</strong> missing required argument: <strong>$' . $arg . '</strong>');
        }

        $arguments[] = $given[$arg];
    }

    foreach ($optional as $arg => $default)
    {
        $arguments[] = !isset($given[$arg]) ? $default : $given[$arg];
    }

    return call_user_func_array($function, $arguments);
}
I do custom MODs. PM for a quote!
View My: MODs | Portfolio
Please do NOT contact for support via PM or email.
Remember, the enemy's gate is down.

User avatar
EXreaction
Registered User
Posts: 1555
Joined: Sat Sep 10, 2005 2:15 am

Re: [RFC] [API] API functions accept arrays as arguments

Post by EXreaction »

What I mean is you could do something like:

user_ban($options)

if sizeof(func_get_args) > 1
// fill in $options in order of how they previously were set
$options['mode'] = (first);
ban = (second);
etc;

This actually could be setup really easily with a function to handle all this, where you'd just need to declare an array of what order the arguments used to be in and how they translated to the new options array.

User avatar
callumacrae
Former Team Member
Posts: 1046
Joined: Tue Apr 27, 2010 9:37 am
Location: England
Contact:

Re: [RFC] [API] API functions accept arrays as arguments

Post by callumacrae »

I'm not sure that I'd be a fan of putting "api" in the function name: it's the internal API, so they would be used internally, too.
Made by developers, for developers!
My blog

User avatar
naderman
Consultant
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC] [API] API functions accept arrays as arguments

Post by naderman »

I would actually strongly advocate against this. Why give up the clarity of what parameters there are which is built right into PHP for passing around arrays?

Senky
Extension Customisations
Extension Customisations
Posts: 315
Joined: Thu Jul 16, 2009 4:41 pm

Re: [RFC] [API] API functions accept arrays as arguments

Post by Senky »

I am not against, nor for (arguments are here for passing variables, but on the other side, it is much more clearer to use $args['user_id'], $args['username'], ... than $user_id, $username. It is quite clearer as you know which variable passed by parameter, and which was assigned internally in the function).

Just next idea how to swich to arrays without breaking compatibility:

Code: Select all

function example($param, $param2, $param2, $param4)
{
   if (is_string($param))
   {
      $param = array(
         'param' => $param,
         'param2' => $param2,
         'param3' => $param3,
         'param4' => $param4,
      );
   }

   // continue working
}
 

User avatar
Fyorl
Google Summer of Code Student
Posts: 27
Joined: Mon Apr 02, 2012 4:51 am
Location: UK
Contact:

Re: [RFC] [API] API functions accept arrays as arguments

Post by Fyorl »

Don't you lose the ability to do type hinting with this?

User avatar
naderman
Consultant
Posts: 1727
Joined: Sun Jan 11, 2004 2:11 am
Location: Karlsruhe, Germany
Contact:

Re: [RFC] [API] API functions accept arrays as arguments

Post by naderman »

Exactly, this is really a bad idea.

Post Reply