WordPress Plugin Anatomy and File Structure for Beginners

Welcome to the first step of our journey. Before we dive into complex architecture or database operations, we must establish the ground rules for how WordPress identifies and manages your code.

In this course, we are building a professional-grade Knowledge Base plugin. To ensure your code remains maintainable as we scale, we will treat this plugin as a software project, not just a collection of scripts.

The WordPress Plugin Directory Structure

WordPress looks for plugins within the /wp-content/plugins/ directory. Each plugin must reside in its own dedicated folder. While a simple plugin can exist as a single file, a professional-grade WordPress plugin architecture requires a structured approach to keep logic separated.

To begin our Knowledge Base project, navigate to your local WordPress installation’s wp-content/plugins/ folder and create a new directory named wp-knowledge-base.

Inside this folder, we will create our main entry point: wp-knowledge-base.php.

Defining the Plugin Header

WordPress does not automatically "know" that your folder contains a valid plugin. It scans the files in your directory looking for a specific, comment-based header. This header acts as the plugin's metadata manifest.

Open wp-knowledge-base.php and add the following block at the very top of the file:

PHP
<?php
#6A9955">/**
 * Plugin Name: Knowledge Base
 * Plugin URI:  https:#6A9955">//example.com/knowledge-base
 * Description: A powerful knowledge base system for WordPress.
 * Version:     1.0.0
 * Author:      Your Name
 * Author URI:  https:#6A9955">//example.com
 * License:     GPL2
 * Text Domain: wp-knowledge-base
 */

#6A9955">// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

Breaking Down the Header

• Plugin Name: This is the string displayed in the WordPress admin "Plugins" list.
• Version: Crucial for future updates and cache busting.
• Text Domain: Used for internationalization (we will cover this in later lessons).
• ABSPATH Check: This is a security best practice. It prevents a user from accessing your plugin file directly via a browser URL, which could expose sensitive information or trigger unintended code execution.

Activating the Plugin

Once you have saved the file, head over to your WordPress Dashboard and navigate to the Plugins menu. You should now see "Knowledge Base" listed among your plugins.

Click Activate.

WordPress now tracks your plugin in the wp_options table under the active_plugins key. Once active, your code is included in the execution flow of every page request on your site.

Hands-on Exercise

1. Navigate to your wp-content/plugins/ directory.
2. Create the wp-knowledge-base folder and the wp-knowledge-base.php file.
3. Paste the provided header code into your file.
4. Verify that the plugin appears in your WordPress Dashboard and click "Activate."

Common Pitfalls

• Wrong Directory Structure: Placing the PHP file directly in the plugins/ folder without a sub-folder is generally discouraged. It makes your environment messy and makes it difficult to add assets (CSS/JS) or sub-classes later.
• Missing Header Fields: If the Plugin Name is missing, WordPress will ignore the file entirely. Even if the file is syntactically valid PHP, it won't appear in the dashboard.
• Encoding Issues: Always save your PHP files as UTF-8 without BOM. A Byte Order Mark (BOM) can cause "Headers already sent" errors, which are notoriously difficult to debug for beginners.
• Naming Collisions: Always use a unique prefix for your plugin folder and files. If you name your folder test-plugin, you risk conflicts with other developers' code.

Recap

You have successfully laid the foundation for our project. We have created the folder, defined the mandatory file header, and triggered the activation state. You now have a working plugin entry point that adheres to the standards required for WordPress plugin activation.

In the next lesson, we will move beyond simple headers and learn how to use lifecycle hooks to perform tasks specifically when the plugin is activated or deactivated.

Up next: The Plugin Lifecycle Hooks