NAME

Mixin::Historian - a mixin for recording history about objects

VERSION

version 0.102001

SYNOPSIS

  package My::Object;
  use Mixin::Historian -history => {
    driver => {
      class => 'YourDriver',
      ...,
    },
  };

  # Later...
  my $object = My::Object->retrieve(1234);

  $object->add_history({
    type     => 'lava damage',
    severity => 'very badly burned',
    volcano  => 'Eyjafjallajokull',
  });

DESCRIPTION

Mixin::Historian is an application of Mixin::ExtraFields. If you're not familiar with it, you should read about it, both in its documentation and in this article about Mixin::ExtraFields.

Generally, it provides simple mechanism for write-only history. Importing the -history group will get you the add_history method, which generally will accept one hashref with at least a type key. This will be passed along to the driver's add_history method.

PERL VERSION

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

TODO

I have shoehorned an extra layer of functionality into the Historian driver that I use in my employer's code. When initialized, the Historian mixin is told all legal types, something like this:

  type_map => {
    'lava damage' => {
      severity => { required => 1, store_as => 'extra_1' },
      volcano  => { required => 0, store_as => 'extra_2' },
    },
    ...
  }

This way, history entries can be validated before writing. The store_as entries indicate how the arguments to add_history are mapped to database columns. The entire argument is also stored in one field as JSON, and a few other attributes are always required (like by_whom) and some are added just in time (like logged_at).

This feature is not yet present in the CPAN library because I have not yet found a suitable decomposition of concerns to make it a component.

AUTHOR

Ricardo Signes <cpan@semiotic.systems>

CONTRIBUTOR

Ricardo Signes <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Ricardo Signes.

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