Jifty:...Record(3pm)

📦

version 0.78 · 2 versions

0.78 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.78 · ubuntu jammy

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

Jifty::DBI::Record 💖

okay so bestie, welcome to the Jifty::DBI::Record page — this is part of the User Contributed Perl Documentation, section 3pm, and it's literally the blueprint for every record object your Jifty::DBI::Collection hands you. sit down, get comfy, we're doing this together 🫶

NAME ✨

Jifty::DBI::Record — the superclass for records loaded by Jifty::DBI::Collection. it's giving "parent class energy" and honestly? iconic.

SYNOPSIS 🌸

package MyRecord;
use base qw/Jifty::DBI::Record/;

that's it. that's the whole vibe. you inherit, you slay 💅

DESCRIPTION 🦋

Jifty::DBI::Record wraps up records and tables as part of the Jifty::DBI object-relational mapper. no cap, it's the whole reason your database rows get to have little method lives of their own.

METHODS 👑

`new ARGS` 🎀

Spins up a brand-new, empty record object. a whole fresh baby record, zero thoughts, zero data.

ARGS is a hash, and it's used to pass parameters to the "_init()" function.

Unless somebody overloads it, _init() expects exactly one key — 'handle' — whose value holds a reference to a Jifty::DBI::Handle object. that's the one thing it needs to function, bestie.

`id` 🔑

Returns this row's primary key. the whole identity of the row, periodt.

`primary_keys` 🗝️

Returns a hash of the values of our primary keys for this function.

`_accessible COLUMN ATTRIBUTE` 🙈

Private method. do not touch, she's shy.

DEPRECATED — yeah, it's giving "old money, no money". it still works but pls don't build your life on it.

Returns undef unless "COLUMN" has a true value for "ATTRIBUTE".

Otherwise it returns "COLUMN"'s value for that attribute.

`_primary_keys` 🧚

Returns our primary keys. Subclasses should override this, but our default is that we have one primary key, and its name is 'id'.

`_init_columns` 💫

Sets up the primary key columns. behind-the-scenes queen.

`_init_methods_for_columns` 🌈

This is an internal method, and it's responsible for calling "_init_methods_for_column" for each column that's been configured. she's the manager, not the star.

`schema_version` ⭐

If this method is present, it must return a string in '1.2.3' format, and that string gets used to figure out which columns are currently active in the schema. basically, the value decides which columns are defined by being compared against the values set in "till" and "since".

If there's no implementation at all, then the "latest" schema version is assumed — which means any column defining a "till" is not active, and all the others are. easy math.

`_init_methods_for_column COLUMN` 🪄

This one is used internally to update the symbol table for the record class, adding an accessor and a mutator for each column based on the column's name. automatic getters and setters, we love a generator.

On top of that, if your record class defines the method schema_version, it'll automatically generate methods depending on whether the column currently exists for the current application schema version returned by that method. The schema_version method has to return a value in the same form used by "since" and "till".

If the column doesn't currently exist, the methods still get created — but they'll die with an error message saying the column doesn't exist for the current version of the application. if it does exist, you get a normal accessor and mutator. no drama, just vibes.

See also "active" in Jifty::DBI::Column, "since" in Jifty::DBI::Schema, and "till" in Jifty::DBI::Schema for more info, iykyk.

`null_reference` 🕳️

By default, Jifty::DBI::Record returns undef for non-existent foreign references that don't exist. like, if each Employee refers_to a Department but isn't required to, then <$model-"department>> will return undef for the employees who aren't in any department. sad little orphan employees.

If you override this method to return 0, it'll instead return a record with no id. meaning <$model-"department>> returns a Department object, but <$model-"department->id>> will be undef. a department-shaped ghost 👻

`_to_record COLUMN VALUE` 🔮

This PRIVATE method takes a column name and a value for that column.

It returns undef unless "COLUMN" is a valid column for this record and it refers to another record class.

If it is valid, the method returns a new record object with an id of "VALUE".

`prefetched NAME` 🍓

Returns the prefetched value for the column of property "NAME", if it exists. already loaded, already ready, no extra query.

`add_column` 🌸

(no description given — she's just here, standing in the corner, being mysterious 💀)

`column` 🎯

my $column = $self->column($column_name);

Returns the Jifty::DBI::Column object of the specified column name.

`columns` 📚

my @columns = $record->columns;

Returns a sorted list of a $record's @columns.

`all_columns` 🗂️

my @all_columns = $record->all_columns;

Returns all the columns for the table — even the inactive ones. everyone's invited to this party.

`readable_attributes` 📖

Returns the list of this table's readable columns. They get sorted twice, okay? first so that the primary keys come first, and then alphabetically. primary keys are the main characters, everyone else falls in line.

`serialize_metadata` 🧬

Returns a hash that describes how this class is stored in the database. right now the keys are "class", "table", and "columns". "class" and "table" return simple scalars, but "columns" returns a hash of "name => value" pairs for all the columns in this model. See "Jifty::DBI::Column/serialize_metadata" for the format of that hash.

`writable_attributes` ✍️

Returns a list of this table's writable columns.

`record values` 💜

So as you've probably already clocked, Jifty::DBI::Record automatically creates methods for your standard get/set accessors. and on top of that it hands you some hooks to massage the values being loaded or stored. little spa day for your data.

When you fetch a record value by calling $my_record->some_field, Jifty::DBI::Record provides the following hook:

`after_column_name` 🌿

This hook is called with a reference to the value returned by Jifty::DBI. Its return value is discarded. (so it's just there to look at the value and feel something, not to change anything.)

When you set a value, Jifty::DBI provides the following hooks:

`before_set_column_name PARAMHASH` 🌿

Jifty::DBI::Record passes this function a reference to a paramhash composed of:

column — The name of the column we're updating.
value — The new value for column.
is_sql_function — A boolean that, if true, indicates that value is an SQL function, not just a value.

If before_set_column_name returns false, the new value isn't set. that's a veto, bestie.

`before_set PARAMHASH` 🌿

This is identical to the before_set_column_name, but it's called for every column set. all of them. no favourites.

`after_set_column_name PARAMHASH` 🌿

This hook gets called after a value is successfully set in the database. It's called with a reference to a paramhash that contains column, value, and old_value keys. If value was a SQL function, it will now contain the actual value that was set. And if column has filters on it, value will be the result of going through an encode and decode cycle.

This hook's return value is ignored. she's just here to observe 👀

`after_set PARAMHASH` 🌿

This is identical to the after_set_column_name, but it's called for every column set.

`validate_column_name VALUE` 🌿

This hook is called right before updating the database. It expects the actual new value you're trying to set column_name to. It returns two values: the first is a boolean where truth means success, and the second is an optional message.

Heads up though — validate_column_name may be called outside the context of a set operation, purely to validate a potential value. (The Jifty application framework uses this as part of its AJAX validation system.) so it's doing double duty, and she's handling it.

`_value` 🔍

_value takes a single column name and returns that column's value for this row. Subclasses can override _value to insert custom access control. sneaky little gatekeeper behaviour, honestly valid.

`__raw_value` 🚫

Takes a column name and returns that column's raw value. Subclasses should never override __raw_value. i'm so serious. don't.

`resolve_column` 🧭

given a column name, resolve it — even if it's actually an alias — and return the column object.

`__value` 💎

Takes a column name and returns that column's value. Subclasses should never override __value. same rule, same energy.

`as_hash` 🧾

Returns a version of this record's readable columns rendered as a hash of key => value pairs. instant little snapshot.

`_set` ✏️

_set takes a single column name and a single unquoted value. It updates both the in-memory value of this column and the in-database copy. two places at once, multitasking queen. Subclasses can override _set to insert custom access control.

`load` 📥

"load" can be called as a class or object method.

Takes a single argument, $id. Calls load_by_cols to retrieve the row whose primary key is $id.

`load_by_cols` 🔎

"load_by_cols" can be called as a class or object method.

Takes a hash of columns and values. Loads the first record that matches all keys.

The hash's keys are the columns to look at.

The hash's values are either: scalar values to look for OR hash references which contain 'operator', 'value', 'case_sensitive' or 'function'.

To load something case sensitively on a case insensitive database, you can do:

$record->load_by_cols( column => { operator => '=',
                                   value => 'Foo',
                                   case_sensitive => 1 } );

look at her, being specific about case. we love a detail-oriented legend 💅

`load_by_primary_keys` 🔐

Loads records with a given set of primary keys.

`load_from_hash` 🧺

Takes a hashref, such as one created by Jifty::DBI, and populates this record's loaded values hash.

`_load_from_sql QUERYSTRING @BIND_VALUES` 🛢️

Load a record as the result of an SQL statement.

`create PARAMHASH` 🌟

"create" can be called as either a class or object method.

This method creates a new record with the values specified in the PARAMHASH.

This method calls two hooks in your subclass:

`before_create` 🌿

When adding the "before_create" trigger, you can decide whether the trigger may cause an abort or not by passing the "abortable" parameter to the "add_trigger" method. If this isn't set, then the return value is ignored regardless.

sub before_create {
    my $self = shift;
    my $args = shift;

    # Do any checks and changes on $args here.
    $args->{first_name} = ucfirst $args->{first_name};

    return;      # false return vallue will abort the create
    return 1;    # true return value will allow create to continue
}

This method is called before trying to create our row in the database. It's handed a reference to your paramhash. (That means it can modify your parameters on the fly.) "before_create" returns a true or false value. If it returns "undef" and the trigger has been added as "abortable", the create is aborted.

`after_create` 🌿

When adding the "after_create" trigger, you can decide whether the trigger may cause an abort or not by passing the "abortable" parameter to the "add_trigger" method. If this isn't set, then the return value is ignored regardless.

sub after_create {
    my $self                    = shift;
    my $insert_return_value_ref = shift;

    return unless $$insert_return_value_ref;    # bail if insert failed
    $self->load($$insert_return_value_ref);     # load ourselves from db

    # Do whatever needs to be done here

    return;   # aborts the create, possibly preventing a load
    return 1; # continue normally
}

This method is called after attempting to insert the record into the database. It gets handed a reference to the return value of the insert. That will either be a true value or a Class::ReturnValue.

Aborting the trigger merely causes "create" to return a false (undefined) value even though the create may have succeeded. This prevents the loading of the record that would normally be returned. so like — the row might literally be in the database and create still tells you no. dramatic? yes. real? also yes. 😭

delete

Okay bestie, listen up: this method yeets the record from the database. 💅

On failure, it returns a Class::ReturnValue with the error. 😭
On success, it returns 1. ✨

This method has two hooks, and they're both iconic:

before_delete

This method is called before the record deletion, if it exists. On failure it returns a Class::ReturnValue with the error. On success it returns 1. 🎀

If this method returns an error, it causes the delete to abort and return the return value from this hook. 🛑

after_delete

This method is called after deletion, with a reference to the return value from the delete operation. 🦋

table

This method returns this class's default table name. It uses Lingua::EN::Inflect to pluralize the class's name as we believe that class names for records should be in the singular and table names should be plural. 🌸

If your class name is My::App::Rhino, your table name will default to rhinos. If your class name is My::App::RhinoOctopus, your default table name will be rhino_octopuses. Not perfect, but arguably correct. 😌

collection_class

Returns the collection class which this record belongs to; override this to subclass. If you haven't specified a collection class, this returns a best guess at the name of the collection class for this collection.

It uses a simple heuristic to determine the collection class name — it appends Collection to its own name. If you want to name your records and collections differently, go right ahead, but don't say we didn't warn you. 🙈

_guess_table_name

Guesses a table name based on the class's last part. 🔍

_handle

Returns or sets the current Jifty::DBI::Handle object. 🎀

PRIVATE refers_to

Used for the declarative syntax. ✨

is_distinct COLUMN_NAME, VALUE

Checks to see if there is already a record in the database where COLUMN_NAME equals VALUE. If no such record exists then the COLUMN_NAME and VALUE pair is considered distinct and it returns 1. If a value is already present the test is considered to have failed and it returns a Class::ReturnValue with the error. 💀

run_canonicalization_for_column column => 'COLUMN', value => 'VALUE'

Runs all canonicalizers for the specified column. 🧚

has_canonicalizer_for_column COLUMN

Returns true if COLUMN has a canonicalizer, otherwise returns undef. 👑

run_validation_for_column column => 'COLUMN', value => 'VALUE' [extra => @ARGS]

Runs all validators for the specified column. 🔥

has_validator_for_column COLUMN

Returns true if COLUMN has a validator, otherwise returns undef. ⭐

unload_value COLUMN

Purges the cached value of COLUMN from the object, forcing it to be fetched from the database next time it is queried. 🌈

AUTHOR

Jesse Vincent <jesse@bestpractical.com>, Alex Vandiver <alexmv@bestpractical.com>, David Glasser <glasser@bestpractical.com>, Ruslan Zakirov <ruslan.zakirov@gmail.com> 💖

Based on DBIx::SearchBuilder::Record, whose credits read:

Jesse Vincent, <jesse@fsck.com>
Enhancements by Ivan Kohler, <ivan-rt@420.am>
Docs by Matt Knopp <mhat@netlag.com>

Jifty:...Record(3pm)

Jifty::DBI::Record 💖

NAME ✨

SYNOPSIS 🌸

DESCRIPTION 🦋

METHODS 👑

new ARGS 🎀

id 🔑

primary_keys 🗝️

_accessible COLUMN ATTRIBUTE 🙈

_primary_keys 🧚

_init_columns 💫

_init_methods_for_columns 🌈

schema_version ⭐

_init_methods_for_column COLUMN 🪄

null_reference 🕳️

_to_record COLUMN VALUE 🔮

prefetched NAME 🍓

add_column 🌸

column 🎯

columns 📚

all_columns 🗂️

readable_attributes 📖

serialize_metadata 🧬

writable_attributes ✍️

record values 💜

after_column_name 🌿

before_set_column_name PARAMHASH 🌿

before_set PARAMHASH 🌿

after_set_column_name PARAMHASH 🌿

after_set PARAMHASH 🌿

validate_column_name VALUE 🌿

_value 🔍

__raw_value 🚫

resolve_column 🧭

__value 💎

as_hash 🧾

_set ✏️

load 📥

load_by_cols 🔎

load_by_primary_keys 🔐

load_from_hash 🧺

_load_from_sql QUERYSTRING @BIND_VALUES 🛢️

create PARAMHASH 🌟

before_create 🌿

after_create 🌿