5

I am trying to learn WP Theme development. And as I have understod all "wp core" functions should be placed inside functions.php. But what about custom functions?

Lets say I would need a simple function inside home.php (somthing like: if/do something/else/do something). What is the correct way to do this? Could I put this code directly inside my home.php. Or should I write a function inside functions.php and then call it from home.php? Or is there a other way?

What is "best practice"?

9

At the risk of getting voted down by everybody else here who thinks this is OK. I say: No, you shouldn't define functions in template files. This should be considered bad practice. Let's have a look at the documentation:

  1. Functions File Explained.

The functions file behaves like a WordPress Plugin, adding features and functionality to a WordPress site. You can use it to call functions, both PHP and built-in WordPress, and to define your own functions. You can produce the same results by adding code to a WordPress Plugin or through the WordPress Theme functions file.

  1. Plugins

The core of WordPress is designed to be lean and lightweight, to maximize flexibility and minimize code bloat. Plugins then offer custom functions and features so that each user can tailor their site to their specific needs.

  1. Page Templates have the purpose to render your content – getting values, wrap them in markup, done. The maximum you'll find there are some simple conditions. And honestly, for the sake of any other developer who may have to overtake your project one day in the future that really should be the maximum. Don't tweak the functionality of your page inside template files itself. In my opinion they should be kept as untouched as possible.

What would happen if one future day you might want to switch your theme? Then it really gets difficult to find and grab custom stuff from various template files and put them in your new theme's templates. That's monkey work.

Same when you have to find that piece of code that is responsible for overriding certain output. It's really annoying to read through template files which are tweaked that way. Defining functions has places. But none of them should be a page template.


When I have to decide wether to tweak a template or not, I'ld ask myself:

  • Is it on markup level? Then it's fine. For example if/else-wrapping the title in <h1> or <h2> if is_front_page() is TRUE or FALSE. Or foreaching through posts to provide some extra wrappers. That would be done in a template file.
  • But when it comes to advanced logic I'ld write a plugin or define some helper functions in functions.php. For example adding dynamic classes to some <div> depending on the path. That would be a special function maybe path_to_class() where the logic happens and then I'ld add that to the markup as <div class="<?php print path_to_class(); ?>">.
    • Yes, even checking for multiple or complex conditions as you suggested shouldn't be done in templates. Even for mere readability. That also should be a function defined somewhere else and finally simply called in a condition like <?php if ( complex_condition() ) : ?><div ....

I'm a big fan of having readable and reusable plugins written and put on GitHub. There may be a future project where you need the same or similar stuff again. Then you simply pull the repo from GitHub, activate the plugin and move on. You also always have it as reference online. It's forkable, it's social, others can help you to improve your plugins and you can use it over and over again.

  • Just a small note, not all functions are site specific. Some are theme specific which are best kept inside the theme :-) – Pieter Goosen Aug 30 '15 at 20:57
  • Exactly! That's why every theme has its own functions.php – leymannx Aug 30 '15 at 21:02
  • 1
    I wish I could give you more than one up-vote for clearly stating »No, you shouldn't define functions in template files. This should be considered bad practice.«. – Nicolai Aug 30 '15 at 21:39
  • So for example. If I would like to tweak a loop based on theme-settings. (Something like: if, some option, loop, else, do something). Then I SHOULD write this as a function in my functions.php and then call the function from my template file. Do I understand you correct? Is it okay to put any PHP code in a template other then echos and function-calls? – Alex Aug 31 '15 at 7:34
  • @JohanGudmundsson - Edited answer and added some decision helpers. – leymannx Aug 31 '15 at 9:08
2

Sure. If your function is really just doing some control switching, putting it into the template is fine. Anything more than that traditionally goes into functions.php or similar.

Edit: +10 at Pieter Goosen's mention of trying to keep things DRY. It can actually be difficult to keep things DRY with WordPress theming. I'm a fan of the Sage starter theme. Based on this and another of your questions today, you might want to spend some time poking at Sage to see a whole bunch of (what some consider) WordPress Theming best practices in one spot. Sage source code and Sage Docs. Even if you don't wind up using it, there are lots of good ideas on display to learn from.

  • Anything more than that traditionally goes into functions.php or similar This still all depend on you yourself. There is no set of rules governing this ;-) – Pieter Goosen Aug 30 '15 at 17:25
  • @PieterGoosen Absolutely. I very intentionally used the word "traditionally". ;) For me, functions.php is just a big include file. – Will Aug 30 '15 at 17:28
  • I do it that way as well. Keeps code maintainable and organised ;-) – Pieter Goosen Aug 30 '15 at 17:29
1

There is no wrong or right way, neither is there any type of set rule or standard stating where custom code should go or not.

This is all personal preference. There are few guidelines which you should use (if you want to)

  • Templates (and all code for that matter) should be kept organised, maintainable, and easy to read and understand. Do not clot code together or add long pieces of code which can make a template messy and unreadable

  • Code having a certain relationship should be grouped together, and this where I like to use custom functions files, like pagination functions goes into pagination-functions.php. In future, I know that my pagination funtions will be pagination-functions.php. Also make a note in your code where a function is defined for quick and easy access

  • Keep templates files clean and as short as possible. Break code up into separate template files and functions files. This make code reusable accross multiple templates if needed, and this way you will not have to repeat yourself. Check the DRY Principle

As I said, this is just a basic concept that you can use if you want to.

0

There is no practical or theoretical problem with placing functions in home.php as long as they are being used only in that file. You might be able to use them in other contexes as well, but then it will become bad coding.

In principal any function that is called from two different template files should be in functions.php (or in a file included by it), the rest can be in the specific file or functions.php it is a matter of personal coding style. The advantage of putting all functions in functions.php is that you will not need to move them once you discover that they are needed in another file as well.

For flow control code, it is simplier, put it in the template file and do not create functions in functions.php unless there is a very complicated logic behind it that has to be replicated in other template files. The reason is to let the people that read your code a chance to understand it in one go without a need to open additional files and searching them.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.