[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 » Sat Jul 28, 2012 6:52 pm

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 » Sat Jul 28, 2012 8:23 pm

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 » Sat Jul 28, 2012 10:37 pm

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 » Sun Jul 29, 2012 12:20 am

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 » Sun Jul 29, 2012 1:46 am

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 » Sun Jul 29, 2012 7:51 am

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 » Sun Jul 29, 2012 12:10 pm

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: 314
Joined: Thu Jul 16, 2009 4:41 pm

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

Post by Senky » Sun Jul 29, 2012 12:29 pm

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 » Sun Jul 29, 2012 3:48 pm

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 » Sun Jul 29, 2012 4:40 pm

Exactly, this is really a bad idea.

Post Reply