An introduction to the Web::Simple Perl module, a minimalist web framework

Perl module Web::Simple is easy to learn and packs a big enough punch for a variety of one-offs and smaller services.
384 readers like this.
Image of spider web

You as a Machine. Modified by Rikki Endsley. CC BY-SA 2.0.

One of the more-prominent members of the Perl community is Matt Trout, technical director at Shadowcat Systems. He's been building core tools for Perl applications for years, including being a co-maintaner of the Catalyst MVC (Model, View, Controller) web framework, creator of the DBIx::Class object-management system, and much more. In person, he's energetic, interesting, brilliant, and sometimes hard to keep up with. When Matt writes code…well, think of a runaway chainsaw, with the trigger taped down and the safety features disabled. He's off and running, and you never quite know what will come out. Two things are almost certain: the module will precisely fit the purpose Matt has in mind, and it will show up on CPAN for others to use.

One of Matt's special-purpose modules is Web::Simple. Touted as "a quick and easy way to build simple web applications," it is a stripped-down, minimalist web framework, with an easy to learn interface. Web::Simple is not at all designed for a large-scale application; however, it may be ideal for a small tool that does one or two things in a lower-traffic environment. I can also envision it being used for rapid prototyping if you wanted to create quick wireframes of a new application for demonstrations.

Installation, and a quick "Howdy!"

You can install the module using cpan or cpanm. Once you've got it installed, you're ready to write simple web apps without having to hassle with managing the connections or any of that—just your functionality. Here's a quick example:

package HelloReader;
use Web::Simple;

sub dispatch_request {
  GET => sub {
    [ 200, [ 'Content-type', 'text/plain' ], [ 'Howdy, reader!' ] ]
  '' => sub {
    [ 405, [ 'Content-type', 'text/plain' ], [ 'You cannot do that, friend. Sorry.' ] ]


There are a couple of things to notice right off. For one, I didn't use strict and use warnings like I usually would. Web::Simple imports those for you, so you don't have to. It also imports Moo, a minimalist OO framework, so if you know Moo and want to use it here, you can! The heart of the system lies in the dispatch_request method, which you must define in your application. Each entry in the method is a match string, followed by a subroutine to respond if that string matches. The subroutine must return an array reference containing status, headers, and content of the reply to the request.


The matching system in Web::Simple is powerful, allowing for complicated matches, passing parameters in a URL, query parameters, and extension matches, in pretty much any combination you want. As you can see in the example above, starting with a capital letter will match on the request method, and you can combine that with a path match easily:

'GET + /person/*' => sub {
  my ($self, $person) = @_;
  # write some code to retrieve and display a person
'POST + /person/* + %*' => sub {
  my ($self, $person, $params) = @_;
  # write some code to modify a person, perhaps

In the latter case, the third part of the match indicates that we should pick up all the POST parameters and put them in a hashref called $params for use by the subroutine. Using ? instead of % in that part of the match would pick up query parameters, as normally used in a GET request. There's also a useful exported subroutine called redispatch_to. This tool lets you redirect, without using a 3xx redirect; it's handled internally, invisible to the user. So:

'GET + /some/url' => sub {
  redispatch_to '/some/other/url';

A GET request to /some/url would get handled as if it was sent to /some/other/url, without a redirect, and the user won't see a redirect in their browser.

I've just scratched the surface with this module. If you're looking for something production-ready for larger projects, you'll be better off with Dancer or Catalyst. But with its light weight and built-in Moo integration, Web::Simple packs a big enough punch for a variety of one-offs and smaller services.

User profile image.
Ruth Holloway has been a system administrator and software developer for a long, long time, getting her professional start on a VAX 11/780, way back when. She spent a lot of her career (so far) serving the technology needs of libraries, and has been a contributor since 2008 to the Koha open source library automation suite. Ruth is currently a Perl developer and project lead at Clearbuilt.


This is great for a beginner. Thanks a lot!

You're welcome! Look for more stuff like this in coming articles; I've got other great Perl-beginner articles and Perl module articles lined up!

In reply to by Chrissy McLennon

In some of the code examples there's a typo, it should be "=> sub {", not "= sub {"

Pretty nifty. Thanks!

You're welcome! Watch for other neat and useful modules in coming months!

In reply to by Robert X (not verified)

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.