The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Dancer2-Plugin-DBIx-Class-1.03
River stage one • 2 direct dependents • 2 total dependents
/ Dancer2::Plugin::DBIx::Class

NAME

Dancer2::Plugin::DBIx::Class - syntactic sugar for DBIx::Class in Dancer2, optionally with DBIx::Class::Schema::ResultSetNames

VERSION

version 1.03

SYNOPSIS

# In your Dancer2 app, without DBIx::Class::Schema::ResultSetNames
# (but why would you?)
   my $results = resultset('Human')->search( { . . .} );
#
# or, with DBIx::Class::Schema::ResultSetNames
   my $results = humans->search( { . . . } );
   my $single_person = human($human_id);

DESCRIPTION

Dancer2::Plugin::DBIx::Class adds convenience keywords to the DSL for Dancer2, in order to make database calls more semantically-friendly.

CONFIGURATION

The configuration for this plugin can go in your config.yml, or in your environment:

plugins:
  DBIC:
    # Just about any DBI-compatible DSN
    dsn: dbi:SQLite:dbname=my.db
    # Your application's schema class
    schema_class: MyApp::Schema
    # Optional. If a table name (singular or plural) is a DSL keyword, you can
    # use this to export it anyway. Module adds separator '_', so you don't
    # have to.
    export_prefix: 'db'
    # Optional. If included here, the module will not attempt to export that
    # ResultSetName at all.
    export_exclude: 
      - session      # will still export "sessions"!
      - posts        # will still attempt to export "post"! (see below)

YOU HAVE BEEN WARNED

The "optional" export_prefix configuration adds the given prefix and an underscore to the ResultSet names, if you are using DBIx::Class::Schema::ResultSetNames. It is wise to do this, if you have table names that collide with other Dancer2::Core::DSL keywords, or those added by other plugins.

As an alternative, you can use export_exclude to simply skip those ResultSet names. You can still access them with resultset('Whatever')

If you don't do either of those, the module will not export ResultSet names that collide with DSL keywords; it will carp a warning to you, advising you to use one or the other of these options to shut it up.

The logic here takes care of the horrible, horrible things will happen to your app otherwise. (session is a good example--ask me know I know!)

FUNCTIONS

schema

This keyword returns the related DBIx::Class::Schema object, ready for use.

resultset, rset, rs

These three keywords are syntactically identical, and, given a name of a DBIx::Class::ResultSet object, will return the resultset, ready for searching, or any other method you can use on a ResultSet:

my $cars = rs('Car')->search({ . . .});

NAMED RESULT SETS

DBIx::Class::Schema::ResultSetNames adds both singular and plural method accessors for all resultsets.

So, instead of this:

my $result_set = resultset('Author')->search({...});

you may choose to this:

my $result_set = authors->search({...});

And instead of this:

my $result = resultset('Author')->find($id);

you may choose to this:

my $result = author($id)

The usual caveats apply to find() returning multiple records; that behavior is deprecated, so if you try to do something like:

my $result = author( { first_name => 'John'} );

...odds are things will blow up in your face a lot. Using a unique key in find() is important.

BUT THAT'S NOT ALL!

If you combine this module, DBIx::Class::Schema::ResultSetNames, and DBIx::Class::Helper::ResultSet::Shortcut, you can do some really fabulous, easy-to-read things in a Dancer2 route, like:

# find all the books for an author, give me an array of
#    their books as Row objects, with the editions prefetched.
#
my @books = author($id)->books->prefetch('edition')->all 

# send a JSON-encoded list of hashrefs of authors with first names
#    that start with 'John' and their works to your front-end framework
#    (Some, like DevExtreme, do not cope well with the objects.)
#
send_as JSON => [ authors->like( 'first_name', 'John%')->prefetch('books')->hri->all ];

There are many really snazzy things to be found in DBIx::Class::Helpers. Many of them can make your code much more readable. Definitely worth a look-see.

Remember: your code has two developers: you, and you six months from now.

Remember also: You should write your code like the next developer to work on it is a psychopath who knows where you live.

SEE ALSO

CREDIT WHERE CREDIT IS DUE

Practically all of this code is the work of Matt S Trout (mst). I just tidied things up and wrote documentation.

SOURCE

https://gitlab.com/geekruthie/Dancer2-Plugin-DBIx-Class

HOMEPAGE

https://metacpan.org/release/Dancer2-Plugin-DBIx-Classs

AUTHOR

D Ruth Holloway <ruth@hiruthie.me>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by D Ruth Holloway.

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