Written by a caffeine-fueled WordPress developer, part-time bug whisperer, full-time code style fanatic, and someone who’s argued with
composer.lockmore than actual people.
Introduction
Once upon a time, in the cluttered land of /wp-content/plugins/, a brave WordPress developer set out on a noble quest: to organize his plugin… without losing his mind in a forest of require_once.
Armed with caffeine, curiosity, and Stack Overflow tabs, He stumbled upon an ancient spellbook called Composer, and within it — a mysterious spell:
classmap autoloading.
What follows is his story — and yours — if you dare to become the hero your plugin deserves.
Why Composer Classmap Autoloading?
Before our developer dove into the classmap abyss, he paused and asked:
Wait… why am I doing this again?”
Fair question. Here’s why Composer classmap autoloading is not just a good idea — it’s the MVP of your plugin toolbox.
100% Compatible with WordPress Standard – Still using
class-helper.phpandclass_legacy_widget? Composer’s classmap doesn’t care — it happily loads any class, no matter how “classic” your code style is.No Need to Rename or Restructure Anything – With classmap autoloading, you don’t need to do any refactoring. No need to rewrite files into
Namespace\CamelCase\FileNames. Just point Composer at the folder and go make a sandwich while it figures it out.Zero Manual
requireStatements – Remember when your plugin’s main file looked like this?phprequire_once 'includes/class-helper.php'; require_once 'includes/class-logger.php'; require_once 'includes/class-captcha-generator.php'; // and on and on and on...Yeah, Composer laughs at that.
Now it’s just:
phprequire_once __DIR__ . '/vendor/autoload.php';Like a single power switch that lights up the entire plugin. 💡
Chapter 1: Preparing for the Journey (Prerequisites)
Before our hero (that’s you) could begin, they had to gather their tools:
| What | Why you need it | How to Find It |
|---|---|---|
| System‑wide PHP (≥ 7.4) | Composer runs on PHP magic | Install PHP on Windows (Complete Guide 2025) |
| Composer (global) | It builds the autoloading spellbook for you | Global Composer Setup on Windows (Step‑by‑Step) |
With both installed, the path forward was clear.
Tip: If you’ve already got both of these, you may proceed to cast composer init without fear.
Chapter 2: The Plugin That Wanted to Be Clean
Let’s say our plugin lives here:
my-plugin/
├── composer.json
├── vendor/
├── my-plugin.php
└── includes/
├── class-hello-world.php
└── class-helper.php
Not fancy. Just tidy. Like a hobbit’s house.
Chapter 3: Enchanting Your Classes
Inside includes/, our developer wrote two humble class files.
includes/class-hello-world.php
<?php
class HelloWorld {
public function say_hi() {
return 'Hello from HelloWorld class!';
}
}
includes/class-hello-world.php
<?php
class HelloWorld {
public function say_hi() {
return 'Hello from HelloWorld class!';
}
}
Chapter 4: Summoning Composer
In the terminal (a wizard’s preferred interface), our dev whispered:
composer initComposer asked a few questions — name, description, and whether this plugin likes long walks on the beach. Then, it created a magical scroll: composer.json.
Composer Asks: Package name (<vendor>/<name>)
At some point during composer init, Composer will pause, look you dead in the terminal, and ask:
Package name (<vendor>/<name>)And you might think: “Wait, what? Am I publishing a library? Am I a vendor now? Do I need a storefront?”
Don’t worry — this is just Composer being a little dramatic.
Here’s how to answer it:
yourname/my-pluginyourname= your GitHub username, company name, or just anything that makes you sound legit. It doesn’t have to match a real domain or vendor registry — you’re not opening a Composer bakery. This name just gives your plugin a unique ID in case you ever want to share it or reference it later.my-plugin= the folder name or whatever you’d call your plugin if it went to plugin college
Example:
acme/wp-slider-proIf you’re just using Composer locally for autoloading and sanity, you can literally name it just-me/my-cool-plugin and move on.
So go ahead — be as professional or as goofy as you like. Composer won’t judge.
Composer Asks:Description []:
This is Composer’s polite way of saying:
“Tell me what your plugin does—in, like, one sentence.”
You could say something simple like:
A plugin that finally stopped using 27 require_once calls.
No pressure — it’s just a label for humans (and your future self wondering what this plugin was for at 2AM). Keep it short, sweet, and mildly sane.
Composer Asks:Author [n to skip]:
Now Composer wants to know:
“Hey, who’s behind this masterpiece?”
You can enter your name and email like this:
Your Name <[email protected] >
This doesn’t sign you up for anything — it’s just a shout-out in your composer.json, like signing your name on a painting. 🎨
Or just hit n if you’re feeling mysterious today. 🕵️♂️
Composer Asks:Minimum Stability []:
Composer is basically asking:
“How wild are you willing to get with the packages you install?”
Here are your options, ranked from “super stable” to “living on the edge”:
stable(recommended) – Only install well-tested, production-ready packages. Safe and boring (in a good way).beta,alpha,dev– For when you’re okay with things possibly exploding.
If you’re not sure? Just press Enter. Composer will default to stable, which is what most plugins should stick with — unless you’re feeling adventurous and debugging at 3am.
Composer Asks:Package Type (e.g. library, project, metapackage, composer-plugin) []:
This is Composer’s way of asking:
“What kind of thing are you building here?”
Since you’re making a WordPress plugin, just type: project
libraryis for reusable code shared across projectsprojectis for standalone apps or plugins (yep, that’s you!)The rest? For power users, wizards, and composer plugin sorcerers 🧙♀️
If you skip it, Composer won’t be mad — but setting it as project helps tools and humans understand what this thing is.
Composer Asks:License []:
Composer’s saying:
“How do you want people to legally use your code?”
If you don’t know or don’t care right now, just hit Enter — you can always add it later.
But if you want a quick answer for WordPress plugins: GPL-2.0-or-later
Why? Because WordPress itself is GPL, and your plugin needs to be compatible. It basically says:
“Use this code freely, just share it the same way.”
Or in plain English: Be nice, share nicely. 🤝
Composer Asks:Would you like to define your dependencies (require) interactively [yes]?
And Composer leans in and asks:
“Hey, want to install any packages right now? Maybe something cool like PHPMailer, Monolog, or a library that makes coffee?”
If you’re only setting up Composer for autoloading your own classes — just type “no” and press Enter to say “No”.
Later, if you do want to add a package, you can always do it with:
composer require somevendor/somepackage
No pressure. Composer is just being friendly.
Composer Asks:Would you like to define your dev dependencies (require-dev) interactively [yes]?
Composer leans in again, this time with glasses on and a clipboard:
“Okay… but what about stuff you only need while developing? Testing tools? Code sniffers? A moral support library?”
This is where you’d add things like:
PHPUnit (for testing your plugin logic)
PHP_CodeSniffer + WordPress Coding Standards (to keep your code cleaner than your coffee mug)
Mockery, Faker, or other dev-only goodies
But if you’re just here to get classmap autoloading going and don’t want any extras yet — type “no” and press Enter, to skip it.
No guilt. You can always install them later with: For PHPCS
composer require --dev squizlabs/php_codesniffer
Composer won’t judge. It’s just offering you a toolbox. You’re the one building the plugin castle. 🏰🔨
Composer Asks:Add PSR-4 autoload mapping? Maps namespace "Yourname\\MyPlugin" to the entered relative path. [src/, n to skip]:
Composer is now asking:
“Hey, wanna get fancy and use namespaces like the cool kids?”
It’s offering you PSR-4 autoloading, where you map a namespace (Yourname\MyPlugin) to a folder (src/, by default). That way, when you write:
use Yourname\MyPlugin\Controllers\Dashboard;
Composer knows to look inside:
use Yourname\MyPlugin\Controllers\Dashboard;But here’s the twist:
You’re doing classmap autoloading, so we don’t need this now.
So what do you say?
Just press n to skip and let classmap do its thing. ✨
If you ever switch to a full-on namespaced plugin structure later, you can come back and embrace the PSR-4 lifestyle. For now, we’re keeping it simple and cozy — like coding in sweatpants.
Composer Asks:Do you confirm generation [yes]?
This is it — the final boss of the composer init wizard. Composer takes a deep breath and says:
“Okay, I’ve written up everything you just told me. Want me to go ahead and save this scroll?”
And it shows you something like:
{
"name": "yourname/my-plugin",
"description": "A plugin that finally stopped using 27 require_once calls.",
"type": "project",
"license": "GPL-2.0-or-later",
"authors": [
{
"name": "Your Name",
"email": "[email protected]"
}
],
"minimum-stability": "stable",
"require": {}
}
Now you just type:
yes
And boom — your plugin is officially Composer-aware. The scroll (composer.json) is written, the setup is done.
Chapter 4: Mapping the Kingdom
With the sacred composer.json scroll freshly scribed, our brave plugin developer stood at the edge of the includes/ forest, ready to tell Composer:
So, they added this line to the scroll:“This is where I’ve hidden all my plugin’s classes. Go forth and find them.”
"autoload": {
"classmap": [
"includes/"
]
}
Translation: “Composer, go into that folder and memorize every class you see.”
After adding this to the file, the composer.json looked something like this:
{
"name": "yourname/my-plugin",
"description": "A plugin that finally stopped using 27 require_once calls.",
"type": "project",
"license": "GPL-2.0-or-later",
"authors": [
{
"name": "Your Name",
"email": "[email protected]"
}
],
"minimum-stability": "stable",
"require": {},
"autoload": {
"classmap": [
"includes/"
]
}
}“Are you sure your scroll is valid?” — composer validate
Before you summon the autoloader, it’s smart to make sure your scroll (a.k.a. composer.json) doesn’t contain a missing comma, a typo, or a license that only exists in another universe.
So our dev ran:
composer validate
Composer scanned the scroll, stroked its chin, and replied:
./composer.json is valid.
Always run this before
composer dump-autoload. It’s like linting your spellbook — fewer surprises, more magic.
The Autoloader Awakens: Awakens: composer dump-autoload
Now it was time to breathe life into the plugin. The developer cast:
composer dump-autoload
And Composer sprang into action — scanning includes/, finding every class, and generating the enchanted file:
vendor/autoload.php
require_once __DIR__ . '/vendor/autoload.php';
require_once whack-a-mole. 🎯The Final Polish Before Deployment: composer install --no-dev --optimize-autoloader
Right before releasing the plugin to the world, our dev ran:
composer install --no-dev --optimize-autoloader
This command:
Skipped dev-only tools like PHPCS, PHPUnit, etc.
Optimized the autoloader into a fast, static class map.
Slimmed down the
vendor/folder for production.
It was like packing only the essentials for a long journey — no test gear, just pure plugin magic.
Updating the Plugin’s Toolbox: composer update
When the developer eventually added real dependencies (like logging tools, API clients, or other Composer packages), they ran:
composer update
That refreshed all packages based on composer.json, and updated the composer.lock file.
⚠️ Just don’t run this randomly in production — it updates versions. Best done during dev.
Chapter 5: Using the Magic
Back in my-plugin.php, the developer inscribed the final lines:
<?php
/**
* Plugin Name: 🧙♂️ Classmap Chronicles: Rise of Autoload
* Description: A noble test plugin that demonstrates the ancient art of Composer classmap autoloading.
* Version: 1.0.0
* Author: Your Name
*/
require_once __DIR__ . '/vendor/autoload.php';
$hello = new HelloWorld();
$helper = new Helper();
add_action('admin_notices', 'classmap_plugin_activation_notice');
function classmap_plugin_activation_notice() {
if (get_transient('classmap_plugin_notice')) {
echo '<div class="notice notice-success is-dismissible">';
echo '<p><strong>🎉 Classmap Autoloading is working!</strong><br>You can now summon <code>HelloWorld</code> and <code>Helper</code> without a single require_once.</p>';
echo '</div>';
delete_transient('classmap_plugin_notice');
}
}
register_activation_hook(__FILE__, 'classmap_plugin_activate');
function classmap_plugin_activate() {
set_transient('classmap_plugin_notice', true, 30);
}
register_deactivation_hook(__FILE__, 'classmap_plugin_deactivate');
function classmap_plugin_deactivate() {
delete_transient('classmap_plugin_notice');
}
No require_once, no include juggling, no scrolls burned in frustration.
Chapter 6: The Test of Fire (a.k.a. WordPress)
The plugin was zipped, uploaded, and activated.
And what did it say?
Hello from HelloWorld!
Helper is here to help!
That refreshed all packages based on composer.json, and updated the composer.lock file.
The magic worked.
Chapter 7: Questions from the Tavern (FAQ)
1. Do I need namespaces?
Nope. Classmap is laid-back. It’ll map plain ol’ classes without a fuss.
2. Should I include the vendor/folder?
Yes! WordPress users won’t run composer install, so include everything — like packing snacks for a road trip.
3. What if I add a new class later?
Just re-run:
composer dump-autoload
That refreshed all packages based on composer.json, and updated the composer.lock file.
Think of it as refreshing the spellbook.
4. Can I switch to PSR-4 someday?
Absolutely! Classmap is a great place to start. When you’re ready for namespaces and full structure, PSR-4 awaits.
Final Chapter: A Plugin Transformed
And so, our developer’s plugin lived happily ever after — clean, efficient, and free from the shackles of manual includes.
Composer classmap autoloading may not be flashy, but it’s the trusty magic that keeps your code organized and your sanity intact.
So next time you start a WordPress plugin, remember this tale — and let Composer do the heavy lifting.
