CGI::A...Stream(3pm)

💖 CGI::Application::Plugin::Stream 💖

okay so bestie, you know CGI::Application::Plugin::Stream? that's the manual page we're doing — the Perl plugin that streams files. it lives in the User Contributed Perl Documentation, and it is genuinely so useful. let's get into it 🫶

---

✨ NAME ✨

CGI::Application::Plugin::Stream — a CGI::Application plugin for streaming files. that's the whole vibe. streaming. files. slay. 💅

---

🦋 SYNOPSIS 🦋

use CGI::Application::Plugin::Stream (qw/stream_file/);

sub runmode {
  # ...

  # Set up any headers you want to set explicitly
  # using header_props() or header_add() as usual

  #...

  if ( $self->stream_file( $file ) ) {
    return;
  } else {
    return $self->error_mode();
  }
}

like, that's it. you pull in stream_file, you call it in your runmode, and if it works you return and if it doesn't you go to error_mode(). iconic behaviour tbh.

---

🌸 DESCRIPTION 🌸

so this plugin gives you a way to stream a file back to the user. that's the whole point.

it's giving very useful when you're creating a PDF or a Spreadsheet document dynamically to hand over to the user. no cap.

here's the cute part: the file gets read and printed in small chunks so your memory consumption stays low. we're not loading the whole thing at once, we're not doing that to you. 🧚

now listen, this plugin is a consumer. meaning? your runmode should not try to do any output or anything afterwards. it messes with the HTTP response headers, so anything you try to do after it will probably just not work. if you pass along a filehandle, we'll make sure to close it for you, don't worry about it. 🫶

💡 it's recommended that you increment $| (or just set it to 1), which will autoflush the buffer as your application is streaming out the file. do it. trust.

---

👑 METHODS 👑

💜 stream_file()

$self->stream_file($fh);
$self->stream_file( '/path/to/file',2048);

okay so this method can take two parameters:

1. the first one is either the path to the file or a filehandle
2. the second one (optional, bestie) is the number of bytes that determines the chunk size of the stream

it defaults to 1024, btw. iykyk.

it will either stream a file to the user, or return false if it fails — maybe because it couldn't find the file you referenced. rude of the file, honestly.

⚠️ we highly recommend you provide a file name if you're passing along a filehandle, because we won't be able to deduce the file name and we'll just use 'FILE' by default. not the moment. example:

$self->header_add( -attachment => 'my_file.txt' );

with both a file handle or file name, we'll try to determine the correct content type by using File::MMagic. and if File::MMagic can't figure it out, the default 'application/octet-stream' gets used instead. no stress. ✨

the size will be calculated and added to the headers as well. we're thorough like that.

again, you can set these explicitly if you want as well:

$self->header_add(
     -type                     =>      'text/plain',
     -Content_Length   =>      42, # bytes
);

look at that. gorgeous. 💅

---

🎀 AUTHOR 🎀

Jason Purdy, <Jason@Purdy.INFO>, with inspiration from Tobias Henoeckl and tremendous support from the cgiapp mailing list.

Mark Stosberg also contributed to this module. shoutout. 🫶

---

🌈 SEE ALSO 🌈

• CGI::Application
• <http://www.cgi-app.org>
• "CREATING A STANDARD HTTP HEADER" in CGI.pm
• <http://www.mail-archive.com/cgiapp@lists.erlbaum.net/msg02660.html>
• File::Basename
• "$|" in perlvar

---

🍓 LICENSE 🍓

Copyright (C) 2004-2005 Jason Purdy, <Jason@Purdy.INFO>

this library is free software. you can modify and or distribute it under the same terms as Perl itself. periodt. 💖

---

and that's the whole page, bestie!! it was perl v5.34.0, dated 2022-06-09, and this little doc lives at CGI::A...Stream(3pm). mwah. 💋✨