The hosts file is not yours alone
Herd keeps a block there. So does Laragon. So do hand-written entries nobody remembers adding. How to add local domains without destroying somebody else’s setup, and how to do it without running the whole app as administrator.
A local development tool that serves my-app.test has to make that name
resolve, and on Windows that means editing
C:\Windows\System32\drivers\etc\hosts. It is a shared, system-owned file that
other tools are also writing to. Here is how to edit it without breaking
somebody else's setup.
The file is not yours
A developer's hosts file accumulates. Laravel Herd keeps a block there. So does Laragon. So do hand-written entries for staging servers, blocked domains and whatever someone added two years ago and forgot.
Rewriting the file wholesale, which is the easy implementation: destroys all of it. The user finds out when an unrelated project stops resolving, and has no reason to connect that to the tool they installed yesterday.
Own a block, not the file
# BEGIN Libxa Desktop - managed automatically, do not edit
127.0.0.1 franky.test
127.0.0.1 libxastack.test
127.0.0.1 phpmyadminlibxa.test
# END Libxa Desktop
Everything outside those two markers is preserved byte-for-byte. The algorithm is: find the markers, split the file into before / block / after, replace only the middle, write it back.
Two details worth getting right:
Search for the marker as a prefix. The first version of ours ended with an
em dash and a note. Changing that text later would have orphaned every block
already written: the code would no longer recognise its own marker and would
append a second one. Matching on # BEGIN Libxa Desktop and writing whatever
suffix you like after it makes the marker text safe to change.
Keep the marker ASCII. The resolver reads this file in the system codepage.
Our em dash came back as â€" in every other tool that opened the file.
Harmless: it is a comment, but there is no reason to put non-ASCII in a file
this old.
Writing it needs elevation
The hosts file is only writable by administrators. Two ways to handle that:
- Run the whole application elevated.
- Run normally and elevate only the write.
The first is what many tools do and it is the wrong trade. An app that manages downloads, spawns processes and serves web content should not spend its entire lifetime with administrator rights so that it can occasionally append four lines.
So: stage the new content to a temp file, then ask Windows to copy it with a single elevated step.
Start-Process -FilePath cmd.exe `
-ArgumentList '/c','copy','/y','<staged>','<hosts>' `
-Verb RunAs -Wait -PassThru
-Verb RunAs raises the UAC prompt. -Wait means we report the real outcome
instead of returning before the copy has happened. Staging the content avoids
putting a multi-line file through a command line that would need heavy quoting.
A declined UAC prompt is a user decision, not a malfunction, and is reported that way:
Administrator permission was declined, so the hosts file was not changed.
Ports are part of the address
One thing that surprises people: adding 127.0.0.1 my-app.test does not mean
http://my-app.test works.
Port 80 needs elevation on Windows and is usually already taken: by IIS, by
another local stack, or by a Hyper-V reserved range. Libxa Desktop defaults to
a high port, which means the working address is my-app.test:8000.
The hosts file has no concept of ports; it maps names to addresses. So the app shows the full URL, including the port, everywhere a site is listed. Showing the bare domain would be showing an address that does not load.
Say when it is not done
If a domain is not in the file yet, the browser shows
DNS_PROBE_FINISHED_NXDOMAIN, which tells the user nothing about what to do.
So the app checks before opening: the Sites tab shows which domains are missing, with a button to add them, and clicking a site whose domain does not resolve says so instead of opening a dead tab.