{"record":{"id":"8ba500770ea7a46e","repo":"octobercms/october","slug":"the-plugin-configuration-file-plugin-yaml-should-c","errorCode":null,"errorMessage":"The plugin configuration file plugin.yaml should contain the \"plugin\" section: %s.","messagePattern":"The plugin configuration file plugin\\.yaml should contain the \"plugin\" section: (.+?)\\.","errorType":"exception","errorClass":"SystemException","httpStatus":500,"severity":"error","filePath":"modules/system/classes/PluginBase.php","lineNumber":55,"sourceCode":"     * @return array\n     * @throws SystemException\n     */\n    public function pluginDetails()\n    {\n        $thisClass = get_class($this);\n\n        $configuration = $this->getConfigurationFromYaml(sprintf(\n            'Plugin configuration file plugin.yaml is not '.\n            'found for the plugin class %s. Create the file or override pluginDetails() '.\n            'method in the plugin class.',\n            $thisClass\n        ));\n\n        if (array_key_exists('plugin', $configuration)) {\n            return $configuration['plugin'];\n        }\n\n        throw new SystemException(sprintf(\n            'The plugin configuration file plugin.yaml should contain the \"plugin\" section: %s.',\n            $thisClass\n        ));\n    }\n\n    /**\n     * register method, called when the plugin is first registered.\n     */\n    public function register()\n    {\n    }\n\n    /**\n     * @inheritDoc\n     */\n    public function registerMarkupTags()\n    {\n        return [];","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/octobercms/october/blob/b608633a7e8922487d91a8161499020121c3b3bf/modules/system/classes/PluginBase.php#L37-L73","documentation":"PluginBase::pluginDetails() supplies the name/description/author shown in the backend by reading the plugin.yaml sitting next to the plugin class (getConfigurationFromYaml). If the file exists and parses but contains no top-level 'plugin' key, SystemException is thrown naming the plugin class. Most plugins instead override pluginDetails() and return the array directly, so this path hits code relying on the YAML-driven flow.","triggerScenarios":"Creating plugin.yaml with other sections (navigation, permissions) but omitting the plugin: block; overriding pluginDetails() to call parent::pluginDetails() while the YAML lacks the section; scaffolding a plugin where the yaml template was trimmed.","commonSituations":"Plugin scaffolding by hand or by generator that writes a partial plugin.yaml; upgrading plugins where the yaml was reorganized and the plugin key was dropped; the backend system settings page or plugin list requesting details from every registered plugin.","solutions":["Add the missing top-level section to plugin.yaml with at least name, description and author (icon optional).","Alternatively override pluginDetails() in the plugin class to return the array directly and stop relying on the YAML.","Validate indentation — 'plugin:' nested one level too deep parses as a child of another key."],"exampleFix":"# before — plugin.yaml\nnavigation:\n  main: ...\n\n# after — plugin.yaml\nplugin:\n  name: Blog\n  description: 'Blog management'\n  author: Acme\n  icon: icon-pencil\nnavigation:\n  main: ...","handlingStrategy":"fallback","validationCode":"// In tests or a boot check, verify the yaml carries the section\nuse Symfony\\Component\\Yaml\\Yaml;\n\nfunction pluginYamlHasPluginSection(string $pluginClass): bool\n{\n    $ref = new ReflectionClass($pluginClass);\n    $file = dirname($ref->getFileName()) . '/plugin.yaml';\n    if (!file_exists($file)) return false;\n    $config = Yaml::parse(file_get_contents($file));\n    return is_array($config) && array_key_exists('plugin', $config);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer overriding pluginDetails() in the plugin class for stable metadata instead of relying on plugin.yaml.","If YAML-driven, keep the plugin: section (name, description, author, icon) at the top level — indentation matters.","Add a CI check that parses every plugin.yaml and asserts the plugin key."],"tags":["php","plugin","yaml","plugin-yaml","configuration"],"backgroundTag":"missing-config-section","analyzedSha":"b608633a7e8922487d91a8161499020121c3b3bf","analyzedAt":"2026-08-21T04:24:57.515Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}