HTTP::...rFilter(3pm)

✨ NAME ✨

HTTP::Proxy::HeaderFilter — bestie, it's literally a base class for HTTP message header filters 💅 (that's the HTTP::...rFilter(3pm) you clicked on, from the User Contributed Perl Documentation manual, no cap)

---

🌸 SYNOPSIS 🌸

package MyFilter;

use base qw( HTTP::Proxy::HeaderFilter );

# changes the User-Agent header in all requests
# this filter must be pushed on the request stack
sub filter {
    my ( $self, $headers, $message ) = @_;

    $message->headers->header( User_Agent => 'MyFilter/1.0' );
}

1;

---

🦋 DESCRIPTION 🦋

okay so listen. The HTTP::Proxy::HeaderFilter class is the blueprint you use to build filters that mess with HTTP request/response headers. That's the whole vibe. 👑

🎀 Creating a HeaderFilter

A HeaderFilter is just a derived class (yes, a subclass, we're being fancy) that implements a couple of methods the proxy calls on its own. And of all the methods listed down here, literally only filter() has to be defined in your derived class. The rest are optional, so breathe. 🫶

filter()

The signature of the filter() method is exactly this, character for character:

sub filter { my ( $self, $headers, $message) = @_; ... }

where $self is the filter object, $headers is a HTTP::Headers object, and $message is either a HTTP::Request or a HTTP::Response object. Three args, that's it, slay. ✨

The $headers HTTP::Headers object is the one that will actually get sent to the client (if your filter is sitting on the response stack) or to the origin server (if your filter is on the request stack). And if your filter modifies $headers, then the modified headers are what get sent to the client or the server. So like… you change it, it ships. That's the power. 💅

The init() method (if it exists) is called by the new() constructeur to do all the initisalisation tasks. It gets called once in the filter lifetime. One time. That's it. 🎀

A HTTP::Proxy::HeaderFilter object is a blessed hash, and the base class reserves only hash keys that start with "_hphf". So don't touch those, bestie, they're not yours. 🙈

new()

The constructor is defined for all subclasses — you don't write it, it's already there. Any initialisation tasks your subclass needs (if any) go in the init() method instead (peep below 👇).

init()

This method is called by the new() constructeur to perform all the initisalisation tasks. It's called once in the filter lifetime. ⭐

It receives all the parameters passed to new(). All of them. Every single one. 🫶

🌈 Standard HeaderFilters

Standard HTTP::Proxy::HeaderFilter classes are lowercase. (iykyk, it's a naming convention thing.)

The following HeaderFilters are included in the HTTP::Proxy distribution:

• simple — this class lets you create a simple header filter from a code reference. Iconic, low effort, big results. ✨
• standard — this is the filter that provides standard headers handling for HTTP::Proxy. It gets loaded automatically by HTTP::Proxy, so you don't even have to do anything. Main character energy fr fr. 👑

Please read each filter's documentation for more details about their use. (Do it. Go read it. I'll wait. 🍓)

---

💖 USEFUL METHODS FOR SUBCLASSES 💖

Some methods are available to filters, so they can eventually use the little knowledge they might have of HTTP::Proxy's internals. They're mostly accessors. Lowkey handy.

proxy()

Gets a reference to the HTTP::Proxy object that owns the filter. This gives you access to some of the proxy methods. It's giving "backstage pass". 🎟️

---

🌟 AUTHOR 🌟

Philippe "BooK" Bruhat, <book@cpan.org>. A legend. We stan. 💜

---

🧚 SEE ALSO 🧚

• HTTP::Proxy
• HTTP::Proxy::BodyFilter

---

👑 COPYRIGHT 👑

Copyright 2003-2015, Philippe Bruhat.

---

⭐ LICENSE ⭐

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

---

perl v5.36.0 · 2022-12-04 · HTTP::...rFilter(3pm) — that's a wrap bestie, go build some filters, you're gonna eat 💅✨🦋