Koha Namespace RFC

Koha Namespace

Status:	unknown
Sponsored by:	no-one
Developed by:	lot of ppl
Expected for:	2012-06-10
Bug number:	Bug 8309
Work in progress repository:	link(s) to currently published work on this RFC
Description:	A Description of how the Koha namespace will be set up.

Koha Namespace

The Koha namespace will be separated into 3 primary compoents

Koha::DB

The lowest level, this is the only level that will have direct database access, and will be built on DBIx::Class

Koha::DataObject

Since some tables are logically linked ( biblio and biblioitems, accountlines and accountoffsets, etc. ) this level will use those Koha::DB objects to present a single unified view to the next layer.

Often we will have a 1 to 1 relationship between Koha::DB and Koha::DataObject ( for example, Koha::DB::Branches and Koha::DataObject::Branches ). It may be possible in these cases for the DataObject class to be a simple wrapper for the DB class.

Classes in this namespace will use standard method naming conventions when possible to prevent confusion over what a method does ( GetObject, CreateObject, UpdateObject, DeleteObject [ and perhapts GetObjects, UpdateObjects, etc. ] ). 

Koha::Service

This is what we have been referring to as simply the Koha namespace. This is where we put all out business logic. These are the only Perl modules that our cgi-scripts will use. We can continue to just put anything that would belong here in the Koha:: namespace, but I will use Koha::Service here for clarity.

Example workflow

Perl script ( e.g. /admin/banch.pl ) ↓ ↑ Koha::Service ( e.g. Koha::Service::Branches ) ↓ ↑ Koha::Data ( e.g. Koha::Data::Branches ) ↓ ↑ Koha::Schema ( e.g. Koha::Schema::Branches )

Inside the Koha::Service namespace, modules will *never* access modules sideways or backwards.

For example, we may have the following modules as part of our circulation:

Koha::Service::Circulation::CheckIn

Koha::Service::Circulation::Checkout

Koha::Service::Circulation::Accounts

These modules will *never* interact with each other. If Koha::Service::Circulation::CheckIn needs to create a fine, it will use Koha::Data::Accounts. In this way, we will avoid creating circular dependencies. 

List of neccessary modules

Koha::Schema::{One for each table}

Koha::Data::BiblioRecord ( combines Koha::Schema::Biblio & Koha::Schema::Biblioitem )

Koha::Service::Circulation::CheckIn
Koha::Service::Circulation::Checkout
Koha::Service::Circulation::Accounts

Koha::Service::Branches

Other standards

Use OOP

All modules in the Koha::Schema and Koha::Data namespaces should be strictly Object Oriented, though the methods may be static where applicable.

Pass Parameters by Hash

Parameter passing should be done by hashes. For example

$object->method( param1 => $param1, param2 => $param2, param3 => $param3, param4 => $param4 );

sub method { my %params = @_;

my $param1 = $params{param1}; my $param2 = $params{param2}; my $param3 = $params{param3}; return unless ( $param1 && $param2 ); return unless ( $param3 || $param4 );

Do Something Useful

}

In this way, we would eliminate the mess of parameters many Koha subroutines have ( e.g. myFunction( $param1, $param2, undef, undef, $param3 ); ).

We can return or die ( or even croak ) if a required param is missing.

This will give us greater flexebility when modifying the methods in the future. With this method, we only need to pass the parameters we need to, rather than needing to many undef's as part of the parameters. We will no longer need to have code that looks like myFunction( $param1, undef, $param2, $parmam3, undef, undef, $param4 ).