1# AGENTS.md 2 3This file provides guidance to AI agents when working with code in this repository. 4 5**Always update this file automatically when you learn new things about the code base!** 6 7## Project Overview 8 9This is the @@PLUGIN_NAME@@ DokuWiki plugin. 10 11It's for @@PLUGIN_DESC@@ 12 13**FIXME** replace this section with a more detailled description when you first inspect or extend the codebase. 14 15## Automated Testing 16 17Tests run via DokuWiki's PHPUnit-based testing framework. The calls MUST be made from within the plugin's repository root using a relative path to the `bin/plugin.php` script! 18 19```bash 20# Tests must be run from repository root 21../../../bin/plugin.php dev test 22 23# run individual test file 24../../../bin/plugin.php dev test _test/GeneralTest.php 25 26# create a new test file 27../../../bin/plugin.php dev addTest MyClass 28``` 29 30DokuWiki provides useful helper methods for testing: 31 32* `DokuWikiTest::getInaccessibleProperty()` to access private/protected properties 33* `DokuWikiTest::callInaccessibleMethod` to execute private/protected methods 34* read `../../../_test/core/DokuWikiTest.php` for more helper methods 35* use `../../../_test/TestRequest.php` to simulate HTTP requests for integration tests 36* use `../../../_test/phpQuery-onefile.php` if you need to parse HTML in tests 37 38Each test run will provide a fresh DokuWiki instance in a temporary directory via the default setupBeforeClass methods. 39 40**Important:** Test classes that need the plugin must set `protected $pluginsEnabled = ['@@PLUGIN_NAME@@'];` to enable it in the test environment. 41 42**Important:** `setUp()` and `tearDown()` methods must be `public` (not `protected`) to match the `DokuWikiTest` base class. 43 44 45## Caching 46 47DokuWiki may cache JavaScript, CSS and rendered output. To reset the cache just touch the config file 48 49```bash 50touch ../../../conf/local.php 51``` 52 53## Linting, Formatting and Conventions 54 55Adhere to PSR-12 coding standards. Always add proper docblocks with descriptions, parameter types, and return types to all classes, methods and functions. 56 57```bash 58# Lint PHP files using PHP_CodeSniffer (must be run from repo root) 59../../../bin/plugin.php dev check 60 61# Auto-Fix formatting issues using PHP_CBF and Rector (must be run from repo root) 62../../../bin/plugin.php dev fix 63``` 64 65## Plugin Architecture 66 67Inspect the base plugin classes in `../../../inc/Extension/` to learn about the plugin system architecture. 68 69```bash 70# add new plugin components (must be run from repo root) 71../../../bin/plugin.php dev addComponent <type> 72# e.g. 73../../../bin/plugin.php dev addComponent action 74# if multiple of the same type are needed, give a name: 75../../../bin/plugin.php dev addComponent action foobar 76# -> creates action/foobar.php 77``` 78 79Additional classes are autoloaded when using the `dokuwiki\plugin\@@PLUGIN_NAME@@` namespace. 80