Hello all,
This is my first post of this kind. I apologize if my question or myself is
stupid, unclear, the pod below too long etc.
I'd very appreciate any comments, suggestions, criticism etc. concerning the
module described in the pod below. My native language is not english.
I also have some specific questions, if the pod is worth to be discussed.
- Could it be useful for other people than me?
- Did I miss a module with similar (small) functionality?
- Is it enough generic? (dbh, DBD::mysql per default...)
- Is anything missing that should not?
- Do you see obvious problems I don't see?
- Could the api be improved?
The module names are _just_temporarily_. The pod misses some clarity.
There is also a helper Module which provides predefined callbacks
and a make_callback() method which can take a regex (string, qr//,
Regexp::Common), or a set of values, or a dbh and fieldname to search for a
value in a database.
Thanks a lot for any help, comments...
===
POD (hopefully the formatting is not lost)
===
NAME
Apache::Request::Restricted - Subclass of Apache::Request adding input
validation restrictions and optional persistency
DESCRIPTION
Request values are only accessible if a parameter specification has been
defined, and if the values pass the validation callback tests.
Parameters may be marked as persistent, so they are acessible through
the param() method in further requests. They are automatically updated
with actual request data.
The module provides means to centralize input validation and keeping
session data. No need to care about theses things anymore when request
parameters are accessed and used.
MODIFIED METHODS
new(-pconfig=>$param_configuration
[, -dbh=>$dbh [, -sid_name=>$sid_name]
[, -no_create=>$bool] ])
Create a new object.
All acessible request parameters must have a definition in
$param_configuration, consisting of a hashref with parameter names
or regexes as keys, and an arrayref of callbacks as values. See
PARAMETER CONFIGURATION below.
If session management is wanted, -dbh must be provided, and
optionally
- -sid_name: The name of the session id in the request
(defaults to '_session_id')
- -no_create=>1 (default 0) if no new session should be
created if the request contains a session id without
data in the session. Otherwise, a new session with a
new session id is created, as if no session id had
been provided by the request.
An existent session is opened if a session id is specified in the
actual request, and data exists for it.
A session is created if either a session id the actual request is
only defined but not set, or - in case -no_create is true - if a
session id is provided but no session data present for it.
To switch to session management, include a '$sid_name=' into the
request.
[Of course this is only applied if -dbh is provided and there are
persistent request parameters]
Returns undef on errors.
instance([EMAIL PROTECTED])
Analogous to the method in Apache::Request: The same arguments as
for new() can be provided; they are ignored from the second call on.
The object is a singleton on a per request level.
param()
Returns all defined request parameter names (same as the base
class).
param($name)
Returns the value(s) that passed the validation checks. Data may
come from the request or the session.
param($name, @values)
Set the values of a request parameter (and eventually of the
session). Note the CGI-Syntax (The base class uses [EMAIL PROTECTED]).
ADDITIONAL METHODS
add_config($pconfig)
Additionaly to the -pconfig new parameter, parameter specifications
can be added later on. If the key is a string, an existent old spec
is overwritten. If the key is a regex, it is appended to the
existing regexes.
As soon as a request parameter ist specified as persistent, a
session is created at the next param() call.
sid()
Returns the actual session id or undef if session management is not
wanted or deactivated because there are no persistent request
parameters defined.
NOTE (TODO): A sid is not available before the first call of param()
with argument(s).
register_callback ($name, $cb)
Class method to register callbacks under names, for later retrieval
with callcack(). Returns false if the name already exists, else
true.
callback([$name])
Class method. With $name provided, get the callback registered with
register_callback() by its name. Returns undef if the name does not
exists.
Without arguments, returns a list of all names of registered
callbacks.
Normally this method is not used directly (it is called from new()
and add_pconfig() when specifying a callback name instead of a
callback).
errors()
Returns the callback validation failures since object creation
(including ignoring values because no callbacks is available).
TODO: errors related to the last relevant action only.
clear_errors()
Deletes all accumulated errors.
TODO: Gets obsolete after TODO of errors().
PARAMETER CONFIGURATION
The -pconfig option of new() and instance(), as well as the argument
to add_pconfig, is a hashref like follows:
my @callbacks1=[
sub {...},
$registered_callback_name1,
$callback_obj,
...
];
...
my $defs={
_session_id=>{
-callbacks=>[EMAIL PROTECTED],
-persistent=>1, # default false
-ignore_false=>1, # default false
},
name1=>{
-callbacks=>[EMAIL PROTECTED],
},
qr/a regex/=>{
-callbacks=>[EMAIL PROTECTED],
},
...
};
Keys of the hashref are names or qr//-precompiled regexes, the
latter being a "collective key" to all names matchable with the
regex. If -sid_name is provided to new() or instance(), the hashref
must contain the definition of the session id parameter.
@callbacksN above can contain subrefs or names of callbacks
registered with register_callback().
The callbacks are executed in the order they are specified. If
-persistent and -ignore_false are both true, then a false value does
not update the corresponding session data.
If no entry has a true -persistent option, session management is
deactivated, even if a -dbh was provided to new() or instance().
The callbacks get a reference to a scalar as argument, and should
return undef if the argument is undef, otherwise the result of the
callback (boolean). The callback may change the (live) value. For
details see Apache::Request::Restricted::Callbacks.
The callback may also return undef if the next callback in the chain
should be tried (kind of DECLINED in ApacheHandlers).
IMPLEMENTATION NOTES
There is some caching active:
Callbacks found via a regex key for a certain request parameter names
are cached (the param name with it's callback are cached).
Values once accessed (be it read or write, with or without session
management) are cached in the object. If session management is on, the
database is physically updated when the object is destroyed.
SEE ALSO
Apache::Request(3), Apache::Session(3)
and
Apache::Request::Restricted::Callbacks(3) (helper module)
Apache::Request::Restricted::Session(3) (internal)
Apache::Request::Restricted::Dispatcher(3) (internal)
