NAME

    WWW::MLite - Lite Web Application Framework

VERSION

    Version 2.01

SYNOPSIS

        package MyApp;
    
        use base qw/WWW::MLite/;
    
        use HTTP::Status qw/:constants/;
        use Data::Dumper;
    
        __PACKAGE__->register_method( # GET /myapp
            name    => "getIndex",
            description => "Index page",
            method  => "GET",
            path    => "/myapp",
            deep    => 0,
            attrs   => {
                    foo         => 'blah-blah-blah',
                    bar         => 'on',
                    deserialize => 0,
                    serialize   => 1,
                },
            requires => undef,
            returns => undef,
            code    => sub {
            my $self = shift;
            my @params = @_;
    
            $self->data(Dumper({
                    params => [@params],
                    name   => $self->name,
                    description => $self->info("description"),
                    attrs  => $self->info("attrs"),
                    path   => $self->info("path"),
                    method => $self->info("method"),
                    requires => $self->info("requires"),
                    returns => $self->info("returns"),
                }));
    
            return HTTP_OK; # HTTP RC
        });
    
        1;
    
        package main;
    
        use FindBin qw/$Bin/;
        use lib "$Bin/../lib";
    
        use CGI;
        use File::Spec;
    
        my $q = new CGI;
        my $server = MyApp->new(
            project     => "MyApp",
            ident       => "myapp",
            root        => File::Spec->catdir($Bin, "conf"),
            #confopts    => {... Config::General options ...},
            configfile  => File::Spec->catfile($Bin, "conf", "myapp.conf"),
            log         => "on",
            logfd       => fileno(STDERR),
            #logfile     => '/path/to/log/file.log',
            nph         => 0, # NPH (no-parsed-header)
        );
        print $server->call($q->request_method, $q->request_uri, $q) or die($server->error);

DESCRIPTION

    Lite Web Application Framework

    This module allows you to quickly and easily write a REST servers

 new

        my $server = MyApp->new(
            project     => "MyApp",
            ident       => "myapp",
            root        => File::Spec->catdir($Bin, "conf"),
            #confopts    => {... Config::General options ...},
            configfile  => File::Spec->catfile($Bin, "conf", "myapp.conf"),
            log         => "on",
            logfd       => fileno(STDERR),
            #logfile     => '/path/to/log/file.log',
            nph         => 0, # NPH (no-parsed-header)
        );

    Returns CTK object as WWW::MLite server

    confopts

      Optional value. Config::General options

    configfile

      File of configuration

      Default: /etc/myapp/myapp.conf

    log

      General switch for logging enable/disable

      Default: off

      Also see configuration for logging manage

    logfd

      File descriptor or fileno

      Default: none (use syslog)

      See IO::Handle

    logfile

      Log file path. Not recommended!

    nph

      Enable or disable NPH mode (no-parsed-header)

      Default: 0

      See "USING-NPH-SCRIPTS" in CGI

      This option for the response subroutine only!

    root

      Root directory for project. This is NOT document root directory!

      Default: /etc/myapp

    See also CTK and CTK::App

METHODS

    List of available methods

 call

    See "call_method"

 call_method

        $server->call_method( $ENV{REQUEST_URI}, $ENV{REQUEST_METHOD}, ... );

    Runs the callback function from current method with additional
    parameters

    Note: any number of parameters can be specified, all of them will be
    receive in the callback function and in your overridden the response
    subroutine

    Returns: response content

 check_http_method

        $server->check_http_method("GET"); # returns 1
        $server->check_http_method("OPTIONS"); # returns 0

    Checks the availability of the HTTP method by its name and returns the
    status

 code

        my $code = $server->code;
        my $code = $server->code( 500 );

    Gets/Sets response HTTP code

    Default: 200 (HTTP_OK)

    See HTTP::Status

 cleanup

        $server->cleanup;

    Cleans the all working data and resets it to default values

 data

        my $data = $server->data;
        $server->data({
                param1 => "new value",
            });

    Gets/Sets working data structure or HTTP content

    Default: undef

    See HTTP::Response

 head

        my $head = $server->head;
        $server->head({
                "Content-Type" => "text/plain",
            });

    Gets/Sets HTTP headers

    Default: "text/plain"

    See HTTP::Headers

 info

        my $info = $server->info;
        my $description => $server->info("description");
        my $attrs = $server->info("attrs");
        my $path = $server->info("path");
        my $method = $server>info("method");
        my $requires = $server->info("requires");
        my $returns = $server->info("returns");

    Returns the info structure or info-data of current method

 lookup_method

        my $method = $server->lookup_method($ENV{REQUEST_URI}, $ENV{REQUEST_METHOD});

    Returns $method structure from hash of registered methods; or undef if
    method is not registered

 message

        my $message = $server->message;
        my $message = $server->message( "Internal Server Error" );

    Gets/Sets response HTTP message

    Default: "OK"

    See HTTP::Status

 name

        my $name = $server->name;

    Returns name of current method. Default: default

 register_method

        use base qw/WWW::MLite/;
    
        use HTTP::Status qw/:constants/;
        use Data::Dumper;
    
        __PACKAGE__->register_method( # GET /myapp
            name    => "getIndex",
            description => "Index page",
            method  => "GET",
            path    => "/myapp",
            deep    => 0,
            attrs   => {
                    foo         => 'blah-blah-blah',
                    bar         => 'on',
                    deserialize => 0,
                    serialize   => 1,
                },
            requires => [
                    qw/ user1 user2 userX /
                ],
            returns => {
                    type => 'any',
                },
            code    => sub {
            my $self = shift;
            my @params = @_;
    
            # ... your method's code here ...
    
            return HTTP_OK; # HTTP RC
        });

    Registers new method and returns operation status

    NOTE! This is non class method!

    attrs

      Sets attributes of the method as hashref

      Default: {}

      In the method's code or response method, you can get the attribute
      values using the $self->info("attrs") method

    code

      Sets callback function

      Default: sub { return HTTP::Status::HTTP_OK }

      This callback function MUST return HTTP status code

      See HTTP::Status

    deep, depth

      Enables deeply scanning of path for method lookup. If this param is
      set to true then the mechanism of the deeply lookuping will be
      enabled. For example:

      For registered path /foo with enabled deep lookuping will be matched
      any another incoming path that begins from /foo prefix: /foo,
      /foo/bar, /foo/bar/baz and etc.

      Default: 0

    description

      Sets the description of method

      Default: none

    name

      Sets the name of method

      Default: default

    method

      Sets the HTTP method for trapping. Supported: GET, POST, PUT, DELETE.

      Default: GET

    path

      Sets the URL's path for trapping

      Default: /

    requires

      Array-ref structure that contains list of groups/users or any data
      for authorization

      Default: []

    returns

      Hash-ref structure that contains schema

      Default: {}

      See JSON::Schema, JSON::Validator, http://json-schema.org/

 middleware

    The middleware method. Runs before every Your registered methods.

    You can override this method in Your class.

    This method MUST returns HTTP status code. If code is a Successful
    status code (2xx) then Your registered method will called

    For examle:

        sub response {
                my $self = shift;
                my @params = @_;
    
                # . . .
    
                return HTTP::Status::HTTP_OK
        }

 response

    The method for response prepare.

    You can override this method in Your class.

    But note! This method MUST returns serialized or plain content for
    output

    For examle:

        sub response {
            my $self = shift;
            my @params = @_;
            my $rc = $self->code; # RC HTTP code (from yuor methods)
            my $head = $self->head; # HTTP Headers (hashref)
            my $data = $self->data; # The working data
            my $msg = $self->message || HTTP::Status::status_message($rc) || "Unknown code";
    
            # . . .
    
            my @res = (sprintf("Status: %s %s", $rc, $msg));
            push @res, sprintf("Content-Type: %s", "text/plain; charset=utf-8");
            push @res, "", $data // "";
            return join("\015\012", @res);
        }

 again

    Internal use only!

    See "again" in CTK::App

EXAMPLES

    See all examples on METACPAN website
    https://metacpan.org/release/WWW-MLite

HISTORY

    See Changes file

TO DO

    See TODO file

BUGS

    * none noted

    Please report any bugs to https://rt.cpan.org/.

SEE ALSO

    CTK, HTTP::Message

AUTHOR

    Serż Minus (Sergey Lepenkov) http://www.serzik.com <abalama@cpan.org>

COPYRIGHT

    Copyright (C) 1998-2019 D&D Corporation. All Rights Reserved

LICENSE

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    See LICENSE file and https://dev.perl.org/licenses/