DBIx::...Change(3pm)

📦
version 2.037000 · 5 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 DBIx::...Change — the DBIx::Class::Helper::Row::OnColumnChange manual 💖

okay bestie, so this is a page from the User Contributed Perl Documentation section, and it's literally all about doing stuff when a column in your database changes value. it's giving main character energy for your schema. let's go 🦋

✨ NAME ✨

DBIx::Class::Helper::Row::OnColumnChange — do things when the values of a column change. like, react to it. immediately. no cap.

🌸 SYNOPSIS 🌸

okay so here's the whole vibe, with plain old DBIx::Class::Core:

package MyApp::Schema::Result::Account;

use parent 'DBIx::Class::Core';

__PACKAGE__->load_components(qw(Helper::Row::OnColumnChange));

__PACKAGE__->table('Account');

__PACKAGE__->add_columns(
   id => {
      data_type         => 'integer',
      is_auto_increment => 1,
   },
   amount => {
      data_type          => 'float',
      keep_storage_value => 1,
   },
);
sub on_column_change_allow_override_args { 1 }

__PACKAGE__->before_column_change(
  amount => {
     method   => 'bank_transfer',
     txn_wrap => 1,
  }
);

sub bank_transfer {
  my ($self, $old_value, $new_value) = @_;

  my $delta = abs($old_value - $new_value);
  if ($old_value < $new_value) {
     Bank->subtract($delta)
  } else {
     Bank->add($delta)
  }
}

1;

or, if you're a DBIx::Class::Candy girlie (and honestly? same), it looks like this:

package MyApp::Schema::Result::Account;

use DBIx::Class::Candy -components => ['Helper::Row::OnColumnChange'];

table 'Account';

column id => {
   data_type         => 'integer',
   is_auto_increment => 1,
};

column amount => {
   data_type          => 'float',
   keep_storage_value => 1,
};
sub on_column_change_allow_override_args { 1 }

before_column_change amount => {
   method   => 'bank_transfer',
   txn_wrap => 1,
};

sub bank_transfer {
  my ($self, $old_value, $new_value) = @_;

  my $delta = abs($old_value - $new_value);
  if ($old_value < $new_value) {
     Bank->subtract($delta)
  } else {
     Bank->add($delta)
  }
}

1;

🌈 DESCRIPTION 🌈

so this module codifies a pattern the author has used in a whole bunch of projects — namely, doing something when a column changes its value in the database. obsessed.

it leverages DBIx::Class::Helper::Row::StorageValues for passing in the $old_value, which you do not have to use. like, it's optional, bestie. if you leave the keep_storage_value out of the column definition it will just pass undef in as the $old_value. 🙈

also note the txn_wrap option — this lets you specify that you want the call to update and the call to the method you requested to be wrapped in a transaction. and if you end up calling more than one method because of multiple column change methods, and more than one of them specifies txn_wrap, it will still only wrap once. iconic behaviour honestly.

the author has gone to great lengths to ensure that order is preserved, so before and around changes are called in order of definition, and after changes are called in reverse order. 💅

and to be clear — the change methods only get called if the value will be changed after update runs. it correctly looks at the current value of the column as well as the arguments passed to update. so no sneaky false alarms.

🍓 CANDY EXPORTS 🍓

if used in conjunction with DBIx::Class::Candy this component will export:

before_column_change
around_column_change
after_column_change

three little gifts, just for you 🎀

👑 NO SURPRISE RACE CONDITIONS 👑

one thing that should be made totally clear is that the column change callbacks are in effect only once in a given update. periodt.

if you expect to be able to do something weird like calling one of the callbacks which changes a value with an accessor which calls a callback etc etc, you probably just need to write some code to do that yourself. this helper is specifically made with the aim of reacting to changes immediately before they hit the database. it's not a whole recursion engine, bestie, it's a vibe.

💅 METHODS 💅

before_column_change

__PACKAGE__->before_column_change(
  col_name => {
     method   => 'method', # <-- anything that can be called as a method
     txn_wrap => 1,        # <-- true if you want it to be wrapped in a txn
  }
);
note: the arguments passed to method will be $self, $old_value, $new_value.

after_column_change

__PACKAGE__->after_column_change(
  col_name => {
     method   => 'method', # <-- anything that can be called as a method
     txn_wrap => 1,        # <-- true if you want it to be wrapped in a txn
  }
);
note: the arguments passed to method will be $self, $new_value, $new_value. (because the old value has been changed.) yes, you read that right, it's $new_value twice. it's not a typo, it's just like that 😭

around_column_change

__PACKAGE__->around_column_change(
  col_name => {
     method   => 'method', # <-- anything that can be called as a method
     txn_wrap => 1,        # <-- true if you want it to be wrapped in a txn
  }
);
note: the arguments passed to method will be $self, $next, $old_value, $new_value.

around is subtly different than the other two callbacks. you must call $next in your method or it will not work at all. like, at all. zero. nada.

a silly example of how this is done could be:

sub around_change_name {
  my ($self, $next, $old, $new) = @_;

  my $govt_records = $self->govt_records;

  $next->();

  $govt_records->update({ name => $new });
}
note: the above code implies a weird database schema. the author hasn't actually seen a time when around was needed yet, but it seems like there is a use-case. 🙈

also note: you don't get to change the args to $next. if you think you should be able to, you probably don't understand what this component is for. that or you know something the author doesn't (equally likely.) no shade, fr fr.

on_column_change_allow_override_args

this is a method that allows a user to circumvent a strange bug in the initial implementation.

basically, if the user wanted, she could use before_column_change to override the value of a given column before update gets called, thus replacing the value. unfortunately this worked in the case of accessors setting the value, but not if the user had used an argument to update.

to be clear, if you want the following to actually replace the value:

__PACKAGE__->before_column_change(
   name => {
      method   => sub {
         my ($self, $old, $new) = @_;

         $self->name(uc $new);
      },
   },
);

you will need to define this in your result class:

sub on_column_change_allow_override_args { 1 }

if for some reason you need the old style, a default of false is already set. so you're safe if you don't touch it.

and if you are painted in the corner and need both, you can create an accessor and set it yourself to change the behavior:

__PACKAGE__->mk_group_accessors(inherited => 'on_column_change_allow_override_args');
...
$obj->on_column_change_allow_override_args(1); # works the new way

💜 AUTHOR 💜

Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>

This software is copyright (c) 2024 by Arthur Axel "fREW" Schmidt.

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

okay bestie that's the whole page 💖 this was documented with perl v5.40.0, dated 2024-11-16, and it lives in DBIx::...Change(3pm). go forth and make your columns change with style. 🦋✨👑

📦 where this page comes from