PHP Classmap Watcher

Stop wasting CPU cycles searching for PHP files.

PHP Classmap Watcher is a lightweight VS Code extension for any PHP project.
It automatically generates a high-performance classmap, replacing expensive recursive autoloading with instant O(1) lookups.

Think of it as Composer-style optimized autoloading, without requiring Composer.

Works with WordPress plugins, Laravel, Symfony, custom frameworks — any PHP project.

---

✨ Features

• ⚡ Lightning-Fast Autoloading — replace filesystem scans with direct array lookups
• 🔄 Automatic Rebuilding — updates instantly when files are created, renamed or deleted
• 👁 Window Focus Rebuild — detects changes made outside VS Code (terminal, git) when you switch back
• 📁 Multi-Directory Support — scan multiple folders, each gets its own classmap file
• ⚠️ Smart Warnings — alerts on duplicate class names and multiple classes per file
• 🚫 Directory Exclusions — skip tests/, fixtures/ or any folder; vendor, node_modules, .git always excluded
• 📊 Status Bar Integration — live class count, rebuild progress, warning badge
• 🖱 Right-Click Rebuild — trigger rebuild from Explorer or editor context menu
• 🚫 No Composer Required
• 🚫 No PSR-4 Required — files can live anywhere, named anything

---

🚀 Why Use PHP Classmap Watcher?

Traditional autoloaders do this on every request:

// Scans filesystem on every class load
foreach ($paths as $path) {
    if (file_exists($path . $class . '.php')) {
        require_once $path . $class . '.php';
    }
}

PHP Classmap Watcher converts that into:

// One hash lookup — no filesystem scan
if (isset($classMap[$class])) {
    require $classMap[$class];
}

	Traditional	Classmap
Lookup cost	O(n) filesystem stats	O(1) hash lookup
Miss cost	Scans all paths	1 hash lookup, done
OPcache friendly	✗	✅ array interned in shared memory
PSR-4 required	Often	Never

---

📦 Installation

Install directly from the VS Code Marketplace:

👉 https://marketplace.visualstudio.com/items?itemName=saurab-gupta.wp-classmap-watcher

Or via VS Code:

1. Open Extensions (Ctrl + Shift + X)
2. Search: PHP Classmap Watcher
3. Click Install

---

⚙️ Configuration

Paths are absolute. Add to your global VS Code settings (Ctrl + , → open settings.json):

{
    "wpClassmap.directories": [
        {
            "includesDir": "/home/user/my-plugin/includes",
            "outputFile":  "/home/user/my-plugin/classmap.php",
            "exclude":     ["tests", "fixtures"]
        }
    ]
}

Multiple directories — each gets its own classmap file:

{
    "wpClassmap.directories": [
        {
            "includesDir": "/home/user/my-plugin/includes",
            "outputFile":  "/home/user/my-plugin/includes/classmap.php"
        },
        {
            "includesDir": "/home/user/my-plugin/src",
            "outputFile":  "/home/user/my-plugin/src/classmap.php"
        }
    ]
}

All Settings

Setting	Type	Default	Description
wpClassmap.directories	array	[]	List of { includesDir, outputFile, exclude? }
wpClassmap.exclude	array	[]	Directory names excluded from all scans
wpClassmap.watchOnSave	boolean	false	Also rebuild when a PHP file is saved

vendor, node_modules, and .git are always excluded regardless of config.

---

🧩 PHP Autoloader

Add this to your main bootstrap file:

<?php

$classMap = require __DIR__ . '/classmap.php';
$base     = __DIR__ . '/includes/';

spl_autoload_register(function (string $class) use ($classMap, $base): void {
    if (!isset($classMap[$class])) return; // O(1) — only check on miss
    require $base . $classMap[$class];     // direct require on hit
});

• Miss = 1 hash lookup, nothing else
• Hit = 1 hash lookup + require
• No str_replace, no path derivation, no filesystem stat

---

🛠 Example Generated Classmap

<?php
// Auto-generated by PHP Classmap Watcher — 2025-01-01T00:00:00.000Z
// Do not edit manually.
return array(
    'MyPlugin\\Admin\\Settings'   => 'Admin/Settings.php',
    'MyPlugin\\Api\\Routes'       => 'Api/Routes.php',
    'MyPlugin\\Core\\Loader'      => 'Core/Loader.php',
);

---

⌨️ Commands

Command	Description
PHP: Rebuild Classmap(s)	Force a full rebuild of all configured directories
PHP: Add Classmap Directory	Add a new directory via prompt

Right-click any .php file or folder in the Explorer → PHP: Rebuild Classmap

---

📊 Status Bar

$(symbol-class) Classmap: 42          — idle, 42 classes indexed
$(sync~spin) Rebuilding...             — rebuild in progress
$(check) Classmap: 42                  — just finished
$(warning) Classmap: 42 $(warning)3   — finished with 3 warnings
$(error) Classmap: 1 error(s)         — a directory was not found

Click the status bar item at any time to trigger a manual rebuild.

---

⚠️ Warnings

The extension warns about:

• Multiple classes in one file — only the first is mapped; split into separate files
• Duplicate class names — same fully-qualified class in two files; last one wins

Warnings appear as VS Code notifications with a Show Files / Show Details action.

---

🔄 Keeping the Map Fresh Outside VS Code

The watcher covers file changes inside VS Code. For changes made outside (terminal, git):

• Window focus — the map automatically rebuilds whenever you switch back to VS Code
• Right-click rebuild — manually trigger from Explorer or editor at any time

---

✅ Requirements

• VS Code 1.70+
• Any PHP project (WordPress, Laravel, Symfony, custom)
• PHP files must declare namespace and class / interface / trait / enum

Supported platforms: Windows · macOS · Linux

---

🚫 No External Dependencies

Does not require Composer, PSR-4, vendor directories, or any third-party libraries.

---

🛠 Building from Source

npm install
npm run package   # compiles TypeScript + produces .vsix

Install the .vsix:

code --install-extension php-classmap-watcher-0.2.0.vsix

---

📄 License

MIT