README.md
1# Delete Page Guard for DokuWiki
2
3The **Delete Page Guard** plugin prevents accidental or intentional deletion of
4wikipages in your DokuWiki installation by blocking the “empty save”
5operation when certain pages are protected. A page is considered for
6protection when its ID or relative file path matches one or more
7regular expressions configured via the DokuWiki Configuration Manager.
8
9## Features
10
11* Prevents deletion via "empty save" on protected pages.
12* Supports any number of protection patterns using PCRE syntax.
13* Choose whether to match against the colon‑separated page ID or the
14 relative file system path.
15* Allow administrators and optional additional groups to bypass the
16 protection.
17* Optionally treat whitespace‑only content as empty.
18* **Pattern validation**: Real-time validation with detailed error messages for administrators.
19* **Admin interface**: Dedicated admin page for testing and validating patterns.
20* **Security features**: Built-in ReDoS protection and input sanitization.
21
22## Installation
23
241. Copy the contents of this plugin directory into
25 `<dokuwiki>/lib/plugins/deletepageguard/`.
262. Ensure that the directory name matches the `base` value in
27 `plugin.info.txt` (here: `deletepageguard`).
283. Visit the **Configuration Manager** in your DokuWiki and adjust the
29 plugin settings under the “Delete Page Guard” section.
30
31## Configuration
32
33The following options are available in the Configuration Manager:
34
35| Setting | Description |
36|---|---|
37| **Protected page patterns** | List of PCRE regular expressions. Each line defines a pattern. When a page matches any pattern, non‑admin users cannot delete it by empty save. Invalid patterns are automatically skipped with warnings shown to administrators. |
38| **Match against** | Choose whether the patterns should match against the page ID (e.g. `users:john:home`) or the relative file path (e.g. `users/john/home.txt`). |
39| **Extra groups allowed to delete** | Comma separated list of user groups that are allowed to delete protected pages, in addition to administrators. Leave empty to restrict deletion to admins only. |
40| **Treat whitespace‑only pages as empty** | If enabled, pages containing only whitespace will be treated as empty and deletion will be blocked on protected pages. |
41
42### Pattern Validation
43
44The plugin includes comprehensive pattern validation:
45
46* **Real-time validation**: Invalid patterns are automatically detected when pages are saved
47* **Administrator feedback**: Detailed error messages are shown to administrators when invalid patterns are encountered
48* **Admin interface**: Visit **Admin → Delete Page Guard** to test and validate patterns before saving them to configuration
49* **Security protection**: Built-in protection against ReDoS (Regular Expression Denial of Service) attacks
50
51### Pattern examples
52
53* `^users:` – protect all pages in the `users` namespace.
54* `^users:[^:]+:start$` – protect every user's landing page named `start` under `users:<username>`.
55* `^projects:.*$` – protect everything in the `projects` namespace.
56* `^private/.*\.txt$` – when matching against file paths, protect any `.txt` file in the `private` directory.
57
58## How it works
59
60When a page is saved, DokuWiki triggers the `COMMON_WIKIPAGE_SAVE` event just before writing to disk. For normal edits, the plugin does nothing. However, when the new content is empty (after optional trimming) the plugin checks the configured patterns against the chosen target (ID or file path). If a match occurs and the current user is not an administrator and not in one of the exempt groups, the plugin prevents the deletion by calling `$event->preventDefault()` and `$event->stopPropagation()` as documented in DokuWiki's event system. An error message is displayed to the user informing them that deletion is not allowed.
61
62## Security Features
63
64* **Regex Validation**: All regular expressions are validated for syntax before use.
65* **ReDoS Protection**: Basic protection against Regular Expression Denial of Service attacks through pattern complexity checks and execution timeouts.
66* **Input Sanitization**: User input is properly sanitized and validated.
67
68## Development
69
70### Developer Testing
71
72The plugin includes a comprehensive test suite for developers:
73
74```bash
75# Run all tests
76php tests/test_runner.php
77
78# Check syntax of all files (if make is available)
79make check
80
81# See all available commands (if make is available)
82make help
83```
84
85The test suite covers pattern validation, matching logic, security features, and edge cases without requiring a DokuWiki installation.
86
87### Release Process
88
89For maintainers and contributors, see **[RELEASE.md](RELEASE.md)** for the complete release workflow including:
90- Version management and semantic versioning
91- Automated testing and validation
92- Distribution packaging
93- Git workflow and tagging
94- Quality assurance processes
95
96### Test Coverage
97
98- **Comprehensive tests** covering all core functionality
99- **Pattern validation** (syntax, ReDoS protection, length limits)
100- **Pattern matching** (simple and complex regex patterns)
101- **File path conversion** (absolute to relative paths)
102- **Configuration parsing** (multi-line patterns, different line endings)
103- **Security features** (escaping, unicode support, injection protection)
104- **Edge cases** (empty patterns, very long inputs)
105- **Real-world scenarios** (user pages, namespaces, file extensions)
106
107## Compatibility
108
109This plugin hooks into the `COMMON_WIKIPAGE_SAVE` event, which was introduced in DokuWiki release **"Detritus" (2016‑02‑24)** and is marked as preventable. It has been tested for compatibility with current releases such as **"Kaos" (2024‑02‑06b)**. The plugin uses only public APIs and the documented event system, so it should continue to work with future versions as long as these events remain available.
110
111## License
112
113This plugin is released under the terms of the
114[GNU General Public License v2](https://www.gnu.org/licenses/gpl-2.0.html).
115