The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
App-Dochazka-REST-0.087
River stage zero No dependents
1 ++
/ App::Dochazka::REST::Model::Employee

NAME

App::Dochazka::REST::Model::Employee - Employee data model

VERSION

Version 0.087

SYNOPSIS

Employee data model

    use App::Dochazka::REST::Model::Employee;

    ...

DESCRIPTION

A description of the employee data model follows.

Employees in the database

At the database level, App::Dochazka::REST needs to be able to distinguish one employee from another. This is accomplished by the EID. All the other fields in the employees table are optional.

The employees database table is defined as follows:

    CREATE TABLE employees (
        eid       serial PRIMARY KEY,
        nick      varchar(32) UNIQUE,
        fullname  varchar(96) UNIQUE,
        email     text UNIQUE,
        passhash  text,
        salt      text,
        remark    text,
        stamp     json
    )

EID

The Employee ID (EID) is Dochazka's principal means of identifying an employee. At the site, employees will be known by other means, like their full name, their username, their user ID, etc. But these can and will change from time to time. The EID should never, ever change.

nick

The nick field is intended to be used for storing the employee's username. While storing each employee's username in the Dochazka database has undeniable advantages, it is not required - how employees are identified is a matter of site policy, and internally Dochazka does not use the nick to identify employees. Should the nick field have a value, however, Dochazka requires that it be unique.

fullname, email

Dochazka does not maintain any history of changes to the employees table.

The full_name and email fields must also be unique if they have a value. Dochazka does not check if the email address is valid.

# # FIXME: NOT IMPLEMENTED depending on how App::Dochazka::REST is configured, # these fields may be read-only for employees (changeable by admins only), or # the employee may be allowed to maintain their own information.

passhash, salt

The passhash and salt fields are optional. See "AUTHENTICATION" for details.

remark, stamp

# FIXME

Employees in the Perl API

Individual employees are represented by "employee objects". All methods and functions for manipulating these objects are contained in App::Dochazka::REST::Model::Employee. The most important methods are:

App::Dochazka::REST::Model::Employee also exports some convenience functions:

For basic employee object workflow, see the unit tests in t/004-employee.t.

EXPORTS

This module provides the following exports:

eid_by_nick - function

METHODS

spawn

Employee constructor. Does not interact with the database directly, but stores database handle for later use. Takes PARAMHASH with required parameters: 'dbh' (database handle) and 'acleid' (EID of he employee initiating the request - for ACL lookup only; _not_ the EID of an employee to look up). All subsequent operations will be carried out with the privileges of that employee, so be sure to destroy the object when finished with it. Optional parameter: PARAMHASH containing definitions of any of the attributes listed in the 'reset' method.

reset

Instance method. Resets object, either to its primal state (no arguments) or to the state given in PARAMHASH.

Accessor methods

Basic accessor methods for all the fields of employees table. These functions return whatever value happens to be associated with the object, with no guarantee that it matches the database.

eid

Accessor method.

email

Accessor method.

fullname

Accessor method.

nick

Accessor method.

passhash

Accessor method.

salt

Accessor method.

remark

Accessor method.

priv

Accessor method. Wrapper for App::Dochazka::REST::Model::Shared::priv_by_eid N.B.: for this method to work, the 'eid' attribute must be populated

schedule

Accessor method. Wrapper for App::Dochazka::REST::Model::Shared::schedule_by_eid N.B.: for this method to work, the 'eid' attribute must be populated

insert

Instance method. Takes the object, as it is, and attempts to insert it into the database. On success, overwrites object attributes with field values actually inserted. Returns a status object.

update

Instance method. Assuming that the object has been prepared, i.e. the EID corresponds to the employee to be updated and the attributes have been changed as desired, this function runs the actual UPDATE, hopefully bringing the database into line with the object. Overwrites all the object's attributes with the values actually written to the database. Returns status object.

delete

Instance method. Assuming the EID really corresponds to the employee to be deleted, this method will execute the DELETE statement in the database. It won't succeed if there are any records anywhere in the database that point to this EID. Returns a status object.

load_by_eid

Instance method. Loads employee from database, by EID, into existing object, overwriting whatever was there before. The EID value given must be an exact match. Returns a status object.

load_by_nick

Instance method. Loads employee from database, by the nick provided in the argument list, into existing object, overwriting whatever might have been there before. The nick must be an exact match. Returns a status object.

_load

Load employee, by eid or nick, into an existing object, overwriting whatever was there before. The search key (eid or nick) must be an exact match: this function returns only 1 or 0 records. Takes one of the two following PARAMHASHes:

    dbh => $dbh, nick => $nick
    dbh => $dbh, eid => $eid

FUNCTIONS

The following functions are not object methods.

eid_by_nick

** NO ACL CHECK ** Given a database handle and a nick, attempt ot retrieve the EID corresponding to the nick. Returns EID or undef on failure.

AUTHOR

Nathan Cutler, <presnypreklad@gmail.com>