WordPress plugin_basename Example: Identify Plugin Files Correctly

Last reviewed: May 13, 2026

Plugin code often needs a stable identifier for the plugin file itself. That comes up in activation hooks, deactivation hooks, settings links, and admin notices that target one specific plugin row. plugin_basename() is the helper WordPress uses to convert a full plugin file path into the normalized plugin-relative identifier that those APIs expect.

This guide shows how to use plugin_basename() correctly and why plain basename() is not a safe substitute for plugin-aware behavior.

Use it when an API expects the plugin-relative file identifier

<?php
$plugin_file = plugin_basename( __FILE__ );

add_filter(
	"plugin_action_links_{$plugin_file}",
	'vulnwp_add_settings_link'
);

The helper turns the current plugin file path into the format WordPress uses internally for plugin references, such as my-plugin/my-plugin.php.

Do not replace it with plain filename helpers

The code reference notes that plugin_basename() strips the real plugins directory or must-use plugins directory from the path. That means it carries WordPress installation context that plain PHP path helpers do not know about.

Be careful with nested files

If the plugin contract should point to the main plugin bootstrap file, using __FILE__ from a nested include file will produce a different basename than expected. In those cases, the correct file reference should be passed intentionally rather than assumed.

Common mistakes

• Using basename() where WordPress expects a plugin-relative identifier. That loses important path context.
• Calling it from the wrong file in a nested plugin structure. The result may target the wrong plugin file.
• Hardcoding plugin identifiers. That creates brittle refactor and rename paths.
• Mixing filesystem path logic with plugin registration logic. They are different concerns.

Production checklist

• Use plugin_basename() for hook keys and plugin-row targeting.
• Pass the intended plugin file deliberately in multi-file plugins.
• Avoid hardcoded plugin slugs when a file-derived identifier is available.
• Keep filesystem path and plugin identifier logic separate.
• Retest plugin-row hooks after file moves or plugin renames.

Related reading

Pair this with the plugin_action_links guide for plugin-row integrations and with the plugin_dir_path article when the same codebase also needs filesystem-safe path resolution.

References and further reading

• WordPress Code Reference: plugin_basename()
• WordPress Code Reference: register_activation_hook()
• WordPress Plugin Handbook: Determining Plugin and Content Directories