- First Thing’s First (WTF is WordPress?)
- Some Basics
- Version Control
- Theme Building
- Customizing the Admin
- Share Your Knowledge
- The Bottom Line
This is my WordPress site. There are many like it, but this one is mine.
My WordPress site is my best friend. It is my life. I must master it as I must master my life.
My WordPress site, without me, is useless. Without my WordPress site, I am useless. I must develop my WordPress site true. I must develop more securely than my enemy who is trying to hack me. I must stop him before he hacks me. I will…
My WordPress site and I know that what counts in war is not the rounds we fire, the noise of our burst, nor the smoke we make. We know that it is the hits that count. We will hit…
I may have lost my thread at the end there…
There are lots of WordPress development best practices articles around the internet.
This article is not meant to be the be-all, end-all WP best practices document, but rather to supplement accepted standards with the guidelines I have come to adhere to through trial, error, blood, sweat, tears, death, and dismemberment*.
*Only two, maybe three, of the things on that list are accurate.
First Thing’s First (WTF is WordPress?)
Make sure you know what WordPress is. This sounds simple, but it’s a bit more nuanced than you may think. From WordPress.org:
WordPress started in 2003 with a single bit of code to enhance the typography of everyday writing and with fewer users than you can count on your fingers and toes. Since then it has grown to be the largest self-hosted blogging tool in the world, used on millions of sites and seen by tens of millions of people every day.
To say that WordPress is simply a blogging tool, is a gross understatement. It can function as pretty much any type of standard website you can shake a stick at, as well as serve as an API, a backend for software applications, and much more. The uses are constantly evolving and I encourage you to just do some quick google searches and see some of the innovative ways people are using the tool.
A word about support
The best support comes from the pros. If you have a question, hit a roadblock, or are just confused about something you are seeing in a codebase, here are the places to start your search for enlightenment:
- WordPress Codex | WP Developer Resources | WP Code Reference
- Who better to tell you how to do something in WordPress than the dudes and dudettes that made the thing? Seriously – their documentation, by and large, is super robust and well thought out.
- WordPress Development Stack Exchange & Stack Overflow
Learn from your peers.
Crafting a google query to find answers to your questions is an art form. Practice, practice, practice!
There’s a bunch of security stuff sprinkled throughout this article, but rather than jam it all in here, check out this separate article for a list of security tasks and considerations.
These are some of the most basic (but very important) tenets I follow when making a WordPress site. Not coincidently, these are also standard WP best practices.
- Never modify the WordPress core or the core of any third party plugins
WordPress is updated all the time, as are well-supported third party plugins. If you need to modify core behaviors, write functions in your theme to hook into the various filters wordpress has. This will ensure the stability of the site over time.
- Use WordPress functions to accomplish the tasks you need accomplished in your site.
WordPress is super robust and has a ridiculous amount of functions that allow you to access, modify, and manipulate your site data. Make use of these rather than creating your own PHP functions. WordPress bakes a lot of security into its functions and as core updates roll out, using WP functions helps ensure site stability. For 99% of the work you do in WordPress, you should be able to use WP functions, along with your custom filters to accomplish your goals. In the rare case you do need to access data more directly…
- Always use the wpdb class for custom interactions with the database
If you find yourself in a situation where WordPress just doesn’t have a method for you to access your data the way you want, use the wpdb class to interact with the database. https://codex.wordpress.org/Class_Reference/wpdb
- Keep your themes self-contained
By this I mean do not have theme dependancies (other than plugins or database, obviously) that live outside the theme folder. Some examples: Image assets that are essential to the theme should be part of the theme, never uploaded via the media browser. JS files should be contained in the theme folder. Favicons should be contained in the theme, etc.
- I build my themes from a starter theme I put together
This ensures I know and understand all the bits and pieces that are incorporated in my theme, and saves time on project start. Hacking or modifying an existing theme may be tempting, but it’ll only end in support heartache and an unnecessarily bloated theme. I have made my own starter theme that’s a great jumping off point.
- Always start your site development with the latest version of WordPress and any plugins you plan to use…
And keep them updated throughout the dev process…and beyond.
- Clients should never be given “administrator” roles except in cases where they control the hosting and ask for it
This is for security and long-term stability. Also has the bonus of filtering out a lot of admin interfaces that most clients do not need any access to.
- Setup Permalinks
For most sites, you’ll want to use “Post Name” as the default permalink setting as this is typically best for SEO.
- Leave Auto Updates Turned On
You have to do a little work to manually turn them off, so just don’t do that. I like auto updates. Security and maintenance updates are important. Let them fly.
- Handle Images According to Our Best Practices
There are certain steps that should be taken when handling images from custom fields and WP’s Featured Image. Please consult this other article for instructions, notes, and sample functions to make your life easier: Handling Images in WordPress.
When creating a repository my WordPress sites, I only commit the theme folder. I do not commit plugins, WordPress core, uploads, etc. This makes deployments more straight forward when you consider that WordPress and plugins will be updated via the WP admin panel and very quickly you will end up with a repository that is out of date. It’s a big security risk to be deploying out of date plugins, especially if a vulnerable plugin has been updated via the WP admin, then an old flawed version is deployed at a later date, opening up the security hold once again.
Sometimes I also include a ‘dev’ directory in my theme folder that I use to hold notes, sql backups, etc…basically anything site-related that I also want in version control. I just make sure to not include that folder in your deployment, especially if it contains any sensitive data.
When you start a new WordPress site, here are some things I do out of the gate to start off on the right foot.
- Download the latest version of WordPress and start from there
- Download the latest version of any plugins I intend to use
- Remove the pre-packaged WordPress themes and plugins. If the site will leverage the WordPress comment api, I leave akismet in place and use it
- When installing WordPress and doing my initial setup, make sure to assign a strong (and non-default) admin username and password. I don’t use admin / admin. That’s just silly.
- Understand the wp-config.php file and set it up with the proper settings (ref: https://codex.wordpress.org/Editing_wp-config.php)
- Set the salt
- Turn on WP_DEBUG during dev…turn it off when the site goes live
- Go through the admin and remove default content that WordPress includes (sample post, sample page, sample comment, default tag line, etc).
- If my site is not going to include commenting, close the comments api. Reference meta article: Discussion Settings
- Change the default table prefix from “wp_”. In terms of security, this doesn’t actually score many more points, but it doesn’t hurt and it helps keep databases more visually organized.
As per usual, the WordPress Codex covers this topic far more deeply than I could hope to here…and they keep it up-to-date. Read these articles…seriously…lots of great information in there that you’ll want to know: https://codex.wordpress.org/Theme_Development & https://codex.wordpress.org/Stepping_Into_Templates
Some basic guidelines I follow for theme building:
- Start from my starter theme!
- Keep it lean
WordPress themes don’t need a lot of files. Obviously any site is going to require some of the basics (style.css, index.php, functions.php, header.php, footer.php, etc) but start small and scale up as needed. Keep it light…this helps when we need to hand projects off to other developers. My starter theme is pretty light and can start you off on solid footing.
- Know, understand, and make use of proper Template Hierarchy
- Comment my code!
- Properly setup the style.css header to include all relevant data and include a screenshot.png file in the root of your theme folder
This is in service of having your template show up cleanly and all professional looking and whatnot in the WordPress admin. Ex: http://take.ms/zsTqH
- Use WordPress menu functions
Makes building and styling menus 100% easier and more maintainable. Ref: https://codex.wordpress.org/Navigation_Menus
- Enqueue your scripts and style sheets
Rather than hard-coding into the theme header and footer, scripts and stylesheets should pass through the WP enqueue functions. This prevents collisions with other scripts and allows you to load them only when and where you need to. Ref: https://developer.wordpress.org/reference/functions/wp_enqueue_script/
- Style WYSIWYG content
Especially for editorial sites, I always style out anything that can come out of the WYSIWYG editor so the user has the full range of styles at their disposal. At a minimum, I address H1-H6, p, pre, blockquote, ul, ol, li, alignleft, alignright, aligncenter, hr. Remember that these don’t have to be the same as the styling for these elements elsewhere on the site layout…just wrap them in a <div class=”content”> wrapper and you can target those specifically.
Customizing the WP Admin
My themes are typically leveraged for more than just the user-facing side of the site. It is equally important to make the wp-admin interface clean, customized, easy to use, and (perhaps most importantly) idiot-proof. There are lots of ways to accomplish these goals. I created a plugin (Aceify) that handles a bunch of them, but usually I implement them in my theme functions (many of these are included in my starter theme). Here are some of the basics:
- Always give clients “Editor” privileges. Clients should never be given “administrator” roles except in cases where they control the hosting
This is for security and long-term stability. Also has the bonus of filtering out a lot of admin interfaces that most clients do not need any access to.
- Identify and implement Custom Post Types where necessary
Bonus: assign custom icons to those post types (ex: http://take.ms/t1QYz)
- Identify and implement Custom Taxonomies where necessary
- Hide Unnecessary Menu Items
If your site is not using “Posts” for example, hide the menu item to clean up the admin. Feature included in Aceify and my starter theme.
- Customize the WP login page
Put in the client’s logo instead of WordPress’ logo, modify page styling, etc. Make it more unique and our clients feel happier. Feature included in Aceify and my starter theme.
- Hide various meta boxes that are unnecessary to the site functionality
If your site does not have comments, hide the comments metaboxes from post and page edit screens. There are a lot of ways to accomplish this, but using Advanced Custom Fields tends to be the easiest and you’ll most likely be using it anyway for other things.
- Set the favicon in the admin
Use a theme function to set the admin favicon.
- Think before implementing interfaces in the admin!
Before creating an admin interface, I think about how the client may interact with that interface, both intentionally and unintentionally. If there is any chance the client could break some aspect of the site by interacting with the interface you are creating…I come up with another way to do it. For example, if I have some kind of endpoint or handler and need it to have a nice URL, rather than creating a page template and making a page in the admin (which a client could easily delete), use the rewrite api (reference article: Custom Rewrites for Static Pages)
- Create a Documentation tab in the Admin
Depending on the project, I will often put together tutorials and documentation on how the client can manage their site. I create a page in the admin for “Documentation” where clients can easily access this information. Check out this tutorial for a quick rundown of how to create this page.
Plugins extend WordPress functionality. Some are built by Automattic (the folks behind WordPress), but most are created by the extremely active WordPress community. There are currently almost 40,000 plugins available in the WordPress Plugins repository.
NOT ALL PLUGINS ARE CREATED EQUAL
Because most plugins are created by random people and don’t have any real quality control, BE VERY CAREFUL when implementing a plugin that you haven’t previously vetted. Check the reviews and ratings, request a peer review of the plugin from other developers, and when in doubt, don’t use it. A lot of times you can accomplish what you are trying to do through a little extra elbow grease and some code slinging.
Plugins I Really Like
These are some plugins I have used a bunch. They have active support, and have been stable and reliable.
- Advanced Custom Fields
A super robust plugin for creating custom field meta boxes, options pages, customizing admin interfaces, and retrieving custom field data in a theme. Fantastic documentation. I have a license for the pro version and highly recommend it. The ACF Local JSON functionality can be leveraged to deploy fields and enable version control of those settings.
- ACF QuickEdit Fields
Add on plugin for ACF Pro that adds the ability to edit fields from the post list screens via bulk and quick edit. Also can include fields as columns in the post list screen.
- All In One SEO
Reliable plugin for seo. Has features for social meta, robots.txt editing, sitemap xml, etc.
- Yoast SEO
Similar set of features to All In One SEO, but also includes tools to help content editors write better content for SEO.
- Gravity Forms
Great form builder tool. I use this often for sites with many form needs.
- User Role Editor
Nice little plugin for creating new user roles and customizing the permissions various roles have access to.
- Custom Post Type UI
This plugin provides a GUI for creating custom post types and custom taxonomies. I personally prefer to build those manually in the theme, but this is a solid alternative to that.
- WP Fastest Cache, WP Super Cache & WP Total Cache
All of these are solid cacheing choices, but some play nicer with different hosts. Rackspace cloudsites plays nicer with WP Super Cache, for instance. Some managed hosting companies provide their own hosting, so be sure to check on that before installing one of these.
- WP Extended Search
So far this has been the lightest weight plugin I’ve found to extend WP default search functionality. Out of the box, WP does not search taxonomies or custom fields. This plugin gives you more control over that.
WPEngine Disallowed Plugins
WPengine keeps up with a lot of security and performance related issues in regards to plugins. Some of these plugins are only bad in WPE’s environment, as they duplicate functionalty WPE is already providing (like cacheing plugins), while others are just bad news across the board. When trying out a new plugin, I usually make sure to check their list…it’s never bad to check and see if they have given the plugin a red flag. Ref: http://wpengine.com/support/disallowed-plugins/
Follow standard WP best practices, don’t use sketchy plugins, make your admin lean, mean, and idiot-proof, and ask for guidance should you need it.
If you read all the way to the end, thanks, you’re a real mensch.