/ 
ActiveRecord-Simple-0.22
River stage zero No dependents
/ ActiveRecord::Simple

NAME

ActiveRecord::Simple - Simple to use lightweight implementation of ActiveRecord pattern.

VERSION

Version 0.22

NAME

ActiveRecord::Simple

VERSION

0.21

DESCRIPTION

ActiveRecord::Simple is a simple lightweight implementation of ActiveRecord pattern. It's fast, very simple and very ligth.

SYNOPSIS

package MyModel:Person;

use base 'ActiveRecord::Simple';

__PACKAGE__->table_name('persons');
__PACKAGE__->columns(['id', 'name']);
__PACKAGE__->primary_key('id');

1;

That's it! Now you're ready to use your active-record class in the application:

use MyModel::Person;

# to create a new record:
my $person = MyModel::Person->new({ name => 'Foo' })->save();

# to update the record:
$person->name('Bar')->save();

# to find a record (by primary key):
my $person = MyModel::Person->find(1);

# to find many records by parameters:
my @persons = MyModel::Person->find({ name => 'Foo' })->fetch();

# to find records by sql-condition:
my @persons = MyModel::Person->find('name = ?', 'Foo')->fetch();

# also you can do something like this:
my $persons = MyModel::Person->find('name = ?', 'Foo');
while ( my $person = $persons->fetch() ) {
    say $person->name;
}

# You can add any relationships to your tables:
__PACKAGE__->relations({
    cars => {
        class       => 'MyModel::Car',
        foreign_key => 'id_person',
        type        => 'many',
    },
    wife => {
        class       => 'MyModel::Wife',
        foreign_key => 'id_person',
        type        => 'one',
    }
});

# And then, you're ready to go:
say $person->cars->fetch->id; # if the relation is one to many
say $person->wife->name; # if the relation is one to one

METHODS

ActiveState::Simple provides a variety of techniques to make your work with data little easier. It contains only a basic set of operations, such as serch, create, update and delete data.

If you realy need more complicated solution, just try to expand on it with your own methods.

Class Methods

Class methods mean that you can't do something with a separate row of the table, but they need to manipulate of the table as a whole object. You may find a row in the table or keep database hanlder etc.

new

Creates a new object, one row of the data.

MyModel::Person->new({ name => 'Foo', second_name => 'Bar' });

It's a constructor of your class and it doesn't save a data in the database, just creates a new record in memory.

columns

__PACKAGE__->columns([qw/id_person first_name second_name]);

Set names of the table columns and add accessors to object of the class. This method is required to use in the child (your model) classes.

primary_key

__PACKAGE__->primary_key('id_person');

Set name of the primary key. This method is reqired to use in the child (your model) classes.

table_name

__PACKAGE__->table_name('persons');

Set name of the table. This method is reqired to use in the child (your model) classes.

relations

__PACKAGE__->relations({
    cars => {
        class => 'MyModel::Car',
        foreign_key => 'id_person',
        type => 'many'
    },
});

It's not a required method and you don't have to use it if you don't want to use any relationships in youre tables and objects. However, if you need to, just keep this simple schema in youre mind:

__PACKAGE__->relations({
    [relation key] => {
        class => [class name],
        foreign_key => [column that refferers to the table],
        type => [many or one]
    },
})

[relation key] - this is a key that will be provide the access to instance
of the another class (which is specified in the option "class" below),
associated with this relationship. Allowed to use as many keys as you need:

$package_instance->[relation key]->[any method from the related class];

find

There are several ways to find someone in your database using ActiveRecord::Simple:

# by primary key:
my $person = MyModel::Person->find(1);

# by multiple primary keys
my @persons = MyModel::Person->find([1, 2, 5])->fetch();

# by simple condition:
my @persons = MyModel::Person->find({ name => 'Foo' })->fetch();

# by where-condtions:
my @persons = MyModel::Person->find('first_name = ? and id_person > ?', 'Foo', 1);

If you want to get an instance of youre active-record class and if you know the primary key, you can do it, just put the primary key as a parameter into the find method:

my $person = MyModel::Person->find(1);

In this case, you will get only one instance (because can't be more than one rows in the table with the same values of the primary key).

If you want to get a few instances by primary keys, you should put it as arrayref, and then fetch from resultset:

my @persons = MyModel::Person->find([1, 2])->fetch();

# you don't have to fetch it immidiatly, of course:
my $resultset = MyModel::Person->find([1, 2]);
while ( my $person = $resultset->fetch() ) {
    say $person->first_name;
}

To find some rows by simple condition, use a hashref:

my @persons = MyModel::Person->find({ first_name => 'Foo' })->fetch();

Simple condition means that you can use only this type of it:

{ first_name => 'Foo' } goes to "first_type = 'Foo'";
{ first_name => 'Foo', id_person => 1 } goes to "first_type = 'Foo' and id_person = 1";

If you want to use a real sql where-condition:

my $res = MyModel::Person->find('first_name = ? or id_person > ?', 'Foo', 1);
# select * from persons where first_name = "Foo" or id_person > 1;

dbh

Keeps a database connection handler. It's not a class method actually, this is an attribute of the base class and you can put your database handler in any class:

Person->dbh($dbh);

Or even rigth in base class:

ActiveRecord::Simple->dbh($dht);

This decision is up to you. Anyway, this is a singleton value, and keeps only once at the session.

Object Methods

Object methods usefull to manipulating single rows as a separate objects.

save

To insert or update data in the table, use only one method. It detects automatically what do you want to do with it. If your object was created by the new method and never has been saved before, method will insert your data.

If you took the object using the find method, "save" will mean "update".

my $person = MyModel::Person->new({
    first_name => 'Foo',
    secnd_name => 'Bar',
});

$person->save() # -> insert

$person->first_name('Baz');
$person->save() # -> now it's update!

### or

my $person = MyModel::Person->find(1);
$person->first_name('Baz');
$person->save() # update

delete

$person->delete();

Delete row from the table.

is_exists_in_database

Checks for a record in the database corresponding to the object:

my $person = MyModel::Person->new({
    first_name => 'Foo',
    secnd_name => 'Bar',
});

$person->save() unless $person->is_exists_in_database;

to_hash

Convert objects data to the simple perl hash:

use JSON::XS;

say encode_json({ person => $peron->to_hash });

is_defined

Checks weather an object is defined:

my $person = MyModel::Person->find(1);
return unless $person->is_defined;

fetch

When you use the "find" method to get a few rows from the table, you get the meta-object with a several objects inside. To use all of them or only a part, use the "fetch" method:

my @persons = MyModel::Person->find('id_person != ?', 1)->fetch();

You can also specify how many objects you want to use:

my @persons = MyModel::Person->find('id_person != ?', 1)->fetch(2);
# fetching only 2 objects.

Private Methods

Most of this methods you can't use directly in your code.

fill_params

Fill parameters.

find_many_by_condition

One of the "find" methods.

find_many_by_params

One of the "find" methods.

find_many_by_primary_keys

One of the "find" methods.

find_one_by_primary_key

One of the "find" methods.

get_all

You can get a whole table as a hashref:

my $table = Person->get_all();

You also may specify which rows you want to use:

my $table = Person->get_all(['name']);

insert

Insert (save).

mk_accessors

This method makes accessors.

mk_attribute_getter

This method makes attribute getter.

quote_string

Quote string.

update

Update (save).

AUTHOR

shootnix, <shootnix at cpan.org>

BUGS

Please report any bugs or feature requests to shootnix@cpan.org, or through the github: https://github.com/shootnix/activerecord-simple/issues

SUPPORT

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

perldoc ActiveRecord::Simple

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2013 shootnix.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.