The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DBIx-NinjaORM-v3.1.0
River stage zero No dependents
1 ++
/ DBIx::NinjaORM::StaticClassInfo

NAME

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

VERSION

Version 3.1.0

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:

  • default_dbh

    The database handle to use when performing queries. The methods that interact with the database always provide a dbh 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]",
        );

  • memcache

    Optionally, DBIx::NinjaORM uses memcache to cache objects and queries, in conjunction with the list_cache_time and object_cache_time arguments.

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

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

  • 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';

  • primary_key_name

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

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

  • list_cache_time

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

    By default it is disabled (with undef), 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.

  • object_cache_time

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

    By default it is disabled (with undef), 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 retrieve_list() on how to cache objects.

  • unique_fields

    The list of unique fields on the object.

    Note: DBIx::NinjaORM 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' ];

  • filtering_fields

    The list of fields that can be used to filter on in retrieve_list().

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

  • readonly_fields

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

  • has_created_field

    Indicate whether the table has a field name created 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;

  • has_modified_field

    Indicate whether the table has a field name modified 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;

  • 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';

  • verbose

    Add debugging and tracing information, 0 by default.

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

  • verbose_cache_operations

    Add information in the logs regarding cache operations and uses.

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');

METHODS

new()

Create a new DBIx::NinjaORM::StaticClassInfo object.

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

get()

Retrieve the value of one of the configuration variables.

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

set()

Set values for one or more configuration variables.

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

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/guillaumeaubert/DBIx-NinjaORM/issues/new. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

        perldoc DBIx::NinjaORM::StaticClassInfo

You can also look for information at:

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

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.