[Catalyst-commits] r8005 - in Catalyst-Plugin-DebugCookie/1.000/trunk/lib/Catalyst/Plugin: . DebugCookie

Wed Jun 25 23:12:02 BST 2008

Author: jgoulah
Date: 2008-06-25 23:12:02 +0100 (Wed, 25 Jun 2008)
New Revision: 8005

Modified:
   Catalyst-Plugin-DebugCookie/1.000/trunk/lib/Catalyst/Plugin/DebugCookie.pm
   Catalyst-Plugin-DebugCookie/1.000/trunk/lib/Catalyst/Plugin/DebugCookie/Util.pm
Log:
some pod for the plugin

Modified: Catalyst-Plugin-DebugCookie/1.000/trunk/lib/Catalyst/Plugin/DebugCookie/Util.pm
===================================================================

--- Catalyst-Plugin-DebugCookie/1.000/trunk/lib/Catalyst/Plugin/DebugCookie/Util.pm	2008-06-25 20:52:44 UTC (rev 8004)
+++ Catalyst-Plugin-DebugCookie/1.000/trunk/lib/Catalyst/Plugin/DebugCookie/Util.pm	2008-06-25 22:12:02 UTC (rev 8005)
@@ -7,6 +7,22 @@
 use Sub::Exporter
     -setup => { exports => [ qw(make_debug_cookie check_debug_cookie_value) ] };
 
+=head1 NAME
+
+Catalyst::Plugin::DebugCookie::Util - Utility class to handle abstracting the cookie get/set 
+
+=head1 DESCRIPTION
+
+These methods provide an interface for creating the debug cookie, and also checking it later
+for when a page is hit with the 'is_debug' query parameter
+
+=cut
+
+=head2 make_debug_cookie($c, $username) 
+
+Creates a debug cookie with a hash of your secret key and username 
+
+=cut
 sub make_debug_cookie {
 	my ($c, $username) = @_;
 
@@ -23,6 +39,12 @@
 }
 
 
+=head2 check_debug_cookie_value($c, $username) 
+
+Checks the debug cookie and verifies the value matches
+the hash of your secret key and username 
+
+=cut
 sub check_debug_cookie_value {
 	my ($c, $username) = @_;
 
@@ -40,4 +62,15 @@
 	return 0;
 }
 
+=head1 AUTHOR
+
+ John Goulah       <jgoulah at cpan.org>
+
+=head1 COPYRIGHT
+
+This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+
+=cut
+
 1;

Modified: Catalyst-Plugin-DebugCookie/1.000/trunk/lib/Catalyst/Plugin/DebugCookie.pm
===================================================================
--- Catalyst-Plugin-DebugCookie/1.000/trunk/lib/Catalyst/Plugin/DebugCookie.pm	2008-06-25 20:52:44 UTC (rev 8004)
+++ Catalyst-Plugin-DebugCookie/1.000/trunk/lib/Catalyst/Plugin/DebugCookie.pm	2008-06-25 22:12:02 UTC (rev 8005)
@@ -5,14 +5,75 @@
 use Class::C3;
 use Catalyst::Plugin::DebugCookie::Util qw/check_debug_cookie_value/;
 
-=head
-debug will only get hit when catalyst debug is off
-b/c CATALYST_DEBUG=1 injects a 'sub debug { 1 }' into MyApp::
+our $VERSION = '0.999001';
 
-=cut
+=head1 NAME
 
-our $VERSION = '0.999001';
+Catalyst::Plugin::DebugCookie - Catalyst plugin to turn on 
+debug when a secure cookie and a query param are set  
 
+=head1 SYNOPSIS
+
+ # In your application class 
+ use Catalyst qw/DebugCookie/;
+
+ # In your controller, a method to set the cookie
+ use Catalyst::Plugin::DebugCookie::Util qw/make_debug_cookie/;
+ sub secure_debug_cookie :Path(/this/is/not/public) { 
+	my ($self, $c, $username) = @_; 
+
+	make_debug_cookie($c, $username);
+	$c->res->body("Cookie set"); 
+ }
+
+ # Your config in perl  
+ __PACKAGE__->config->{Plugin::DebugCookie} = {
+	secret_key  => '001A4B28EE3936',
+	cookie_name => 'mycookie',
+ }
+
+ # Your config in Config::General format 
+ <Plugin::DebugCookie>
+    secret_key 001A4B28EE3936
+    cookie_name my_secure_debug_cookie 
+ </Plugin::DebugCookie>
+
+ # In your browser set the cookie
+ http:///this/is/not/public/username
+ # In your browser view a page with debug 
+ http://yourserver?is_debug=username
+
+=head1 DESCRIPTION
+
+Catalyst plugin to turn debug on, typically used in a production
+environment where debug is off.  Two things must happen to enable debug.
+First, you have to go to a secure (ideally password protected) URL to 
+set the cookie, which is a hash of your secret key and username.  Secondly,
+you have to hit the page with the ?is_debug=<username> query parameter.
+
+Note that this plugin will only work when catalyst debug is off since 
+CATALYST_DEBUG=1 injects a 'sub debug { 1 }' into MyApp::, therefore
+the overloaded debug in this plugin would not be executed.
+
+=head1 CONFIGURATION
+
+=head2 secret_key 
+
+This is a key hashed with a username to provide cookie security 
+
+=head2 cookie_name 
+
+Sets the name of the cookie (optional). Defaults to 'debug_cookie'  
+
+=head1 EXTENDED METHODS
+
+The following methods are extended from the main Catalyst application class.
+
+=head2 prepare 
+
+Sets 'X-Catalyst-Debug' and enables stats when debug is on
+
+=cut
 sub prepare { 
 	my $class = shift; 
 	my $self = $class->next::method(@_); 
@@ -23,17 +84,12 @@
 	$self; 
 }
 
-sub valid_debug_mode {
-	my $self = shift;
+=head2 debug 
 
-	if(my $is_debug = $self->req->query_params->{is_debug}) {
-		return check_debug_cookie_value($self, $is_debug); 
-	}
+Determines whether debug should be 
+set based on cookie and query param
 
-	return 0;
-}
-
-
+=cut
 sub debug { 
 	my $self = shift;
 	if (ref $self) { 
@@ -43,6 +99,12 @@
 	}
 }
 
+=head2 use_stats 
+
+Determines whether use_stats should be 
+set based on cookie and query param
+
+=cut
 sub use_stats { 
 	my $self = shift;
 	if (ref $self) { 
@@ -52,4 +114,33 @@
 	}
 }
 
+=head1 METHODS
+
+=head2 valid_debug_mode 
+
+Checks for is_debug query param and checks for a valid cookie
+and returns true if both are validated
+
+=cut
+sub valid_debug_mode {
+	my $self = shift;
+
+	if(my $is_debug = $self->req->query_params->{is_debug}) {
+		return check_debug_cookie_value($self, $is_debug); 
+	}
+
+	return 0;
+}
+
+=head1 AUTHOR
+
+ John Goulah       <jgoulah at cpan.org>
+
+=head1 COPYRIGHT
+
+This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+
+=cut
+
 1;


