Note: The complete source code for the examples in this tutorial can be downloaded at the end of the tutorial.

Introduction

The function printf() and its cousins are among of the most versatile and well-known functions for sending formatted strings as output to files and the screen. They are implemented by many languages, including C, Java, Perl, PHP, Python, Ruby, and a handful of others.

One of printf()'s signature benefits is its ability to accept a variable number of arguments. This allows printed text to contain countless variations of formatted values and strings. In this tutorial, you will learn how to extend this functionality to create your own printf() wrapper function.

Why would we want to do this? One of the most obvious reasons would be to create our own warning() or error() functions that act just like printf() but can be conditionally switched on or off by, say, a boolean flag or configuration value. This would save us the need to wrap individual debug statements in conditional blocks, cutting down code size and complexity.

This tutorial will demonstrate how to do this PHP.

[tuthead]Our Silver Bullet: vprintf()[/tuthead]
The secret to our success here is printf()'s close cousin, vprintf(). This function does the same thing as printf(), but differs in the way it accepts arguments. As we know, printf() accepts a format string and then a variable number of arguments. vprintf() on the other hand accepts a format string and then an array of arguments. It is this array that allows us to easily pass all of the arguments from our function into printf().

In order to generate this array from our function, we use the PHP function func_get_args(). This function returns an array containing the arguments passed into the function.

<?php
function printThis() {
    $argv = func_get_args();
    $format = array_shift( $argv );
    vprintf( $format, $argv );
}
?>

We need not declare any arguments for our function; func_get_args() will take care of the variable number of arguments passed in. Also, since the array we get contains all of our arguments, we want to make sure to shift off the first element to be used as the format string, keeping the remaining array as our arguments.

Putting It All Together

Now that we've successfully wrapped printf() in our own function, let's go ahead and create our own error() function that behaves exactly like printf(), but displays "Error: " before our messages.

<?php
function error() {
    $argv = func_get_args();
    $format = array_shift( $argv );
    printf( 'Error: ' );
    vprintf( $format, $argv );
    printf( "\n" );
}
?>

That's all there is to it. You can call error() the same exact way you would call printf(). As I mentioned earlier, you can surround its definition with a conditional so that output will only be generated if a given flag is set. Useful, eh?

Conclusion

You should now know how to create your own wrapper function for printf() in order to customize it to suit your needs. Keep in mind that you can create functions with variable-length arguments for many other purposes as well.

You may find the following resources helpful when working with the printf() family of functions:
printf(), fprintf(), vprintf(), vfprintf()

I always welcome questions or feedback about this tutorial. Simply post a reply or PM me; I'm glad to help! Full source:

printf.php

<?php

function error() {
    $argv = func_get_args();
    $format = array_shift( $argv );
    printf( 'Error: ' );
    vprintf( $format, $argv );
    printf( "\n" );
}

error( "An error has occured %d times due to %s.", 5, 'server overload' );

?>

This page was published on It was last revised on

Contributing Authors

0

1 Comment

  • Votes
  • Oldest
  • Latest
Commented
Updated

That is very neat 🙂

add a comment
0