ProcessWirePhpStormMeta

The ProcessWirePhpStormMeta module generates a .phpstorm.meta.php/ directory containing individual *.meta.php files for ProcessWire API autocompletion in PhpStorm. It automatically regenerates the files when fields, templates, or modules change.

$meta = $modules->get('ProcessWirePhpStormMeta');
$meta->generateMetaFile();

Configuration

Setting	Type	Default	Description
`metaFilePath`	`string`	`site/assets/.phpstorm.meta.php`	Path relative to PW root (treated as directory, `.meta.php` files inside)
`generatePageClassFieldMeta`	`bool`	`false`	Field-type autocompletion per Page class
`generateDebounceSeconds`	`int`	`2`	Min seconds between regenerations
`autoRegenerate`	`bool`	`true`	Auto-regenerate on field/template/module changes
`autoloadMode`	`string`	`admin`	`admin` (only in admin) or `always` (every request)

Config values are accessed via the module instance and saved via [[Modules]]:

$meta = $modules->get('ProcessWirePhpStormMeta');

// Read effective value (includes constructor defaults)
$path = $meta->get('metaFilePath');

// Read saved config only (may differ from effective value)
$saved = $modules->getConfig('ProcessWirePhpStormMeta');

// Save config — module picks up new value on next request
$modules->saveConfig('ProcessWirePhpStormMeta', [
    'autoRegenerate' => false,
]);

Override via site/config.php

All settings can be overridden in site/config.php. Overridden values are shown as disabled in the module config UI:

$config->ProcessWirePhpStormMeta = [
    'autoloadMode' => 'always',
    'autoRegenerate' => false,
];

Generated files

The module creates these files inside site/assets/.phpstorm.meta.php/:

File	Content	Regenerated on
`wire.meta.php`	`wire('key')` / `Wire::wire('key')` autocompletion	Never (static)
`constants.meta.php`	Page status, field flags, template cache, Inputfield collapsed, sort flags	Never (static)
`process-status.meta.php`	ProcessWire runtime status constants	Never (static)
`pages.meta.php`	`Pages::get()` page name → page class mapping	Page changes
`page-class-fields.meta.php`	Per-class `__get()` / `get()` field type overrides	Template/field changes¹
`templates.meta.php`	`Templates::get()` template name map	Template changes
`fields.meta.php`	`Fields::get()` field name map	Field changes
`modules.meta.php`	`Modules::get()` module name map	Module changes
`hooks.meta.php`	`Wire::addHook*()` hookable method autocompletion	Code file changes
`custom.meta.php`	Custom content via `generateCustomMetaContent()` hook	When hooks fire

¹ Only generated when generatePageClassFieldMeta is enabled.

Each file is wrapped in its own namespace PHPSTORM_META { ... } block — PhpStorm merges them automatically.

Only files whose content actually changed are written to disk. Unchanged files keep their mtime, reducing IDE cache invalidation and git noise.

Methods

generateMetaFile()

Generate (or regenerate) the .phpstorm.meta.php/ directory and all *.meta.php files inside. Called automatically when fields, templates, or modules change (debounced), or manually.

$meta = $modules->get('ProcessWirePhpStormMeta');
$meta->generateMetaFile();

Return: void

generateCustomMetaContent()

Hookable extension point for injecting custom PHP into custom.meta.php. Multiple hooks concatenate. Hook after it to append content:

$wire->addHookAfter('ProcessWirePhpStormMeta::generateCustomMetaContent', function($event) {
    $names = [];
    foreach (glob(wire()->config->paths->templates . 'blocks/*.php') ?: [] as $f) {
        $names[] = pathinfo($f, PATHINFO_FILENAME);
    }
    sort($names);
    if (empty($names)) return;
    $custom = "\n    registerArgumentsSet(\"block_names\",\n";
    foreach ($names as $n) $custom .= "        \"{$n}\",\n";
    $custom .= "    );\n\n";
    $custom .= "    expectedArguments(\\ProcessWire\\renderBlock(), 0, argumentsSet(\"block_names\"));\n";
    $event->return .= $custom;
});

Return: string — content to append (default: empty string)

getModuleConfigInputfields($inputfields)

Returns the module configuration form fields. Implements [[ConfigurableModule]].

$inputfields = $modules->get('InputfieldFieldset');
$form = $meta->getModuleConfigInputfields($inputfields);

Parameters: InputfieldWrapper $inputfields — wrapper to populate.

Return: InputfieldWrapper

Hooks

Hook	When	Arguments
`ProcessWirePhpStormMeta::generateCustomMetaContent`	Before meta files are written	`$event->return` (string, appendable)

$wire->addHookAfter('ProcessWirePhpStormMeta::generateCustomMetaContent', function($event) {
    $event->return .= "    // my custom entry\n";
});

CLI usage

The module registers the 'cli' => 'phpstormmeta' key in getModuleInfo():

php index.php phpstormmeta generate     # Regenerate meta directory
php index.php phpstormmeta status       # Show meta directory status (JSON)

When the directory regenerates

Field saved/deleted · Template saved/deleted · Module installed/uninstalled
"Regenerate Meta Files" button in module settings
CLI: php index.php phpstormmeta generate

The module debounces regeneration: repeated changes within generateDebounceSeconds coalesce into a single write.

Notes

autoload => true — module loads on all requests. In init(), context is filtered via autoloadMode config: 'admin' (default) only acts on admin pages, 'always' acts everywhere.
Auto-regeneration hooks (Fields::save, Templates::save, Modules::install, etc.) are only registered when autoRegenerate is true.
Generated files are safe to commit (content is compared before writing — no unnecessary mtime updates).
Extends [[WireData]] and implements [[Module]] and [[ConfigurableModule]]. CLI support via 'cli' key in getModuleInfo().
For richer per-page property stubs, combine with AutoTemplateStubs.
Source file: site/modules/ProcessWirePhpStormMeta/ProcessWirePhpStormMeta.module

FilesExpand file tree

API.md

Latest commit

History