Skip to content

DX: Configure Xdebug 3, Enable Early Hints, and Document Asset Hot Reload #26

Open
Open
DX: Configure Xdebug 3, Enable Early Hints, and Document Asset Hot Reload#26

Description

@llegaz
llegaz
opened on Sep 8, 2026

DX: Configure Xdebug 3, Enable Early Hints, and Document Asset Hot Reload

a somewhat catch-all issue

Summary

Improve developer experience (DX) and leverage FrankenPHP's modern HTTP capabilities by finalizing the Xdebug setup, enabling 103 Early Hints support, and documenting the asset hot reload workflow.

Tasks

1. Xdebug 3 Configuration

  • Set XDEBUG_MODE=off by default in docker-compose.yml to ensure zero performance overhead.
  • Configure xdebug.start_with_request=trigger and xdebug.discover_client_host=true so debugging only starts when invoked via browser extension/cookie.
  • Ensure extra_hosts with "host.docker.internal:host-gateway" is present in docker-compose.yml for seamless Linux host resolution.

2. HTTP 103 Early Hints

  • Ensure HTTP/2 and HTTP/3 support is properly configured in the Caddyfile.
  • Add a middleware or helper example to send early Link headers (rel=preload, rel=modulepreload) prior to generating full HTML responses.

3. Front-end & Hot Reload Documentation

  • Add a short DX section in README.md explaining:
    • FrankenPHP's native file watcher (--watch) for PHP code changes.
    • Recommended setup for front-end asset hot-reloading (e.g., Vite HMR).

Acceptance Criteria

  • Xdebug triggers properly from IDE (at least NetBeans) without slowing down standard requests.
  • Server returns 103 Early Hints status when headers are flushed early.
  • Clear setup instructions are available in the project README.md.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions