CGI-Capture

 view release on metacpan or  search on metacpan

lib/CGI/Capture.pm  view on Meta::CPAN

package CGI::Capture; # git description: cc2391e
# ABSTRACT: Meticulously thorough capture and replaying of CGI calls

#pod =pod
#pod
#pod =head1 SYNOPSIS
#pod
#pod   # Capture the current CGI to a file, and replay it once created
#pod   use CGI::Capture 'fileupload.dat';
#pod   
#pod   # Create an object and capture the state
#pod   my $Capture = CGI::Capture->new->capture;
#pod   
#pod   # Store it in a file and load it back in
#pod   $Capture->store('somefile.dat');
#pod   my $second = CGI::Capture->apply('somefile.dat');
#pod   
#pod   # Apply the CGI call to the current environment
#pod   $second->apply;
#pod
#pod =head1 DESCRIPTION
#pod
#pod L<CGI> does a terribly bad job of saving CGI calls. C<CGI::Capture> tries
#pod to resolve this and save a CGI call in as much painstaking detail as it
#pod possibly can.
#pod
#pod Because of this, C<CGI::Capture> should work with server logins, cookies,
#pod file uploads, strange execution environments, special environment
#pod variables, the works.
#pod
#pod It does this by capturing a large amount of the perl environment
#pod BEFORE F<CGI.pm> itself gets a chance to look at it, and then restores
#pod it in the same way.
#pod
#pod So in essence, it grabs all of C<STDIN>, C<%ENV>, C<@INC>, and anything
#pod else it can think of. The things it can't replicate, it records anyway
#pod so that later in the debugger it can ensure that the execution
#pod environment is as close as possible to what it captured (and bitch at

lib/CGI/Capture.pm  view on Meta::CPAN

#pod Sometimes you want to be a little more targeted, and for these situations
#pod an alternative methodology is provided.
#pod
#pod The C<as_yaml> and C<from_yaml> methods allow you to store and retrieve a
#pod CGI capture using L<YAML::Tiny> instead of L<Storable>.
#pod
#pod Once you have stored the CGI capture as a YAML file, you can hand-edit the
#pod capture file, removing any keys you will not want to be restored, keeping
#pod only the useful parts.
#pod
#pod For example, to create a test file upload or CGI request involving
#pod cookies, you could discard everything except for the STDIN section of
#pod the capture file, which will then allow you to reuse the capture on
#pod other hosts, operating systems, and so on.
#pod
#pod =head1 METHODS
#pod
#pod In most cases, the above is all you probably need. However, if you want to
#pod get more fine-grained control, you can create and manipulate CGI::Capture
#pod object directly.
#pod

lib/CGI/Capture.pm  view on Meta::CPAN

CGI::Capture - Meticulously thorough capture and replaying of CGI calls

=head1 VERSION

version 1.15

=head1 SYNOPSIS

  # Capture the current CGI to a file, and replay it once created
  use CGI::Capture 'fileupload.dat';
  
  # Create an object and capture the state
  my $Capture = CGI::Capture->new->capture;
  
  # Store it in a file and load it back in
  $Capture->store('somefile.dat');
  my $second = CGI::Capture->apply('somefile.dat');
  
  # Apply the CGI call to the current environment
  $second->apply;

=head1 DESCRIPTION

L<CGI> does a terribly bad job of saving CGI calls. C<CGI::Capture> tries
to resolve this and save a CGI call in as much painstaking detail as it
possibly can.

Because of this, C<CGI::Capture> should work with server logins, cookies,
file uploads, strange execution environments, special environment
variables, the works.

It does this by capturing a large amount of the perl environment
BEFORE F<CGI.pm> itself gets a chance to look at it, and then restores
it in the same way.

So in essence, it grabs all of C<STDIN>, C<%ENV>, C<@INC>, and anything
else it can think of. The things it can't replicate, it records anyway
so that later in the debugger it can ensure that the execution
environment is as close as possible to what it captured (and bitch at

lib/CGI/Capture.pm  view on Meta::CPAN

Sometimes you want to be a little more targeted, and for these situations
an alternative methodology is provided.

The C<as_yaml> and C<from_yaml> methods allow you to store and retrieve a
CGI capture using L<YAML::Tiny> instead of L<Storable>.

Once you have stored the CGI capture as a YAML file, you can hand-edit the
capture file, removing any keys you will not want to be restored, keeping
only the useful parts.

For example, to create a test file upload or CGI request involving
cookies, you could discard everything except for the STDIN section of
the capture file, which will then allow you to reuse the capture on
other hosts, operating systems, and so on.

=head1 METHODS

In most cases, the above is all you probably need. However, if you want to
get more fine-grained control, you can create and manipulate CGI::Capture
object directly.