File Coverage

blib/lib/DBIx/NinjaORM/StaticClassInfo.pm

Criterion	Covered	Total	%
statement	26	26	100.0
branch	8	8	100.0
condition			n/a
subroutine	8	8	100.0
pod	3	3	100.0
total	45	45	100.0

package DBIx::NinjaORM::StaticClassInfo;

use 5.010;

use strict;
use warnings;

use Carp;
use Data::Validate::Type;


=head1 NAME

DBIx::NinjaORM::StaticClassInfo - Hold the configuration information for L classes.


=head1 VERSION

Version 3.1.0

=cut

our $VERSION = '3.1.0';


=head1 DESCRIPTION

This package is used to store and retrieve defaults as well as general
information for a specific class. It allows for example indicating what table
the objects will be related to, or what database handle to use.

Here's the full list of the options that can be set or overridden:

=over 4

=item * default_dbh

The database handle to use when performing queries. The methods that interact
with the database always provide a C argument to allow using a specific
database handle, but setting it here means you won't have to systematically
pass that argument.

	$info->{'default_dbh'} = DBI->connect(
		"dbi:mysql:[database_name]:localhost:3306",
		"[user]",
		"[password]",
	);

=item * memcache

Optionally, C uses memcache to cache objects and queries,
in conjunction with the C and C arguments.

If you want to enable the cache features, you can set this to a valid
C object (or a compatible module, such as
C).

	$info->{'memcache'} = Cache::Memcached::Fast->new(
		{
			servers =>
			[
				'localhost:11211',
			],
		}
	);

=item * table_name

Mandatory, the name of the table that this class will be the interface for.

	# Interface with a 'books' table.
	$info->{'table_name'} = 'books';

=item * primary_key_name

The name of the primary key on the table specified with C.

	$info->{'primary_key_name'} = 'book_id';

=item * list_cache_time

Control the list cache, which is an optional cache system in
C to store how search criteria translate into object IDs.

By default it is disabled (with C), but it is activated by setting it to
an integer that represents the cache time in seconds.

	# Cache for 10 seconds.
	$info->{'list_cache_time'} = 10;

	# Don't cache.
	$info->{'list_cache_time'} = undef;

A good use case for this would be retrieving a list of books for a given author.
We would pass the author ID as a search criteria, and the resulting list of book
objects does not change often. Provided that you can tolerate a 1 hour delay
for a new book to show up associated with a given author, then it makes sense
to set the list_cache_time to 3600 and save most of the queries to find what
book otherwise belongs to the author.

=item * object_cache_time

Control the object cache, which is an optional cache system in
C to store the objects returned and be able to look them up
by object ID.

By default it is disabled (with C), but it is activated by setting it to
an integer that represents the cache time in seconds.

	# Cache for 10 seconds.
	$info->{'object_cache_time'} = 10;

	# Don't cache.
	$info->{'object_cache_time'} = undef;

A good use case for this are objects that are expensive to build. You will see
more in C on how to cache objects.

=item * unique_fields

The list of unique fields on the object.

Note: L does not support unique indexes made of more than one
field. If you add more than one field in this arrayref, the ORM will treat them
as separate unique indexes.

	# Declare books.isbn as unique.
	$info->{'unique_fields'} = [ 'isbn' ];

	# Declare books.isbn and books.upc as unique.
	$info->{'unique_fields'} = [ 'isbn', 'upc' ];

=item * filtering_fields

The list of fields that can be used to filter on in C.

	# Allow filtering based on the book name and author ID.
	$info->{'unique_fields'} = [ 'name', 'author_id' ];

=item * readonly_fields

The list of fields that cannot be set directly. They will be populated in
C, but you won't be able to insert / update / set them directly.

=item * has_created_field

Indicate whether the table has a field name C to store the UNIX time
at which the row was created. Default: 1.

	# The table doesn't have a 'created' field.
	$info->{'has_created_field'} = 0;

=item * has_modified_field

Indicate whether the table has a field name C to store the UNIX time
at which the row was modified. Default: 1.

	# The table doesn't have a 'modified' field.
	$info->{'has_modified_field'} = 0;

=item * cache_key_field

By default, the object cache uses the primary key value to make cached objects
available to look up, but this allows specifying a different field for that
purpose.

For example, you may want to use books.isbn instead of books.book_id to cache
objects:

	$info->{'cache_key_field'} = 'isbn';

=item * verbose

Add debugging and tracing information, 0 by default.

	# Show debugging information for operations on this class.
	$info->{'verbose'} = 1;

=item * verbose_cache_operations

Add information in the logs regarding cache operations and uses.

=back


=head1 SYNOPSIS

	my $static_class_info = $class->SUPER::static_class_info();

	# Set or override information.
	$static_class_info->set(
		{
			table_name       => 'books',
			primary_key_name => 'book_id',
			default_dbh      => DBI->connect(
				"dbi:mysql:[database_name]:localhost:3306",
				"[user]",
				"[password]",
			),
		}
	);

	# Retrieve information.
	my $table_name = $static_class_info->get('table_name');


=head1 METHODS

=head2 new()

Create a new L object.

	my $static_class_info = DBIx::NinjaORM::StaticClassInfo->new();

=cut

sub new
{
	my ( $class ) = @_;

	return bless(
		{
			'default_dbh'              => undef,
			'memcache'                 => undef,
			'table_name'               => undef,
			'primary_key_name'         => undef,
			'list_cache_time'          => undef,
			'object_cache_time'        => undef,
			'unique_fields'            => [],
			'filtering_fields'         => [],
			'readonly_fields'          => [],
			'has_created_field'        => 1,
			'has_modified_field'       => 1,
			'cache_key_field'          => undef,
			'verbose'                  => 0,
			'verbose_cache_operations' => 0,
		},
		$class,
	);
}


=head2 get()

Retrieve the value of one of the configuration variables.

	my $value = $static_class_info->get( $key );

=cut

sub get
{
	my ( $self, $key ) = @_;

	croak "The key name must be defined"
		if !defined( $key );
	croak "The key '$key' is not valid"
		if !exists( $self->{ $key } );

	return $self->{ $key };
}

=head2 set()

Set values for one or more configuration variables.

	$static_class_info->set(
		{
			unique_fields    => [],
			filtering_fields => [],
			...
		}
	);

=cut

sub set ## no critic (NamingConventions::ProhibitAmbiguousNames, Subroutines::RequireArgUnpacking)
{
	croak 'The first argument passed must be a hashref'
		if !Data::Validate::Type::is_hashref( $_[1] );

	my ( $self, $values ) = @_;

	foreach my $key ( keys %$values )
	{
		croak "The key '$key' is not valid"
			if !exists( $self->{ $key } );

		$self->{ $key } = $values->{ $key };
	}

	return;
}


=head1 BUGS

Please report any bugs or feature requests through the web interface at
L.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.


=head1 SUPPORT

You can find documentation for this module with the perldoc command.

	perldoc DBIx::NinjaORM::StaticClassInfo


You can also look for information at:

=over 4

=item * GitHub's request tracker

L

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * MetaCPAN

L

=back


=head1 AUTHOR

Guillaume Aubert, C<<  >>.


=head1 COPYRIGHT & LICENSE

Copyright 2009-2017 Guillaume Aubert.

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the LICENSE file for more details.

=cut

1;