docs(03): create phase plan
Phase 03: Settings System - 1 plan created - 3 tasks defined - Ready for execution
This commit is contained in:
204
.planning/phases/03-settings/03-01-PLAN.md
Normal file
204
.planning/phases/03-settings/03-01-PLAN.md
Normal file
@@ -0,0 +1,204 @@
|
||||
---
|
||||
phase: 03-settings
|
||||
plan: 01
|
||||
type: execute
|
||||
depends_on: ["01-01"]
|
||||
files_modified: [includes/class-settings.php, umzugsliste.php]
|
||||
---
|
||||
|
||||
<objective>
|
||||
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.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
~/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.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()
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Create settings class with WordPress Settings API registration</name>
|
||||
<files>includes/class-settings.php, umzugsliste.php</files>
|
||||
<action>
|
||||
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.
|
||||
</action>
|
||||
<verify>Class file has no PHP syntax errors (php -l), class can be instantiated, no errors when plugin loads</verify>
|
||||
<done>Settings class created, follows singleton pattern, hooks registered, no PHP errors</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Add settings sections and fields with German labels</name>
|
||||
<files>includes/class-settings.php</files>
|
||||
<action>
|
||||
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.
|
||||
</action>
|
||||
<verify>Settings page renders at /wp-admin/admin.php?page=umzugsliste-settings with all fields visible, form submits without errors</verify>
|
||||
<done>Settings page renders with 3 sections and all fields, labels in German, validation working</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Add settings save confirmation and helper method for retrieving settings</name>
|
||||
<files>includes/class-settings.php</files>
|
||||
<action>
|
||||
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.
|
||||
</action>
|
||||
<verify>Save settings, see success message, reload page - values persist. Call Umzugsliste_Settings::get_option('receiver_email') returns saved value.</verify>
|
||||
<done>Settings save with confirmation message, get_option() helper works, defaults set for new installs</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
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
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- 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
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
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').
|
||||
</output>
|
||||
Reference in New Issue
Block a user