How to read the functions guide April 15, 2008 / Updated: January 09, 2023

When you first look at our functions guides it might look confusing and you may not understand what exactly it is telling you. You might ask "why don't they just write an understandable and readable guide that even non-developers can understand at first glance?" Well, actually the guide is not that hard to read once you get into it. 

We are constantly updating and changing things, so that would take too much of our time write a guide manually. If one of us writes or changes a new function, he comments it within the source code directly on top of the function. You might have seen that if you looked at the template-functions.php file for example. We then use the standard auto-documentation tool phpDocumentor that generates the functions guide from these source code's comments. This way we can easily update it with one click anytime we need to.

We explain some basics here. But if you are working on themes it is strongely recommended that you already have basic knowledge of PHP. You will find some resources here:
https://www.php.net/manual/en/langref.php 

So let's take a closer look at one of the more complicated template functions as an example: printAllTagsAs() from template-functions.php:

This is the list of parameters the function provides for your theme customizing needs. There are three "fields" for each parameter. 

1. The type of parameter value you can enter for the variable. These are the common types:
   • string for a text string. Value to be entered within quotes.
   • bool for TRUE or FALSE. Value to be entered without quotes.
   • int for integer numbers. Value to be entered without quotes.
   • obj for an object. Value is a variable containing the object of the required type, e.g. $_zp_current_album.
2. The name of the variable.
3. The description of what values to do what.

This is the actual important part. Important are the options within the brackets. If you look closely you will notice that this is actually the same as the parameter list above. In short this would read:

printAllTagsAs($option, $class = '', $sort = 'abc', $counter = FALSE,$links = TRUE, $maxfontsize = 2, $maxcount = 50, $mincount = 10, $limit = NULL)

For example $sort = 'abc' is a default value that is used if no other value is entered for this parameter. To use this function within your theme, to print a tag cloud, you would have to write this: 

printAllTagsAs('cloud','','abc',FALSE,TRUE,2,50,10,NULL)

This would print:

• a tag cloud
• without a css class for styling
• "abc" for alphabetical sorting
• no tag count within brackets behind the tag
• search tag links included with the tag
• largest font size the cloud should display set to 2
• the maximum count for a tag to appear in the output set to 50
• the minimum count for a tag to appear in the output set to 10
• set to limit the number of tags displayed to the top $numtags disabled.

If you only want to set specific parameters, you have to set all others inbetween too. For example: If you want to set only the parameters $option and $counter you have to set the parameters $class and $sort as well as they are inbetween and can't be left out even if they have default values as described above.

printAllTagsAs('cloud', '','abc',FALSE)

This is only possible if they are the last ones that are not specifially set. So the function call would look like this if you only set the $option parameter:

printAllTagsAs('cloud')

The parameters after $option can be left out so their default values will be used.

NOTE: With PHP 8+ this limitation does not apply anymore as you can use named arguments now.

Hopefully this makes it easier for you to understand the documentation.