---
name: "Web::Machine"
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"
---

# Web::Machine(3pm)

A Perl port of Webmachine

## NAME

Web::Machine - A Perl port of Webmachine

## VERSION

version 0.17

## SYNOPSIS

```
  use strict;
  use warnings;
  use Web::Machine;
  {
      package HelloWorld::Resource;
      use strict;
      use warnings;
      use parent 'Web::Machine::Resource';
      sub content_types_provided { [{ 'text/html' => 'to_html' }] }
      sub to_html {
          q{<html>
              <head>
                  <title>Hello World Resource</title>
              </head>
              <body>
                  <h1>Hello World</h1>
              </body>
           </html>}
      }
  }
  Web::Machine->new( resource => 'HelloWorld::Resource' )->to_app;
```

## DESCRIPTION

`"Web::Machine"` provides a RESTful web framework modeled as a state machine. You define one or more resource classes. Each resource represents a single RESTful URI end point, such as a user, an email, etc. The resource class can also be the target for `"POST"` requests to create a new user, email, etc.

Each resource is a state machine, and each request for a resource is handled by running the request through that state machine.

`"Web::Machine"` is built on top of Plack, but it handles the full request and response cycle.

See Web::Machine::Manual for more details on using `"Web::Machine"` in general, and how `"Web::Machine"` and Plack interact.

This is a port of Webmachine \<https://github.com/basho/webmachine\>, actually it is much closer to the Ruby version \<https://github.com/seancribbs/webmachine-ruby\>, with a little bit of the JavaScript version \<https://github.com/tautologistics/nodemachine\> and even some of the Python version \<https://github.com/benoitc/pywebmachine\> thrown in for good measure.

You can learn a bit about Web::Machine's history from the slides for my 2012 YAPC::NA talk \<https://speakerdeck.com/stevan\_little/rest-from-the-trenches\>.

To learn more about Webmachine, take a look at the links in the SEE ALSO section.

## METHODS

NOTE: This module is a Plack::Component subclass and so follows the interface set forward by that module.

- "new( resource =\> $resource\_classname, ?resource\_args =\> $arg\_list, ?tracing =\> 1\|0, ?streaming =\> 1\|0, ?request\_class =\> $request\_class )"

  The constructor expects to get a `$resource_classname`, which it will use to load and create an instance of the resource class. If that class requires any additional arguments, they can be specified with the `"resource_args"` parameter. The contents of the `"resource_args"` parameter will be made available to the `init()` method of `"Web::Machine::Resource"`.

  The `"new"` method can also take an optional `"tracing"` parameter which it will pass on to Web::Machine::FSM and an optional `"streaming"` parameter, which if true will run the request in a PSGI \<http://plackperl.org/\> streaming response. This can be useful if you need to run your content generation asynchronously.

  The optional `"request_class"` parameter accepts the name of a module that will be used as the request object. The module must be a class that inherits from Plack::Request. Use this if you have a subclass of Plack::Request that you would like to use in your Web::Machine::Resource.

- inflate\_request( $env )

  This takes a raw PSGI `$env` and inflates it into a Plack::Request instance. By default this also uses HTTP::Headers::ActionPack to inflate the headers of the request to be complex objects.

- "create\_fsm"

  This will create the Web::Machine::FSM object to run. It will get passed the value of the `"tracing"` constructor parameter.

- create\_resource( $request )

  This will create the Web::Machine::Resource instance using the class specified in the `"resource"` constructor parameter. It will pass in the `$request` object and call `"new_response"` on the `$request` object to get a Plack::Response instance.

- finalize\_response( $response )

  Given a `$response` which is a Plack::Response object, this will finalize it and return a raw PSGI response.

- call( $env )

  This is the `"call"` method overridden from the Plack::Component superclass.

## DEBUGGING

If you set the `"WM_DEBUG"` environment variable to `1` we will print out information about the path taken through the state machine to STDERR.

If you set `"WM_DEBUG"` to `"diag"` then debugging information will be printed using Test::More's `diag()` sub instead.

## SEE ALSO

- The diagram - \<https://github.com/Webmachine/webmachine/wiki/Diagram\>

  - Original Erlang - \<https://github.com/basho/webmachine\>

  - Ruby port - \<https://github.com/seancribbs/webmachine-ruby\>

  - Node JS port - \<https://github.com/tautologistics/nodemachine\>

  - Python port - \<https://github.com/benoitc/pywebmachine\>

  - 2012 YAPC::NA slides - \<https://speakerdeck.com/stevan\_little/rest-from-the-trenches\>

  - an elaborate machine is indispensable: a blog post by Justin Sheehy - \<http://blog.therestfulway.com/2008/09/webmachine-is-resource-server-for-web.html\>

  - Resources, For Real This Time (with Webmachine): a video by Sean Cribbs - \<http://www.youtube.com/watch?v=odRrLK87s\_Y\>

  ## SUPPORT

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

## AUTHORS

- •

  Stevan Little \<stevan@cpan.org\>

- •

  Dave Rolsky \<autarch@urth.org\>

## CONTRIBUTORS

- •

  Andreas Marienborg \<andreas.marienborg@gmail.com\>

- •

  Andrew Nelson \<anelson@cpan.org\>

- •

  Arthur Axel 'fREW' Schmidt \<frioux@gmail.com\>

- •

  Carlos Fernando Avila Gratz \<cafe@q1software.com\>

- •

  Fayland Lam \<fayland@gmail.com\>

- •

  George Hartzell \<hartzell@alerce.com\>

- •

  Gregory Oschwald \<goschwald@maxmind.com\>

- •

  Jesse Luehrs \<doy@tozt.net\>

- •

  John SJ Anderson \<genehack@genehack.org\>

- •

  Mike Raynham \<enquiries@mikeraynham.co.uk\>

- •

  Nathan Cutler \<ncutler@suse.cz\>

- •

  Olaf Alders \<olaf@wundersolutions.com\>

- •

  Stevan Little \<stevan.little@gmail.com\>

- •

  Thomas Sibley \<tsibley@cpan.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.