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.02
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.02

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:
        dsn: dbi:SQLite:dbname=my.db    # Just about any DBI-compatible DSN goes here
        schema_class: MyApp::Schema
        export_prefix: 'db_'            # Optional, unless a table name (singular or plural)
                                        # is also a DSL keyword.

YOU HAVE BEEN WARNED

The "optional" export_prefix configuration adds the given prefix 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. It is likely that horrible, horrible things will happen to your app if you don't take care of this. (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.