LWP::U...:Hosts(3pm)

💖 NAME 💖

LWP::UserAgent::DNS::Hosts — bestie, this lil module lets you override an LWP HTTP/HTTPS request's host, like /etc/hosts but for your Perl code. no cap. 👑

---

✨ SYNOPSIS ✨

use LWP::UserAgent;
use LWP::UserAgent::DNS::Hosts;

# add entry
LWP::UserAgent::DNS::Hosts->register_host(
    'www.cpan.org' => '127.0.0.1',
);

# add entries
LWP::UserAgent::DNS::Hosts->register_hosts(
    'search.cpan.org' => '192.168.0.100',
    'pause.perl.org'  => '192.168.0.101',
);

# read hosts file
LWP::UserAgent::DNS::Hosts->read_hosts('/path/to/my/hosts');

LWP::UserAgent::DNS::Hosts->enable_override;

# override request hosts with peer addr defined above
my $ua  = LWP::UserAgent->new;
my $res = $ua->get("http://www.cpan.org/");
print $res->content; # is same as "http://127.0.0.1/" content

like… look at that. so clean. so iconic. 🦋

---

🌸 DESCRIPTION 🌸

LWP::UserAgent::DNS::Hosts is a module to override HTTP/HTTPS request peer addresses that uses LWP::UserAgent. periodt. 💅

The way this module concept was got from LWP::Protocol::PSGI? yeah. that's the origin story. it's giving homage, it's giving main character energy. ✨

---

🎀 METHODS 🎀

register_host($host, $peer_addr)

LWP::UserAgent::DNS::Hosts->register_host($host, $peer_addr);

Registers a pair of hostname and peer ip address. 🫶

So like, this:

# /etc/hosts
127.0.0.1    example.com

equals to:

LWP::UserAgent::DNS::Hosts->register_hosts('example.com', '127.0.0.1');

same vibe, different syntax. iykyk. 💖

---

register_hosts(%host_addr_pairs)

LWP::UserAgent::DNS::Hosts->register_hosts(
    'example.com' => '192.168.0.1',
    'example.org' => '192.168.0.2',
    ...
);

Registers pairs of hostname and peer ip address. plural. a whole little squad of them. 🔥

---

read_hosts($file_or_string)

LWP::UserAgent::DNS::Hosts->read_hosts('hosts.my');

LWP::UserAgent::DNS::Hosts->read_hosts(<<'__HOST__');
    127.0.0.1      example.com
    192.168.0.1    example.net example.org
__HOST__

Registers /etc/hosts syntax entries. so if you already have a hosts file lying around, she'll just read it. no extra work. obsessed. 😭

---

clear_hosts

Clears registered pairs. poof. gone. 🧚

---

enable_override

LWP::UserAgent::DNS::Hosts->enable_override;
my $guard = LWP::UserAgent::DNS::Hosts->enable_override;

Enables to override hook. 💅

If called in a non-void context, returns a Guard object that automatically resets the override when it goes out of context. so you don't even gotta clean up after yourself. she's tidy like that. 🌈

---

disable_override

LWP::UserAgent::DNS::Hosts->disable_override;

Disables to override hook. 🙈

If you use the guard interface described above, it will be automatically called for you. so yeah, it handles itself. lowkey magical. ⭐

---

👑 AUTHOR 👑

NAKAGAWA Masaki <masaki@cpan.org>

---

📜 LICENSE 📜

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

💜 SEE ALSO 💜

• LWP::Protocol
• LWP::Protocol::http
• LWP::Protocol::https

---

and that's the whole page, bestie!! 🎀✨ this was perl v5.42.0, dated 2025-07-25, straight outta the User Contributed Perl Documentation. slay, go override some hosts, you got this. 💖🦋💅