From b62b3467ca01a51e60a4fa0b535d8eb9781ddf57 Mon Sep 17 00:00:00 2001 From: Viktor Miller Date: Fri, 16 Jan 2026 11:38:01 +0900 Subject: [PATCH] docs(03): create phase plan Phase 03: Settings System - 1 plan created - 3 tasks defined - Ready for execution --- .planning/phases/03-settings/03-01-PLAN.md | 204 +++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 .planning/phases/03-settings/03-01-PLAN.md diff --git a/.planning/phases/03-settings/03-01-PLAN.md b/.planning/phases/03-settings/03-01-PLAN.md new file mode 100644 index 0000000..971db97 --- /dev/null +++ b/.planning/phases/03-settings/03-01-PLAN.md @@ -0,0 +1,204 @@ +--- +phase: 03-settings +plan: 01 +type: execute +depends_on: ["01-01"] +files_modified: [includes/class-settings.php, umzugsliste.php] +--- + + +Create admin settings page with WordPress Settings API for email and captcha configuration. + +Purpose: Allow admin to configure receiver email address, select captcha provider (reCAPTCHA v2/v3/hCaptcha/none), enter API keys, and set thank you redirect URL. +Output: Working settings page accessible from admin menu, with proper validation and sanitization. + + + +~/.claude/get-shit-done/workflows/execute-plan.md +~/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/01-foundation/01-01-SUMMARY.md + +**From Phase 1:** +- Admin menu structure exists with "Einstellungen" submenu (via class-admin-menu.php) +- Singleton pattern established for all plugin classes +- German labels for all UI text +- Text domain: umzugsliste + +**Settings Requirements from PROJECT.md:** +- Receiver email address (where form submissions go) +- Captcha provider selection: reCAPTCHA v2, reCAPTCHA v3, hCaptcha, or None +- Captcha API keys (site key + secret key) +- Thank you page URL (redirect after successful submission) + +**WordPress Settings API pattern:** +- register_setting() for each setting +- add_settings_section() for grouping +- add_settings_field() for each field +- sanitize_callback for validation +- options table storage via update_option()/get_option() + + + + + + Task 1: Create settings class with WordPress Settings API registration + includes/class-settings.php, umzugsliste.php + +Create Umzugsliste_Settings class following singleton pattern. + +In class-settings.php: +- Private constructor (singleton) +- get_instance() static method +- init() method hooks into admin_init to register settings +- render_settings_page() method (hooked by admin-menu.php for "Einstellungen" submenu) + +Register settings using WordPress Settings API: +- register_setting('umzugsliste_settings', 'umzugsliste_receiver_email', sanitize callback) +- register_setting('umzugsliste_settings', 'umzugsliste_captcha_provider', sanitize callback) +- register_setting('umzugsliste_settings', 'umzugsliste_captcha_site_key', sanitize callback) +- register_setting('umzugsliste_settings', 'umzugsliste_captcha_secret_key', sanitize callback) +- register_setting('umzugsliste_settings', 'umzugsliste_thankyou_url', sanitize callback) + +In umzugsliste.php: +- Add Umzugsliste_Settings::get_instance() to init() method (after CPT and admin menu) + +WHY singleton: Consistent with Phase 1 pattern (all plugin classes use singleton). +WHY WordPress Settings API: Standard WordPress approach, integrates with update_option/get_option automatically. + + Class file has no PHP syntax errors (php -l), class can be instantiated, no errors when plugin loads + Settings class created, follows singleton pattern, hooks registered, no PHP errors + + + + Task 2: Add settings sections and fields with German labels + includes/class-settings.php + +Add settings sections and fields to render_settings_page() method. + +Create two sections: +1. **Email-Einstellungen** (Email Settings) + - Field: Empfänger-E-Mail (text input, required, validate email format) + +2. **Captcha-Einstellungen** (Captcha Settings) + - Field: Captcha-Anbieter (select dropdown: Kein Captcha, reCAPTCHA v2, reCAPTCHA v3, hCaptcha) + - Field: Site Key (text input, shown only if captcha selected) + - Field: Secret Key (text input, shown only if captcha selected) + +3. **Formular-Einstellungen** (Form Settings) + - Field: Danke-Seite URL (text input, validate URL format) + +Use add_settings_section() and add_settings_field() with callbacks that render HTML inputs. + +Field rendering callbacks: +- Use German labels and descriptions +- Add field descriptions below inputs (e.g., "Die E-Mail-Adresse, an die Formularanfragen gesendet werden") +- Show/hide captcha key fields based on provider selection (use JavaScript for dynamic display) +- All fields use name attributes matching registered settings (e.g., name="umzugsliste_receiver_email") + +Validation callbacks: +- sanitize_email() for receiver email +- sanitize_text_field() for captcha provider +- sanitize_text_field() for captcha keys (trim whitespace) +- esc_url_raw() for thank you URL + +WHY German labels: Established in Phase 1, primary language for admin users. +WHY validate: Prevent invalid data from breaking email sending or captcha verification. + + Settings page renders at /wp-admin/admin.php?page=umzugsliste-settings with all fields visible, form submits without errors + Settings page renders with 3 sections and all fields, labels in German, validation working + + + + Task 3: Add settings save confirmation and helper method for retrieving settings + includes/class-settings.php + +Add settings_errors() call to render_settings_page() to show save confirmation message after form submission. + +Create public static get_option($key, $default = '') helper method: +- Wraps get_option("umzugsliste_$key", $default) +- Provides clean API for other classes: Umzugsliste_Settings::get_option('receiver_email') +- Returns sanitized value from options table + +Add default values for new installs: +- In register_setting(), set default values via 'default' argument: + - receiver_email: '' (empty - admin must configure) + - captcha_provider: 'none' (no captcha by default) + - captcha_site_key: '' + - captcha_secret_key: '' + - thankyou_url: home_url() (redirect to homepage by default) + +WHY helper method: Cleaner API for form submission handler (Phase 6) and captcha integration (Phase 7). +WHY defaults: Plugin works out-of-box without errors, admin configures only what they need. + + Save settings, see success message, reload page - values persist. Call Umzugsliste_Settings::get_option('receiver_email') returns saved value. + Settings save with confirmation message, get_option() helper works, defaults set for new installs + + + + + +Before declaring plan complete: +- [ ] `php -l includes/class-settings.php` passes without errors +- [ ] Settings page accessible at /wp-admin/admin.php?page=umzugsliste-settings +- [ ] All fields render correctly with German labels +- [ ] Saving settings shows success message and persists values +- [ ] get_option() helper method returns saved values correctly +- [ ] Invalid email addresses are rejected with validation error +- [ ] Invalid URLs are sanitized properly + + + + +- All tasks completed +- Settings class follows singleton pattern from Phase 1 +- WordPress Settings API properly integrated +- All settings save and retrieve correctly +- Validation prevents invalid data +- German labels throughout +- No PHP errors or warnings + + + +After completion, create `.planning/phases/03-settings/03-01-SUMMARY.md`: + +# Phase 3 Plan 1: Settings System Summary + +**Admin settings page with email, captcha, and redirect configuration using WordPress Settings API** + +## Accomplishments + +- Created settings class with WordPress Settings API integration +- Email configuration (receiver address with validation) +- Captcha configuration (provider selection + API keys for 3 providers) +- Form configuration (thank you page URL) +- Settings save/retrieve with proper sanitization + +## Files Created/Modified + +- `includes/class-settings.php` - Settings management class +- `umzugsliste.php` - Added settings initialization + +## Decisions Made + +[Document any implementation decisions or variations from plan] + +## Issues Encountered + +[Document any problems and resolutions, or "None"] + +## Next Phase Readiness + +Settings system complete. Ready for Phase 4 (Form Rendering). + +Phase 4 will use settings to: +- Redirect to configured thank you URL after submission +- Display captcha based on provider selection + +Settings API provides clean interface via Umzugsliste_Settings::get_option('key'). +