---
name: "Web::Machine::Manual"
section: "3pm"
platform: "linux"
package: "libweb-machine-perl"
version: "0.17-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Web::Machine::Manual"
---

# Web::Machine::Manual(3pm)

Learn how to use Web::Machine

## NAME

Web::Machine::Manual - Learn how to use Web::Machine

## VERSION

version 0.17

## Web::Machine IN A NUTSHELL

The basic idea behind `"Web::Machine"` is that the handling of a web request is implemented as a state machine. If you're not familiar with state machines, think of a flowchart. We look at the request and the resource we provide and ask questions about them. Is our service available? Is this a GET, POST, PUT, etc.? Does the request ask for a content type our resource provides?

The result of each question leads us to the next state (or flowchart box). Eventually we reach a point where we have a response for the client. Since this is all built on top of Plack and PSGI \<http://plackperl.org/\>, the response consists of a status code, some headers, and an optional body.

The best way to understand the full request/response cycle is to look at the original Erlang webmachine state diagram \<https://github.com/basho/webmachine/wiki/Diagram\>. Each diamond in that diagram corresponds to a method that your Web::Machine::Resource subclass can implement. The return value from your method determines what method to call next.

However, unlike on that diagram, we often support return values beyond simple true/false values for methods. The Web::Machine::Resource documentation describes what each method can return.

## Web::Machine and Plack

`"Web::Machine"` is built on top of Plack and follows the PSGI \<http://plackperl.org/\> spec. You can mix `"Web::Machine"` applications with other Plack applications using standard Plack tools like Plack::Builder.

### Web::Machine and Plack Middleware

Since `"Web::Machine"` implements the complete request and response cycle, some Plack middleware is not really needed with `"Web::Machine"`. For example, it wouldn't make sense to use something like `"Plack::Middleware::XSLT"` with `"Web::Machine"`. `"Web::Machine"` implements the full content negotiation process, so if you want to handle requests for `"text/html"` it probably makes more sense to do this in your resources. The benefit of doing so is that with `"Web::Machine"` you can easily ensure that you return a proper `"406 Not Acceptable"` status for content types you *can't* handle.

There are still many pieces of Plack middleware that are useful with `"Web::Machine"`, such as logging middleware, debugging/linting middleware, etc.

That all said, `"Web::Machine"` won't break if you use an inappropriate middleware; you'll just lose some of the benefits you get from implementing things the `"Web::Machine"` way.

### Bodies Must be Bytes

The PSGI spec requires that the body you return contain bytes, not Perl characters. In other words, strings you return must be passed through `"Encode::encode"` so that Perl interprets their contents as bytes.

If your data is not binary or ASCII, your resource should make sure to provide `charset_provided()` and `default_charset()` methods. This will make sure that `"Web::Machine"` knows how to turn your response bodies into bytes.

**CAVEAT:** Note that currently `"Web::Machine"` does not provide full charset or encoding support when the body is returned as a CODE ref. This is a bug to be remedied in the future, but currently you are responsible for making sure this code ref returns bytes.

## SUPPORT

bugs may be submitted through \<https://github.com/houseabsolute/webmachine-perl/issues\>.

## AUTHORS

- •

  Stevan Little \<stevan@cpan.org\>

- •

  Dave Rolsky \<autarch@urth.org\>

## COPYRIGHT AND LICENCE

This software is copyright (c) 2016 by Infinity Interactive, Inc.

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