1NAME
2 Class::DBI::FromCGI - Update Class::DBI data using CGI::Untaint
3
4SYNOPSIS
5 package Film;
6 use Class::DBI::FromCGI;
7 use base 'Class::DBI';
8 # set up as any other Class::DBI class.
9
10 __PACKAGE__->untaint_columns(
11 printable => [qw/Title Director/],
12 integer => [qw/DomesticGross NumExplodingSheep/],
13 date => [qw/OpeningDate/],
14 );
15
16 # Later on, over in another package ...
17
18 my $h = CGI::Untaint->new( ... );
19 my $film = Film->retrieve('Godfather II');
20 $film->update_from_cgi($h);
21
22 my $new_film = Film->create_from_cgi($h);
23
24 if (my %errors = $film->cgi_update_errors) {
25 while (my ($field, $problem) = each %errors) {
26 warn "Problem with $field: $problem\n";
27 }
28 }
29
30 # or
31 $film->update_from_cgi($h => @columns_to_update);
32
33 # or
34 $film->update_from_cgi($h => { ignore => \@cols_to_ignore,
35 required => \@cols_needed,
36 all => \@columns_which_may_be_empty });
37
38 my $how = $film->untaint_type('Title'); # printable
39
40DESCRIPTION
41 Lots of times, Class::DBI is used in web-based applications. (In fact,
42 coupled with a templating system that allows you to pass objects, such
43 as Template::Toolkit, Class::DBI is very much your friend for these.)
44
45 And, as we all know, one of the most irritating things about writing
46 web-based applications is the monotony of writing much of the same stuff
47 over and over again. And, where there's monotony there's a tendency to
48 skip over stuff that we all know is really important, but is a pain to
49 write - like Taint Checking and sensible input validation. (Especially
50 as we can still show a 'working' application without it!). So, we now
51 have CGI::Untaint to take care of a lot of that for us.
52
53 It so happens that CGI::Untaint also plays well with Class::DBI.
54 Class::DBI::FromCGI is a little wrapper that ties these two together.
55
56METHODS
57 untaint_columns
58 All you need to do is to 'use Class::DBI::FromCGI' in your class (or in
59 your local Class::DBI subclass that all your other classes inherit from.
60 You do do that, don't you?).
61
62 Then, in each class in which you want to use this, you declare how you
63 want to untaint each column:
64
65 __PACKAGE__->untaint_columns(
66 printable => [qw/Title Director/],
67 integer => [qw/DomesticGross NumExplodingSheep/],
68 date => [qw/OpeningDate/],
69 );
70
71 (where the keys are the CGI::Untaint package to be used, and the values
72 a listref of the relevant columns).
73
74 update_from_cgi
75 When you want to update based on the values coming in from a web-based
76 form, you just call:
77
78 $obj->update_from_cgi($h => @columns_to_update);
79
80 If every value passed in gets through the CGI::Untaint process, the
81 object will be updated (but not committed, in case you want to do
82 anything else with it). Otherwise the update will fail (there are no
83 partial updates), and $obj->cgi_update_errors will tell you what went
84 wrong (as a hash of problem field => error from CGI::Untaint).
85
86 create_from_cgi
87 Similarly, if you wish to create a new object, then you can call:
88
89 my $obj = Class->create_from_cgi($h => @columns_to_update);
90
91 If this fails, $obj will be a defined object, containing the errors, as
92 with an update, but will not contain the values submitted, nor have been
93 written to the database.
94
95 untaint_type
96 my $how = $film->untaint_type('Title'); # printable
97
98 This tells you how we're going to untaint a given column.
99
100 cgi_update_errors
101 if (my %errors = $film->cgi_update_errors) {
102 while (my ($field, $problem) = each %errors) {
103 warn "Problem with $field: $problem\n";
104 }
105 }
106
107 This returns a hash of any errors when updating. Despite its name it
108 also applies when inserting.
109
110Column Auto-Detection
111 As Class::DBI knows all its columns, you don't even have to say what
112 columns you're interested in, unless it's a subset, as we can auto-fill
113 these:
114
115 $obj->update_from_cgi($h);
116
117 You can also specify columns which must be present, or columns to be
118 ignored even if they are present:
119
120 $film->update_from_cgi($h => {
121 all => \@all_columns, # auto-filled if left blank
122 ignore => \@cols_to_ignore,
123 required => \@cols_needed,
124 });
125
126 Doesn't this all make your life so much easier?
127
128NOTE
129 Don't try to update the value of your primary key. Class::DBI doesn't
130 like that. If you try to do this it will be silently skipped.
131
132ANOTHER NOTE
133 If you haven't set up any 'untaint_column' information for a column
134 which you later attempt to untaint, then we try to call
135 $self->column_type to ascertain the default handler to use. Currently
136 this will only use if you're using Class::DBI::mysql, and only for
137 certain column types.
138
139SEE ALSO
140 Class::DBI. CGI::Untaint. Template.
141
142AUTHOR
143 Tony Bowden
144
145BUGS and QUERIES
146 Please direct all correspondence regarding this module to:
147 bug-Class-DBI-FromCGI@rt.cpan.org
148
149COPYRIGHT
150 Copyright (C) 2001-2005 Kasei. All rights reserved.
151
152 This module is free software; you can redistribute it and/or modify it
153 under the same terms as Perl itself.
154
155