1. Code
  2. Plugins

How to Create a WordPress Avatar Management Plugin from Scratch: Getting Started

Read Time:19 minsLanguages:
This post is part of a series called How to Create a WordPress Avatar Management Plugin from Scratch.
How to Create a WordPress Avatar Management Plugin: Finishing Touches

Avatar Manager for WordPress is a sweet and simple plugin for storing avatars locally and more. Easily.

Enhance your WordPress website by letting your users choose between using Gravatar or a self-hosted avatar image right from their profile screen. Improved workflow, on-demand image generation and custom user permissions under a native interface. Say hello to the Avatar Manager plugin.


A WordPress plugin is a PHP application that adds a specific set of features or services to WordPress, which can be seamlessly integrated with WordPress using access points and methods provided by the WordPress Plugin API.

This article will guide you through the process of creating your own WordPress plugin from scratch.

Note: This article assumes that you are already familiar with the basic functionality of WordPress, and PHP programming.

Step 1. Setting Up the Workspace

To get started navigate to wp-content/plugins/ under your WordPress install. In order to set up the workspace start by creating the following structure of directories and empty files as exemplified in the image below:

Workspace structure of the Avatar Manager plugin
Workspace structure for the Avatar Manager plugin

Make sure to pick a unique name for the plugin directory and for the main PHP file, such as avatar-manager and avatar-manager.php in this example, and put all the plugin's files into that directory.

Silence Is Golden

Before starting to write our plugin, open avatar-manager/index.php and add the following code:

You can see this file in many places of WordPress. It's a simple trick used to prevent directory browsing.

Step 2. Writing a Basic WordPress Plugin

Now, it's time to put some information into our main plugin PHP file.

Standard Plugin Information

The top of the plugin's main PHP file must contain a standard plugin information header. This header lets WordPress recognize that the plugin exists, add it to the plugin management screen so it can be activated, load it, and run its functions; without the header, the plugin will never be activated and will never run.

Open avatar-manager/avatar-manager.php and add the following lines:

The minimum information WordPress needs to recognize our plugin is the Plugin Name line. The rest of the information (if present) will be used to create the table of plugins on the plugin management screen. The order of the lines is not important.

So that the upgrade mechanism can correctly read the version of our plugin it is recommended to pick a format for the version number and stick to it between the different releases.

The License slug should be a short common identifier for the license the plugin is under and is meant to be a simple way of being explicit about the license of the code.


For transparency and insight into our release cycle, and for striving to maintain backward compatibility, Avatar Manager will be maintained under the Semantic Versioning guidelines as much as possible.

Releases will be numbered with the following format:


And constructed with the following guidelines:

  • Breaking backward compatibility bumps the major (and resets the minor and patch).
  • New additions without breaking backward compatibility bumps the minor (and resets the patch).
  • Bug fixes and misc changes bumps the patch.

For more information on SemVer, please visit


It is customary to follow the standard header with information about licensing for the plugin. Most plugins use the same license used by WordPress, which is the GPLv2 license or a license compatible with the GPLv2. To indicate a GPLv2 license, include the following lines in our plugin:

Next, open avatar-manager/LICENSE and paste the plain text version of GPLv2 to it.

Step 3. Programming the Avatar Manager Plugin

After completing the previous step you should be able to locate the Avatar Manager plugin under the Plugins Screen.

The Avatar Manager plugin under Plugins ScreenThe Avatar Manager plugin under Plugins ScreenThe Avatar Manager plugin under Plugins Screen
The Avatar Manager plugin under Plugins Screen

Now, it's time to make our plugin actually do something. Activate it and add the following lines of code to the main plugin PHP file:

The define() function defines a named constant at runtime. The plugin_dir_url() function gets the URL (with trailing slash) for the plugin __FILE__ passed in. The value of __FILE__ is the full path and filename of the current file and it's one of the eight magical constants that PHP provides.

Let's go further and initialize our plugin:

The add_action() call hooks a function on to a specific action. The init action runs after WordPress has finished loading but before any headers are sent. Also the load_plugin_textdomain() call should be made during init, otherwise users can't hook into it. But more about this later, when I'll cover the internationalization of our plugin. The dirname() function returns the parent directory's path, while plugin_basename() function gets the basename of the plugin.

Hooks, Actions and Filters

Hooks are provided by WordPress to allow a plugin to hook into the rest of WordPress; that is, to call functions in the plugin at specific times, and thereby set the plugin in motion. There are two types of hooks:

  • Actions – Actions are the hooks that the WordPress core launches at specific points during execution, or when specific events occur.
  • Filters – Filters are the hooks that WordPress launches to modify text of various types before adding it to the database or sending it to the browser screen.

Step 4. Adding Plugin Options

Next, we're going to add the plugin options. Allowing for customization makes a plugin far more flexible for the user.

The admin_init action is triggered before any other hook when a user accesses the admin area. The register_setting() function registers a setting and its sanitization callback. The add_settings_field() function registers a settings field to a settings page and section. We used them to add our plugin options under the Settings Discussion Screen. The __() function will be explained later, when I'll cover the internationalization process.

Step 5. Adding the Sanitization Callback

Before writing the sanitization callback, we need to define two more functions, avatar_manager_get_default_options() and avatar_manager_get_options().

The avatar_manager_get_default_options() function returns plugin default options.

The avatar_manager_get_options() function retrieves current plugin options. The get_otpion() function returns the value of the specified option or the default value if the option isn't in the database.

The avatar_manager_sanitize_options() function sanitizes and validates plugin options. The isset() call determines if a variable is set and not NULL. The trim() function strips whitespaces from the beginning and end of a string. The is_numeric() function finds whether a variable is a number or a numeric string. The absint() function converts a value to a non-negative integer.

Step 6. Adding the Setting Fields

Now, it's time to add the setting fields.

The avatar_manager_avatar_uploads_settings_field() callback prints Avatar Uploads settings field. The checked() function compares two given values and, if the values are the same, adds the checked attribute to the current checkbox. The _e() function will be described later, when I'll explain the internationalization process.

The avatar_manager_default_size_settings_field() callback prints Default Size settings field.

After adding the setting fields you should be able to locate the plugin options under the Settings Discussion Screen.

The Avatar Manager plugin options under the Settings Discussion ScreenThe Avatar Manager plugin options under the Settings Discussion ScreenThe Avatar Manager plugin options under the Settings Discussion Screen
The Avatar Manager plugin options under the Settings Discussion Screen

The first option controls whether low privileged users can upload an avatar image or not, while the second option represents the default size for an avatar image.

Step 7. Adding the Avatar Section

To allow users manage their avatar, we need to add a new section to their profile page. Let's go furher and add the Avatar section under the User Your Profile Screen:

The show_user_profile and edit_user_profile actions help customization of the user profile page. The $profileuser parameter is a WP_User object of the user being edited. The get_post_meta() function returns the values of the custom fields with the specified key from the specified post. The empty() function determines whether a variable is empty. The remove_filter() function removes a function attached to a specified filter hook; it's required to remove our custom function for retrieving an avatar image.

Next, we're going to add an avatar picker, an upload form and a rating chooser for the custom avatar image of each user.

The Avatar Picker

The avatar picker lets a user choose between using Gravatar or a custom avatar image. To add it, write the following code:

The get_avatar() function retrieves the avatar for a user who provided a user ID or email address. To retrievie a custom avatar image by a user ID, we used the avatar_manager_get_custom_avatar() function, which we'll write later. The current_user_can() function checks whether the current user has a certain capability. Normally, low priviledged users like Subscribers aren't allowed to upload files; this is why we use the $options['avatar_uploads'] variable. The esc_attr() function escapes HTML attributes. The self_admin_url() function retrieves an admin URL link with optional path appended. The IS_PROFILE_PAGE constant tells us if we're editing our profile or another user's profile. The wp_nonce_url() function retrieves URL with nonce added to URL query. Before deleting an avatar, we ask the user to confirm by calling the showNotice.warn() method at the onclick event of the Delete link which displays a warning notice.

The Upload Form

The upload form allows a user to browse and upload a custom avatar image:

The submit_button() function echoes a submit button, with provided text and appropriate class.

The Rating Chooser

The rating chooser shows up only when a custom avatar is available. To add it, write the following lines:

It lets the user choose an appropriate rating for the custom avatar image being used.

Step 8. Adding Scripts and Styles

Now that we've added the Avatar section, it's time to style it. Also, we'll write some JS to change the form encoding; this step is required because we've added a file upload control to it.

The CSS Style

To style our plugin, open avatar-manager/avatar-manager.css and write the following lines:

This aligns an avatar image vertically with a radiobox and styles the Delete link accordingly for a seamless integration with WordPress' native interface.

The JS Script

Next, open avatar-manager/avatar-manager.js and add the following code:

The .attr() function sets the value of one or more attributes for every matched element. The enctype attribute specifies how the form-data should be encoded when submitting it to the server. We need to change its value to multipart/form-data to allow file uploads.

Step 9. Enqueuing the Scripts and Styles

The safe and recommended method of adding scripts and styles to a WordPress generated page is by using wp_enqueue_script() and wp_enqueue_style(). These functions include the scripts and styles if they haven't already been included, and safely handle dependencies.

The admin_enqueue_scripts action is the first action hooked into the admin scripts actions. Then, the global variable $hook_suffix is used to add our scripts and styles only on the needed pages. Before enqueuing a script or style, we need to register it first. The wp_register_style() function is a safe way to register a CSS style file for later use; the wp_enqueue_style() function is used to enqueue it. Similarly, the wp_register_script() and wp_enqueue_script() functions are used to register and enqueue our plugin JS script file.

After this step you should be able to locate the plugin options under the User Your Profile Screen.

The Avatar Manager plugin options under the User Your Profile ScreenThe Avatar Manager plugin options under the User Your Profile ScreenThe Avatar Manager plugin options under the User Your Profile Screen
The Avatar Manager plugin options under the User Your Profile Screen

The first option lets you choose between using Gravatar or a self-hosted avatar image. The second field lets you browse and upload a custom avatar image. The Avatar Rating option shows up only when a custom avatar is available. But more about this later, when we'll handle avatar uploads.

What's Next

This completes the first part of our tutorial. I hope you've enjoyed the time we've spent together and found it to be useful. In the next part we're going to finish the Avatar Manager plugin; we'll handle avatar uploads and on-demand image generation, internationalize our plugin and much more. Thanks for reading!


  • WordPress Coding Standards - General information about coding standards for WordPress development.
  • Writing a Plugin - Best starting place for learning about how to develop WordPress plugins.
  • Plugin API - Description of how to use action and filter hooks in your WordPress plugin, and core functions that plugins can override.
  • Settings API - A reference with examples for adding new settings to existing settings screens.
  • Function Reference - An article with many of the core WordPress functions useful to plugin and theme developers; lists most of the core functions, excluding Template Tags.
  • SemVer - Semantic Versioning (SemVer) specification.
  • GPLv2 - GNU General Public License, version 2.

External Links

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.