[wp-hackers] echo and return and passing parameters: a proposal

[David House]

Having changed my mind several times, I think I've finally come to a conclusion
and felt that someone should put forward a proposal to wrap up what's been
discussed. So here's my effort.

PASSING PARAMETERS
------------------
I think everyone's pretty happy with the associative array format. First
outlined [1] by Stephen Minutillo, this has the benefits of:

1. Self documentation; it's more obvious what each of the parameters do.
2. It's not necessary to pass all the parameters if you don't need to.
3. It's backward-compatable with the URL-style parameters [2].
4. It's much easier to have defaults set as outlined by lowmagnet [3] (although
it needs to be noted that you must always put the defaults on the left, as the
input needs to take precedence over the defaults).
5. It works with funny characters like spaces and even unserialised objects and
arrays, whereas the URL style parameters do not.

Proposed implementation:
With the next release, all the large functions with wp_ prefixes (the one's
that
currently take URL-style parameters) are converted over to array-style
parameters. At the top of each function, Owen Winkler's fix_params function [4]
is called to convert the old URL-style parameters over.

We haven't really come to a solid conclusion over whether the smaller template
functions should be converted at all. If they are, it becomes frightfully hard
to convert them without breaking older functions. The only solid way that I can
think of is to create a whole list of new functions, prefixed with something to
differentiate them from the current ones, and implement these functions with
the array-style parameters. The problem with this is that if these functions
get into regular usage it would be hard to get rid of said prefixes and adopt
the simpler notation again. So, I reccomend that (for the next few releases at
least), we DO NOT convert these functions.

ECHO AND RETURN
---------------
This discussion has not really come to a conclusion yet, but there are several
options available:

1. Using array-style parameters, have 'echo' as one of the parameters, and have
the function check this, echoing if it's true and returning if false. Default
should be TRUE in all instances (for backward compatabilty).

2. We pass all the parameters in an array as the first parameter to any
function, then each function should have a second parameter which is the echo
parameter and acts as above. Basically, just seperate the echo from list of
other paramters.

3. Have one global variable that you could set and unset, that every template
function checks and behaves as in (1). This has several disadvantages (every
function must declare another global variable, two lines each side of every
function call to check, set and unset this variable) and I don't think this is
a practical solution.

4. Every function returns it's value, and that value must be echoed when the
function is called. I should point out that this is NOT backward compatible,
and is extra (confusing) work for the user that shouldn't have to happen.

5. Finally, the solution that makes the most sense to the most people: having
two sets of functions, perhaps called the_* which would echo the value and
get_the_* which would return the value. As Brian Meidell said originally [5],
the the_* functions should just call the get_the_* functions, there's no need
for the logic to be duplicated. Indeed, because of this, I wrote a quick
function that would automatically generate the the_* functions and cut down on
the kilobytes:

$funcs = get_defined_functions();
$funcs = $funcs['user'];
foreach ($funcs as $funcname) 
  if (substr($funcname, 0, 4) == 'get_') {
    $newfname = substr($funcname, 4); //4 is the length of string 'get_'
    if (!function_exists($newfname)) {
      function $newfname($args) {
        {$funcname}($args);
      }
    }

(note: this function assumes that ALL the functions would just take a single
paramater, which would be our array of parameters.)

My proposal suggests the last solution, as it is completely backward compatable,
and basically has no downside (except perhaps that it pollutes the function list
with hundreds of extra functions, but these are very small and I don't think
they'd have too much of a hit on performance. It would be interesting to see
some figures, though).

Proposed implementation:
As (5) is completely backward compatable, we could start implementing this in
the next release. Once all the functions had been converted over to array-style
parameters (if this is indeed what will be agreed), my function above could be
implemented.

Feedback still appreciated on any of the issues raised.

References:
[1]: http://wordpress.org/pipermail/hackers_wordpress.org/2004-July/000901.html
[2]: http://wordpress.org/pipermail/hackers_wordpress.org/2004-July/000917.html
[3]: http://wordpress.org/pipermail/hackers_wordpress.org/2004-July/000904.html
[4]: http://wordpress.org/pipermail/hackers_wordpress.org/2004-July/000917.html
[5]: http://wordpress.org/pipermail/hackers_wordpress.org/2004-July/000868.html

----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.