# NAME

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

# VERSION

version 1.000

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

# NAME

Dancer2::Plugin::DBIx::Class - syntactic sugar for use of DBIx::Class in Dancer2

# VERSION

Version 1.0.

# 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](https://metacpan.org/pod/DBIx%3A%3AClass%3A%3ASchema%3A%3AResultSetNames). It is wise to do this, if you have table names
that collide with other [Dancer2::Core::DSL](https://metacpan.org/pod/Dancer2%3A%3ACore%3A%3ADSL) 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](https://metacpan.org/pod/DBIx%3A%3AClass%3A%3ASchema) object, ready for use.

## resultset, rset, rs

These three keywords are syntactically identical, and, given a name of a [DBIx::Class::ResultSet](https://metacpan.org/pod/DBIx%3A%3AClass%3A%3AResultSet)
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](https://metacpan.org/pod/DBIx%3A%3AClass%3A%3ASchema%3A%3AResultSetNames) 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.

# SEE ALSO

- [DBIx::Class::ResultSet](https://metacpan.org/pod/DBIx%3A%3AClass%3A%3AResultSet)
- [DBIx::Class::Schema::ResultSetNames](https://metacpan.org/pod/DBIx%3A%3AClass%3A%3ASchema%3A%3AResultSetNames)
- [DBIx::Class::Schema](https://metacpan.org/pod/DBIx%3A%3AClass%3A%3ASchema)

# CREDIT WHERE CREDIT IS DUE

Practically all of this code is the work of [Matt Trout](https://metacpan.org/author/MSTROUT).
I just tidied things up and wrote documentation.

# SOURCE

[https://gitlab.com/geekruthie/Dancer2-Plugin-DBIx-Class](https://gitlab.com/geekruthie/Dancer2-Plugin-DBIx-Class)

# HOMEPAGE

[https://metacpan.org/release/Dancer2-Plugin-DBIx-Classs](https://metacpan.org/release/Dancer2-Plugin-DBIx-Classs)

# AUTHOR

D Ruth Holloway <ruth@hiruthie.me>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2020 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.

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