10 — Media library and form builder#

10.1 Media library#

Media in the sidebar, and the same component opens as a modal from any image or gallery field. One implementation, two placements.

Alt text#

The detail panel asks for alt text with a short explanation of why. An image inserted without alt text is flagged in the editor outline with a soft warning, and Dashboard -> Needs attention counts images missing alt text. Decorative images get an explicit This image is decorative toggle, which emits alt="" — so a missing alt is always a mistake, never a choice we cannot distinguish.

Upload limits and validation#

Uploads are stored outside the webroot-executable path only by virtue of being on the public disk under storage/app/public, served via the public/storage symlink. The deploy checklist verifies that the webserver does not execute PHP under storage/, and the installer writes a defensive .htaccess (php_flag engine off, RemoveHandler, ForceType text/plain) into the media directory for Apache/LiteSpeed hosts.

Image pipeline#

upload
  -> validate (extension, mime, size)
  -> read with the detected driver (imagick, else gd)
  -> strip EXIF except orientation; apply orientation
  -> resize down if wider than `media.max_width` (default 2560)
  -> encode primary as WebP (quality 82); keep the original file as well
  -> generate variants: thumb 320w, medium 768w, large 1536w (WebP, skipping sizes larger than the source)
  -> write media row with conversions{} and dimensions

• Variants are generated inline on upload, one file at a time, with the request kept small enough for shared-hosting limits. A batch of uploads processes sequentially with visible progress, so a timeout loses at most the file in flight — already-processed files are committed.
• kodepress:media-optimize re-processes files that predate a settings change, in chunks, driven by cron.
• Output markup: <img loading="lazy" decoding="async" width height srcset sizes> with a <picture> wrapper offering WebP and the original type. Width and height are always emitted, so there is no layout shift.
• The first image of the first section (typically a hero) is emitted with loading="eager" and fetchpriority="high"; everything else is lazy. The renderer knows the position, so this needs no user decision.

10.2 Form builder#

Settings -> Forms lists forms; the builder edits one. The form block on a page selects a form by id, so the same form can appear on several pages and all submissions land in one place.

Field types#

Each field has: key (auto from the label, editable, unique), label, placeholder, help, required, width (full / half / third), options (for choice types), default, and conditional (show this field when another field equals a value).

Form settings#

Submission flow#

POST /_kp/forms/{form}
  -> rate limit (per IP + form) and honeypot / fill-time check -> silent 200 on failure for bots
  -> validate against forms.fields (server-side, always; client-side hints too)
  -> handle file fields: validate, run the image pipeline if it is an image, create media rows
  -> store a form_submissions row (when store_submissions)
  -> send notification email (queue connection is sync, so this happens inline)
  -> audit log entry
  -> respond: Livewire swaps in the success message, or redirects

• Email sending inline is a deliberate trade: with no queue worker available, the alternative is a cron delay of up to a minute on a contact form. Failures are caught, the submission is still stored, the user still sees success, and the failure is logged and surfaced in Dashboard -> Needs attention. A submission is never lost because SMTP was down.
• Spam marking: a submission flagged by the honeypot path that still gets stored (because the heuristic is soft) is marked is_spam and hidden from the default list.

Submissions screen#

Per form: a table of submissions with the first three fields as columns, read/unread state, a detail drawer showing every field and the uploaded files, Mark as read, Delete, and Export CSV (current filter, UTF-8 with a BOM so Excel opens Bengali correctly). Unread counts appear as a badge on the sidebar Settings item and on the Dashboard.

Retention: forms.settings.retain_days (default null = forever). When set, a nightly command deletes older submissions and their uploaded files, and the setting screen states what will be deleted.

10.3 Newsletter block#

A thin wrapper: it creates (on first use) a form with a single email field and a consent checkbox, and renders inline. It is a separate block only because it appears in footers constantly and should be one click, not six.

Integrations with external mailing services are out of scope for core; the submission is stored and can be exported. A plugin may push to a provider.

10.4 Backup and restore (Phase 4)#

Settings -> Backup offers a one-click backup producing a ZIP containing a mysqldump-equivalent SQL file (written with PHP, since mysqldump may be unavailable) and the media directory.

Shared hosting makes this the most failure-prone feature in the product, so:

• The backup runs in chunks across cron ticks: schema, then tables in batches of rows, then media in batches of files, appending to the archive and recording progress in a state file. A timeout resumes rather than restarting.
• Progress is visible on the screen (Backing up: media 340/1200) with a resumable state after a browser close.
• The archive is written to storage/app/backups with a random filename, is never reachable from the web, and is downloaded through an authenticated streaming route.
• Restore asks the owner to type the site name to confirm, takes a safety backup of the current database first, and restores in the same chunked manner. It refuses an archive whose manifest version is newer than the running code.
• Retention: keep the last N (default 3) local backups; the screen shows the disk space used, because filling a shared-hosting quota breaks the live site.

10.5 Tests for this document#

KodePress documentation · generated from the Markdown sources by tools/build-docs-site.py · internal preview, not indexed.