view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    
        __PACKAGE__->load_components(qw/ InflateColumn::DateTime /);
    
        __PACKAGE__->table('artist_event');
    
        __PACKAGE__->add_columns(
            artisteventid => { data_type => 'integer', is_auto_increment => 1 },
            artistid      => { data_type => 'integer' },
    
            # The type of event
            event         => { data_type => 'varchar' },
    
            # Any other custom columns you want to store for each event.
    
            triggered_on => {
                data_type     => 'datetime',
                default_value => \'NOW()',
            },
    
            # Where we store freeform data about what happened
            details => { data_type => 'longtext' },
        );
    
        __PACKAGE__->set_primary_key('artisteventid');
    
        # You should set up automatic inflation/deflation of the details column
        # as it is used this way by "state_at" and the insert/update/delete
        # events.  Does not have to be JSON, just be able to serialize a hashref.
        {
            my $json = JSON->new->utf8;
            __PACKAGE__->inflate_column( 'details' => {
                inflate => sub { $json->decode(shift) },
                deflate => sub { $json->encode(shift) },
            } );
        }

    This belongs_to relationship is optional, and the examples and tests
    assume if it exists, it is not a real database-enforced foreign key
    that will trigger constraint violations if the thing being tracked is
    deleted.

        # A path back to the object that this event is for,
        # not required unlike the has_many "events" relationship above
        __PACKAGE__->belongs_to(
            'artist' => ( 'MyApp::Schema::Result::Artist', 'artistid' ) );

    You probably also want an index for searching for events:

        sub sqlt_deploy_hook {
            my ( $self, $sqlt_table ) = @_;
            $sqlt_table->add_index(
                name   => 'artist_event_idx',
                fields => [ "artistid", "triggered_on", "event" ],
            );
        }

PRECONFIGURED EVENTS

    Automatically creates Events for actions that modify a row.

    See the "BUGS AND LIMITATIONS" of bulk modifications on events.

    insert

      Logs all columns to the details column, with an insert event.

    update

      Logs dirty columns to the details column, with an update event.

    delete

      Logs all columns to the details column, with a delete event.

      See the "BUGS AND LIMITATIONS" for more information about using this
      method with a database enforced foreign key.

METHODS

 event

    Inserts a new event with "event_defaults":

        my $new_event = $artist->event( $event => \%params );

    First, the "event_defaults" method is called to build a list of values
    to set on the new event. This method is passed the $event and a
    reference to %params.

    Then, the %params, filtered for valid "events_relationship" columns,
    are added to the create_related arguments, overriding the defaults.

 state_at

    Takes a timestamp and returns the state of the thing at that timestamp
    as a hash reference. Can be either a correctly deflated string or a
    DateTime object that will be deflated with format_datetime.

    Returns undef if the object was not in_storage at the timestamp.

        my $state = $schema->resultset('Artist')->find( { name => 'David Bowie' } )
            ->state_at('2006-05-29 08:00');

    An idea is to use it to recreate an object as it was at that timestamp.
    Of course, default values that the database provides will not be
    included, unless the "event_defaults" method accounts for that.

        my $resurrected_object
            = $object->result_source->new( $object->state_at($timestamp) );

    See ".. format a DateTime object for searching?" under "Searching" in
    DBIx::Class::Manual::FAQ for details on formatting the timestamp.

    You can pass additional search conditions and attributes to this
    method. This is done in context of searching the events table:

        my $state = $object->state_at($timestamp, \%search_cond, \%search_attrs);

BUGS AND LIMITATIONS

    There is no attempt to handle bulk updates or deletes. So, any changes
    to the database made by calling "update" or "delete" will not create
    events the same as single row modifications. Use the "update_all" or
    "delete_all" methods of the ResultSet if you want these triggers.

    If you create the belongs_to relationship described under "Tracking
    Table" as a database-enforced foreign key then deleting from the
    tracked table will fail due to those constraints.

    There are three required columns on the "events_relationship" table:
    event, triggered_on, and details. We should eventually make those
    configurable.

SEE ALSO

    DBIx::Class::AuditAny

    DBIx::Class::AuditLog

    DBIx::Class::Journal

    DBIx::Class::PgLog

AUTHOR

    Grant Street Group <developers@grantstreet.com>

COPYRIGHT AND LICENSE

    This software is Copyright (c) 2018 - 2024 by Grant Street Group.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)