Web::M...Manual(3pm)

💖 NAME 💖

Web::Machine::Manual — bestie, this is literally the "how do I even use this thing" guide for Web::Machine. ✨

---

🌸 VERSION 🌸

This is version 0.17 🎀

---

🦋 Web::Machine IN A NUTSHELL 🦋

okay so the entire vibe of Web::Machine is this: handling a web request is implemented as a state machine. If you're sitting there like "bestie what is a state machine 😭" — think of a flowchart. We look at the request and the resource we provide, and we 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. And since this is all built on top of Plack and PSGI <http://plackperl.org/>, that response is a status code, some headers, and an optional body. periodt. 💅

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>. Every single diamond in that diagram corresponds to a method that your Web::Machine::Resource subclass can implement. The return value from your method decides what method gets called next. it's giving choose-your-own-adventure fr fr 🧚

But here's the tea ☕ — unlike on that diagram, we often support return values beyond simple true/false values for methods. The Web::Machine::Resource documentation describes exactly what each method can return. go read it, i'm not joking 🙈

---

👑 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. iconic behavior honestly 🌈

✨ 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. Like, 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. slay, no cap 💅

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. lowkey you're just nerfing yourself 💀

🍓 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. do not skip this step bestie, i am begging 😭

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. 🚨 like it's on you, ok?? 🚨

---

💀 SUPPORT 💀

bugs may be submitted through <https://github.com/houseabsolute/webmachine-perl/issues>. go off, tell them everything 👑🐛

---

🌟 AUTHORS 🌟

• Stevan Little <stevan@cpan.org>
• Dave Rolsky <autarch@urth.org>

the literal main characters of this whole situation 🫶✨

---

💜 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. so like, free free. go wild responsibly 🌸

---

and that's the whole thing bestie!! 💖 this page was served to you by perl v5.34.0 on 2022-07-03 — mwah, ily, go build something cute ✨🎀🦋