view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/Authorization/Driver.pm  view on Meta::CPAN

package CGI::Application::Plugin::Authorization::Driver;

use strict;
use warnings;

use UNIVERSAL::require;

=head1 NAME

CGI::Application::Plugin::Authorization::Driver - Base module for building driver classes
for CGI::Application::Plugin::Authorization


=head1 SYNOPSIS

 package CGI::Application::Plugin::Authorization::Driver::MyDriver;
 use base qw(CGI::Application::Plugin::Authorization::Driver);

  sub authorize_user {
      my $self = shift;
      my @params = @_;

      if ( >>> Valid Access Permissions <<< ) {
          return 1;
      }
      return;
  }


=head1 DESCRIPTION

This module is a base class for all driver classes for the L<CGI::Application::Plugin::Authorization>
plugin.  Each driver class is required to provide only one method to authorize the given parameters.
Often this will be a list of groups that the user needs to be a part of, although it could be anything.


=head1 METHODS

=head2 new

This is a constructor that can create a new Driver object.  It requires an Authorization object as its
first parameter, and any number of other parameters that will be used as options depending on which
Driver object is being created.  You shouldn't need to call this as the Authorization plugin takes care
of creating Driver objects.

=cut

sub new {
    my $class = shift;
    my $self = {};
    my $authz = shift;
    my @options = @_;

    bless $self, $class;
    $self->{authz} = $authz;
    Scalar::Util::weaken($self->{authz}); # weaken circular reference
    $self->{options} = \@options;
    $self->initialize;
    return $self;
}

=head2 initialize

This method will be called right after a new Driver object is created.  So any startup customizations
can be dealt with here.

=cut

sub initialize {
    my $self = shift;
    # override this in the subclass if you need it
    return;
}

=head2 options

This will return a list of options that were provided when this driver was configured by the user.

=cut

sub options { return (@{$_[0]->{options}}) }

=head2 find_option

This method will search the Driver options for a specific key and return
the value it finds.  This method assumes that the Driver configuration contains
a hash of information.  If it does not, then you will have to parse the option
manually in the subclass.

=cut

sub find_option {
    my $self = shift;
    my $key = shift;
    my @options = $self->options;
    my $marker = 0;
    foreach my $option (@options) {
        if ($marker) {
            return $option;
        } elsif ($option eq $key) {
            # We need the next element
            $marker = 1;
        }
    }
    return;
}

=head2 authz

This will return the underlying L<CGI::Application::Plugin::Authorization> object.  In most cases it will
not be necesary to access this.

=cut

sub authz { return $_[0]->{authz} }