Project-Pro/vidok.com
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Jacek Pyziak
2026-05-05 22:36:55 +02:00
parent cf1a0adb0b
commit cb077e80d8
39 changed files with 812 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
.paul/phases/01-contact-attachments/01-01-PLAN.md Normal file
View File

@@ -0,0 +1,193 @@
---
phase: 01-contact-attachments
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- plugins/special-actions-middle.php
- templates_user/pages/page-contact-v9.php
- templates_user/modal/modal.php
autonomous: true
delegation: off
---
<objective>
## Goal
Persist uploaded files from contact forms as public attachment links in the same database row as the rest of the contact form data.
## Purpose
Clients already attach project files to contact requests, but those files are only sent by email and currently use temporary storage. Sales/support should be able to recover submitted attachments from the database after the temp folder is cleaned.
## Output
- `contact_messages.attachments` column is created automatically when needed.
- Uploaded contact files are stored in a dedicated public folder outside `temp/`.
- `saveContactData()` stores attachment links in the new column.
- The live contact page and modal communicate the allowed file types and 50 MB limit.
</objective>
<context>
<clarifications>
- **Zakres** - Obejmujemy formularze z plikami?
-> Odpowiedz: Tyle te z plikami.
- **Baza** - Zapisywac zalaczniki jako jedna kolumna czy osobna tabela?
-> Odpowiedz: Jako jedna kolumna.
- **Linki** - Publiczny link czy sciezka serwerowa?
-> Odpowiedz: Publiczny link, ale dedykowanym folderze, nie temp bo ten jest czyszczony automatycznie.
- **Limit** - Ograniczyc typy i rozmiar plikow?
-> Odpowiedz: Ograniczmy. Limit dajmy na 50 MB, tylko musi byc o tym informacja w formularzach.
</clarifications>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
@.paul/codebase/architecture.md
@.paul/codebase/db_schema.md
## Source Files
@plugins/special-actions-middle.php
@templates_user/pages/page-contact-v9.php
@templates_user/modal/modal.php
@config.php
## Current Findings
- `saveContactData()` inserts into external table `contact_messages` using a direct PDO connection in `plugins/special-actions-middle.php`.
- Contact form handlers already read `$_FILES['files']`, move uploads to `temp/`, and pass those temp paths to email sending.
- The live contact template `templates_user/pages/page-contact-v9.php` contains file inputs for `send-contact-form-new-2` and `send-contact-form-new-deweloper`.
- The popup template `templates_user/modal/modal.php` contains file input for `send-contact-modal`.
- File uploader JS currently uses `fileMaxSize: 10`; server validation only blocks `.php`.
- `.paul/SPECIAL-FLOWS.md` is not present, so no specialized apply skills are required.
</context>
<acceptance_criteria>
## AC-1: Persistent Attachment Links
```gherkin
Given a user submits a contact form with one or more valid files
When the form is accepted and saved by saveContactData()
Then each uploaded file is stored in a dedicated public contact attachments folder
And the matching contact_messages row contains public attachment links in one attachments column
And email delivery still receives the same uploaded files as attachments
```
## AC-2: Automatic Database Upgrade
```gherkin
Given the production database does not yet have the attachments column
When the first contact submission is saved after deployment
Then the code automatically adds contact_messages.attachments without requiring a manual migration step
And the form save continues without losing the submission
```
## AC-3: Upload Restrictions
```gherkin
Given a user uploads a disallowed extension or a file larger than 50 MB
When the form handler processes the submission
Then the invalid file is not persisted or emailed
And the user receives a normal form failure alert rather than a PHP warning or partial unsafe upload
```
## AC-4: Form Limit Information
```gherkin
Given a user views the live contact form or modal contact form
When they reach the file upload field
Then the UI states the 50 MB per-file limit and allowed file types
And the client-side uploader enforces the same 50 MB limit as the server
```
</acceptance_criteria>
<tasks>
<task type="auto">
<name>Task 1: Add attachment persistence helpers and schema self-upgrade</name>
<files>plugins/special-actions-middle.php</files>
<action>
Add small helper functions near `saveContactData()`:
- define allowed upload extensions for contact forms: `pdf`, `jpg`, `jpeg`, `png`, `doc`, `docx`, `xls`, `xlsx`, `csv`, `txt`, `xml`, `dwg`, `dxf`, `zip`;
- define 50 MB per-file server limit;
- normalize `$_FILES['files']` so both single and multiple upload shapes are handled;
- save files under `uploads/contact-attachments/YYYY/mm/`, creating directories when missing;
- generate collision-resistant file names using a random suffix and sanitized extension/name;
- return both server paths for `\S::send_email()` and public URLs for database storage;
- block invalid extension, failed upload status, non-uploaded temp files, and oversize files.
Update `saveContactData()` to accept an optional `$attachments` argument, call an `ensureContactMessagesAttachmentsColumn(PDO $pdo)` helper before insert, and store `attachments` as JSON in one `TEXT NULL` column.
Avoid storing files in `temp/` because it is automatically cleaned.
</action>
<verify>php -l plugins/special-actions-middle.php</verify>
<done>AC-1, AC-2, and AC-3 satisfied for backend behavior.</done>
</task>
<task type="auto">
<name>Task 2: Wire contact form handlers to persisted uploads</name>
<files>plugins/special-actions-middle.php</files>
<action>
Replace duplicated upload loops for the forms that currently accept files with the new helper:
- `send-contact-modal`;
- `send-contact-form-new`;
- `send-contact-form-new-2`;
- `send-contact-form-new-deweloper`;
- include `send-contact-landing` only if its current file input is intentionally part of the page/form scope during implementation.
Pass returned server paths to existing `\S::send_email()` calls and returned public links to `saveContactData()`.
Initialize `$files_to_send` safely before use so submissions without files do not create notices.
If any uploaded file is invalid, stop the submission with the existing alert/redirect pattern and do not save partial contact data.
Keep recipients, recaptcha behavior, and existing form validation unchanged.
</action>
<verify>php -l plugins/special-actions-middle.php and code inspection showing every targeted saveContactData() call receives the attachment links argument.</verify>
<done>AC-1 and AC-3 satisfied for each in-scope form handler.</done>
</task>
<task type="auto">
<name>Task 3: Update contact and modal upload UI limits</name>
<files>templates_user/pages/page-contact-v9.php, templates_user/modal/modal.php</files>
<action>
Update the visible file upload copy in both files to mention:
- maximum 50 MB per file;
- allowed file types matching the server allowlist.
Change fileuploader `fileMaxSize` from `10` to `50` in both templates.
Ensure client-side `extensions` matches the backend allowlist and remove non-extension values such as `text/plain`.
Keep existing layout, tracking scripts, form IDs, and recaptcha markup unchanged.
</action>
<verify>php -l templates_user/pages/page-contact-v9.php; php -l templates_user/modal/modal.php</verify>
<done>AC-4 satisfied for the live contact page and popup modal contact form.</done>
</task>
</tasks>
<boundaries>
## DO NOT CHANGE
- Do not change database credentials, email recipients, recaptcha keys, tokens, or anti-spam word lists in this plan.
- Do not refactor unrelated form handlers or admin panel code.
- Do not move existing historical files out of `temp/`; only new uploads from targeted forms should use the dedicated folder.
- Do not create a separate attachments table; the agreed schema is one column on `contact_messages`.
## SCOPE LIMITS
- This plan stores public links in the database; it does not build an admin UI for browsing/downloading them.
- This plan does not retroactively recover attachments from previous submissions.
- This plan targets the current contact page template and modal. Older unused contact template versions should only be changed if implementation proves they are still rendered in production.
</boundaries>
<verification>
Before declaring plan complete:
- [ ] `php -l plugins/special-actions-middle.php`
- [ ] `php -l templates_user/pages/page-contact-v9.php`
- [ ] `php -l templates_user/modal/modal.php`
- [ ] Inspect generated SQL path: missing `contact_messages.attachments` triggers one safe `ALTER TABLE`.
- [ ] Inspect upload path: new files go to `uploads/contact-attachments/YYYY/mm/`, not `temp/`.
- [ ] Inspect in-scope `saveContactData()` calls: attachment links are passed for file-enabled forms.
- [ ] Confirm visible form copy and JS uploader limit say/enforce 50 MB.
</verification>
<success_criteria>
- All in-scope file-enabled forms keep sending emails with uploaded files.
- Accepted uploaded files are retained outside `temp/`.
- `contact_messages.attachments` is created automatically and populated with public links.
- Server and client enforce matching file types and 50 MB per-file limit.
- No unrelated files or PAUL-untracked user changes are reverted.
</success_criteria>
<output>
After completion, create `.paul/phases/01-contact-attachments/01-01-SUMMARY.md`.
</output>

140
.paul/phases/01-contact-attachments/01-01-SUMMARY.md Normal file
View File

@@ -0,0 +1,140 @@
---
phase: 01-contact-attachments
plan: 01
subsystem: forms
tags: [php, mysql, uploads, contact-forms]
requires: []
provides:
- Persistent public attachment links for file-enabled contact forms
- Automatic `contact_messages.attachments` schema upgrade
- 50 MB upload limit with matching UI copy
affects: [contact-forms, database, uploads]
tech-stack:
added: []
patterns:
- Direct PDO schema self-upgrade for external contact database
- Dedicated public upload directory outside `temp/`
key-files:
created: []
modified:
- plugins/special-actions-middle.php
- templates_user/pages/page-contact-v9.php
- templates_user/modal/modal.php
- .paul/codebase/db_schema.md
- .paul/codebase/tech_changelog.md
key-decisions:
- "Store attachment links in one `contact_messages.attachments` column as JSON."
- "Use public links under `/uploads/contact-attachments/YYYY/mm/`."
- "Restrict uploads to an extension allowlist and 50 MB per file."
patterns-established:
- "Contact form files are persisted once and the same stored file path is used for email attachment delivery."
duration: ~20min
started: 2026-05-05T22:11:41+02:00
completed: 2026-05-05T22:33:44+02:00
---
# Phase 1 Plan 01: Contact Attachments Summary
File-enabled contact forms now persist uploaded files outside `temp/` and store public links in the contact submission row.
## Performance
| Metric | Value |
|--------|-------|
| Duration | ~20 min |
| Started | 2026-05-05T22:11:41+02:00 |
| Completed | 2026-05-05T22:33:44+02:00 |
| Tasks | 3 completed |
| Files modified | 5 implementation/docs files plus PAUL state files |
## Acceptance Criteria Results
| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Persistent Attachment Links | Pass | Production test confirmed latest `contact_messages` row contains a JSON attachment link and the public PDF URL returns HTTP 200. |
| AC-2: Automatic Database Upgrade | Pass | `ensureContactMessagesAttachmentsColumn()` creates `attachments TEXT NULL` when missing and tolerates duplicate-column races. |
| AC-3: Upload Restrictions | Pass | Backend allowlist and 50 MB limit added; invalid uploads stop before partial DB save/email. |
| AC-4: Form Limit Information | Pass | Current contact page and modal state 50 MB and allowed types; fileuploader config uses matching limit/extensions. |
## Accomplishments
- Added reusable contact attachment upload handling in `plugins/special-actions-middle.php`.
- Replaced targeted `temp/` upload loops for `/kontakt/` file-enabled handlers and `modal-contact-form`.
- Added automatic schema evolution for `contact_messages.attachments`.
- Updated visible upload guidance and client-side validation to match server rules.
- Verified a real production submission with attachment saved correctly.
## Task Commits
No git commit was created during UNIFY. The worktree had extensive pre-existing unrelated changes, including modified files touched by this phase, so committing would risk bundling user work. Commit intentionally deferred.
## Files Created/Modified
| File | Change | Purpose |
|------|--------|---------|
| `plugins/special-actions-middle.php` | Modified | Upload persistence helper, schema self-upgrade, attachment links passed to `saveContactData()`. |
| `templates_user/pages/page-contact-v9.php` | Modified | Upload copy and fileuploader limit/extensions for current contact page. |
| `templates_user/modal/modal.php` | Modified | Upload copy and fileuploader limit/extensions for modal form. |
| `.paul/codebase/db_schema.md` | Modified | Documented external `contact_messages` schema and `attachments` column. |
| `.paul/codebase/tech_changelog.md` | Modified | Recorded technical change for future context. |
| `.paul/changelog/2026-05-05.md` | Created | Human-readable PAUL changelog entry. |
| `.paul/STATE.md` | Modified | Loop and phase state closure. |
| `.paul/ROADMAP.md` | Modified | Phase marked complete. |
| `.paul/PROJECT.md` | Modified | Requirement moved into shipped/validated context. |
## Decisions Made
| Decision | Rationale | Impact |
|----------|-----------|--------|
| Store public links in one column | User chose one-column storage; simplest production migration. | `attachments` stores JSON array of public paths. |
| Dedicated public upload folder | `temp/` is cleaned automatically. | New uploads go to `/uploads/contact-attachments/YYYY/mm/`. |
| Restrict uploads to allowlist + 50 MB | User requested restrictions and visible limit. | Server and UI now enforce aligned rules. |
| Defer landing page upload persistence | Request scoped to `/kontakt/` and modal. | `send-contact-landing` still uses legacy temp flow and is documented as deferred. |
| Skip automatic git commit | Dirty worktree contained pre-existing unrelated/user changes. | No accidental commit of unrelated work; manual commit can be made later. |
## Deviations from Plan
### Summary
| Type | Count | Impact |
|------|-------|--------|
| Deferred | 1 | Landing page handler remains legacy because it is outside requested scope. |
| Transition deviation | 1 | Git commit skipped to avoid bundling pre-existing dirty worktree changes. |
### Auto-fixed Issues
**1. Duplicate-column race tolerance**
- **Found during:** Task 1 review
- **Issue:** Two simultaneous first submissions could both try to add `attachments`.
- **Fix:** Duplicate-column PDO errors are tolerated after the second request loses the race.
- **Files:** `plugins/special-actions-middle.php`
- **Verification:** `php -l plugins/special-actions-middle.php`
### Deferred Items
- Landing page attachment persistence can be planned separately if `send-contact-landing` should also retain uploads outside `temp/`.
## Issues Encountered
| Issue | Resolution |
|-------|------------|
| Direct DB access from local machine failed because `mysql8` is internal and external DB access is denied. | Used a short-lived FTP-uploaded diagnostic script on the production webroot, then deleted it. |
| Initial diagnostic `file_exists()` check was false due hosting `DOCUMENT_ROOT` behavior. | Verified the public URL returns HTTP 200 and FTP confirms the file exists at the expected path. |
## Next Phase Readiness
**Ready:**
- `/kontakt/` file-enabled forms and modal now retain uploaded attachments.
- Database schema self-upgrade is in place.
- Public upload directory pattern is established.
**Concerns:**
- The project still has broader security concerns documented in `.paul/codebase/concerns.md`.
- The landing page upload flow still uses `temp/` if that page remains business-critical.
**Blockers:**
- None for this phase.
---
*Phase: 01-contact-attachments, Plan: 01*
*Completed: 2026-05-05*