[Medzoner]

Fixes #119

What and why

Add support for project-specific HTTP handler directives in .flock/Caddyfile. Flock imports the file into the route that serves the PHP site and watches it for automatic reloads. This supports local concerns such as CORS headers and preflight responses without replacing Flock’s generated Caddy configuration.

Custom handlers run after an ordered loopback guard, so terminating handle or route directives cannot bypass Flock’s local-only protection. Redirect and unlinked-page blocks do not import project handlers.

The site documentation now describes the supported handler scope and includes a CORS example.

How I tested it

• go test -race ./...
• go vet ./...
• test -z "$(gofmt -l .)"
• git diff --check
• Integration test starts embedded Caddy and verifies a CORS preflight response
• Independent code review approved

[Medzoner]

@onairmarc could you please approve the pending Build workflow and request a Copilot review when you get a chance?

The full Go race suite, lint, docs lint, and a Windows cross-build pass locally. The integration test starts embedded Caddy and verifies the custom handler with a CORS preflight response. Thanks!

[Copilot]

🟡 Changes recommended

Bracketed project paths break Caddy adaptation, Xdebug dispatch can bypass custom handlers, and tests do not verify non-loopback access protection.

3 open issues

• Bracketed project paths break Caddyfile import adaptation · New
• Xdebug handles bypass custom headers and preflight responses · New
• Test remote-request rejection against the adapted handler chain · New

What changed in this PR

Adds per-project .flock/Caddyfile support so PHP sites can customize HTTP handling, including CORS, without replacing Flock’s generated configuration.

Changes:

• Imports custom handlers into an ordered route with a local-access guard, excluding redirect and unlinked-page blocks.
• Detects project Caddyfile changes for automatic reloads.
• Documents handler scope and adds configuration, file-watching, and CORS preflight tests.

File	Description
internal/​web/​web.go	Adds the optional Caddyfile path and guarded handler imports.
internal/​web/​web_test.go	Tests import placement and configuration adaptation.
internal/​web/​serve_test.go	Tests a custom CORS preflight response through embedded Caddy.
internal/​daemon/​daemon.go	Discovers project Caddyfiles and tracks changes for reloads.
internal/​daemon/​daemon_test.go	Tests that adding a Caddyfile changes the project fingerprint.
docs/​sites.md	Documents supported handlers, reload behavior, and a CORS example.

_{Review effort: Balanced}

[onairmarc]

copilot changes

[Medzoner]

@onairmarc all three Copilot findings are addressed in d13a28a, with regression coverage for bracketed paths, Xdebug dispatch, and the wildcard-listener remote guard. The full race suite, vet, docs lint, formatting, Windows cross-build, and an independent review pass locally. The new Build run is waiting for approval again: https://github.com/flock-php/flock/actions/runs/42398809205. Ready for another look once it completes.

[onairmarc]

I'd like to avoid adding noise to the user's repository root if we can. One of my big pet peeves is having to add another config file/directory just to use a tool. If we can make Flock easier to use without adding repo noise, we should.

If they want to change what file Flock should look at, perhaps a new FLOCK_ prefixed value in the .env file.

[Medzoner]

@onairmarc thanks — I may have interpreted “make Flock easier to use without adding repo noise” too narrowly. I changed discovery to the existing root Caddyfile, with FLOCK_CADDYFILE as an override, but that still requires a file.

Do you want this exposed per site in Settings → Sites and stored machine-locally by Flock, so no repository file is needed? If so, should the apps provide:

1. a multiline editor for Caddy HTTP handlers stored in config.json, or
2. a file picker/path setting, with the handler file kept outside the repository?

I can implement it consistently across macOS, Windows, and Linux once the intended UX/storage is confirmed. We could keep root Caddyfile / FLOCK_CADDYFILE only as an optional advanced override if desired.

[onairmarc]

@onairmarc thanks — I may have interpreted “make Flock easier to use without adding repo noise” too narrowly. I changed discovery to the existing root Caddyfile, with FLOCK_CADDYFILE as an override, but that still requires a file.

This is perfect! Since the .env file is common in the local development environment, it belongs there! Thank you!

[lukas-frey]

@onairmarc I pushed a follow-up on top of this. Instead of the root Caddyfile or FLOCK_CADDYFILE in .env, the file is now named in flock.yml (caddyfile: local.caddy), and flock.local.yml can replace it for one machine. That keeps Flock's settings in the files it already uses, and a project's own production Caddyfile is left alone. Without the key nothing changes.

If Flock can't use the file, it shows a warning and serves only that site without it, instead of failing the whole reload. Unbalanced braces and import are rejected, so the directives can't leave the site block. The remote guard fix this relies on landed separately in #132.

Thanks @Medzoner for the groundwork!