LWP::Protocol(3)

💅 LWP::Protocol — like, the base class for LWP protocols, bestie

okay so real quick: this is a page from User Contributed Perl Documentation (the LWP::Protocol(3) one, iykyk), and it's genuinely the blueprint every other LWP protocol class is built on. buckle up 🎀

---

✨ NAME ✨

LWP::Protocol — the actual base class for LWP protocols, no cap. every protocol implementation in the LWP library inherits from this one. she's the mother. 👑

---

🌸 SYNOPSIS 🌸

package LWP::Protocol::foo;
use parent qw(LWP::Protocol);

that's literally it. that's the whole vibe check. you make your own LWP::Protocol::foo package and you use parent qw(LWP::Protocol) and now you're part of the family 🫶

---

🦋 DESCRIPTION 🦋

so this class is used as the base class for, like, all protocol implementations supported by the LWP library. every single one. she's giving main character energy but make it infrastructure.

when you create an instance of this class using LWP::Protocol::create($url), you get back an initialized subclass that's appropriate for that access method. in other words — and this is the part that's so cute — the create in LWP::Protocol function calls the constructor for one of its subclasses. she doesn't do the work herself, she just knows who to call. delegation queen 💅

all derived LWP::Protocol classes need to override the request() method, which is what's used to service a request. and the overridden method can totally make use of the collect() method to collect together chunks of data as they're received. teamwork, bestie ✨

---

💖 METHODS 💖

the following methods and functions are provided:

🎀 new

my $prot = LWP::Protocol->new();

the LWP::Protocol constructor is inherited by subclasses. but listen — as this is a virtual base class, this method should not be called directly. like, don't. it's a vibe thing. 🙈

🎀 create

my $prot = LWP::Protocol::create($scheme)

create an object of the class implementing the protocol to handle the given scheme. important detail: this is a function, not a method. it's more an object factory than a constructor. this is the function user agents should use to access protocols. she's the plug, not the product 🫶

🎀 implementor

my $class = LWP::Protocol::implementor($scheme, [$class])

get and/or set the implementor class for a scheme. returns '' if the specified scheme is not supported. short, sweet, does exactly what it says on the tin. ⭐

🎀 request

$response = $protocol->request($request, $proxy, undef);
$response = $protocol->request($request, $proxy, '/tmp/sss');
$response = $protocol->request($request, $proxy, \&callback, 1024);
$response = $protocol->request($request, $proxy, $fh);

dispatches a request over the protocol and returns a response object. this method needs to be overridden in subclasses — so if you're writing a subclass and you skip this, that's on you, bestie 😭. refer to LWP::UserAgent for the description of the arguments. go read it. i'll wait. 🍓

🎀 collect

my $res = $prot->collect(undef, $response, $collector); # stored in $response
my $res = $prot->collect($filename, $response, $collector);
my $res = $prot->collect(sub { ... }, $response, $collector);

collect the content of a request and process it appropriately — into a scalar, a file, or by calling a callback. let's break down the first parameter, because it's doing a lot:

• if it's undefined, the content is stored within the $response.
• if it's a simple scalar, it's interpreted as a file name and the content is written to this file.
• if it's a code reference, the content is passed to this routine.
• if it's a filehandle, or similar, such as a File::Temp object, content will be written to it.

the collector is a routine that will be called and which is responsible for returning pieces (as ref to scalar) of the content to process. the $collector signals "EOF" by returning a reference to an empty string. that's the lil' goodbye wave 👋✨

the return value is the HTTP::Response object reference.

note: we will only use the callback or file argument if $response->is_success(). this avoids sending content data for redirects and authentication responses to the callback, which would be confusing. she's protecting you from yourself, fr fr. 🙈💀

🎀 collect_once

$prot->collect_once($arg, $response, $content)

can be called when the whole response content is available as content. this will invoke "collect" in LWP::Protocol with a collector callback that returns a reference to $content the first time and an empty string the next. one and done, iconic behaviour 👑

---

🌈 SEE ALSO 🌈

inspect the LWP/Protocol/file.pm and LWP/Protocol/http.pm files for examples of usage. literally go look at them, they're right there, they ate 🔥

---

⭐ COPYRIGHT ⭐

copyright 1995-2001 Gisle Aas.

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

---

and that's the whole page, bestie! 💜 this lil' beauty is from perl v5.42.0, dated 2026-05-18, and it lives at LWP::Protocol(3) — go forth and subclass responsibly 🧚‍♀️✨