lib/Dancer2/Plugin/DBIC.pm

   1 package Dancer2::Plugin::DBIC;
   2
   3 our $VERSION = '0.0100'; # VERSION
   4
   5 use strict;
   6 use warnings;
   7 use utf8;
   8 use Dancer2::Plugin;
   9 use DBICx::Sugar;
  10
  11 sub _schema {
  12     my ($dsl, $name, $cfg) = @_;
  13     my $config;
  14     # ugly switch needed to support plugin2 plugins which use this plugin
  15     # whilst still working for plugin1
  16     if ( $dsl->app->can('with_plugin') ) {
  17         $config = $dsl->config;
  18     }
  19     else {
  20         $config = plugin_setting;
  21     }
  22     DBICx::Sugar::config( $config );
  23     return DBICx::Sugar::schema($name, $cfg);
  24 }
  25
  26 sub _rset {
  27     my ($dsl, $rset_name) = @_;
  28     return schema($dsl)->resultset($rset_name);
  29 }
  30
  31 register schema    => \&_schema;
  32 register resultset => \&_rset;
  33 register rset      => \&_rset;
  34 register_plugin;
  35
  36 # ABSTRACT: DBIx::Class interface for Dancer2 applications
  37
  38
  39 1;
  40
  41 __END__
  42
  43 =pod
  44
  45 =encoding UTF-8
  46
  47 =head1 NAME
  48
  49 Dancer2::Plugin::DBIC - DBIx::Class interface for Dancer2 applications
  50
  51 =head1 VERSION
  52
  53 version 0.0100
  54
  55 =head1 SYNOPSIS
  56
  57     use Dancer2;
  58     use Dancer2::Plugin::DBIC;
  59
  60     get '/users/:user_id' => sub {
  61         my $user = schema('default')->resultset('User')->find(param 'user_id');
  62
  63         # If you are accessing the 'default' schema, then all the following
  64         # are equivalent to the above:
  65         $user = schema->resultset('User')->find(param 'user_id');
  66         $user = resultset('User')->find(param 'user_id');
  67         $user = rset('User')->find(param 'user_id');
  68
  69         template user_profile => {
  70             user => $user
  71         };
  72     };
  73
  74     dance;
  75
  76 =head1 DESCRIPTION
  77
  78 This plugin makes it very easy to create L<Dancer2> applications that interface
  79 with databases.
  80 It automatically exports the keyword C<schema> which returns a
  81 L<DBIx::Class::Schema> object.
  82 It also exports the keywords C<resultset> and C<rset>.
  83 You just need to configure your database connection information.
  84 For performance, schema objects are cached in memory
  85 and are lazy loaded the first time they are accessed.
  86
  87 This plugin is a thin wrapper around L<DBICx::Sugar>.
  88
  89 =head1 CONFIGURATION
  90
  91 Configuration can be done in your L<Dancer2> config file.
  92 This is a minimal example. It defines one database named C<default>:
  93
  94     plugins:
  95       DBIC:
  96         default:
  97           dsn: dbi:SQLite:dbname=some.db
  98
  99 In this example, there are 2 databases configured named C<default> and C<foo>:
 100
 101     plugins:
 102       DBIC:
 103         default:
 104           dsn: dbi:SQLite:dbname=some.db
 105           schema_class: MyApp::Schema
 106         foo:
 107           dsn: dbi:mysql:foo
 108           schema_class: Foo::Schema
 109           user: bob
 110           password: secret
 111           options:
 112             RaiseError: 1
 113             PrintError: 1
 114
 115 Each database configured must at least have a dsn option.
 116 The dsn option should be the L<DBI> driver connection string.
 117 All other options are optional.
 118
 119 If you only have one schema configured, or one of them is named
 120 C<default>, you can call C<schema> without an argument to get the only
 121 or C<default> schema, respectively.
 122
 123 If a schema_class option is not provided, then L<DBIx::Class::Schema::Loader>
 124 will be used to dynamically load the schema by introspecting the database
 125 corresponding to the dsn value.
 126 Remember that you need L<DBIx::Class::Schema::Loader> installed to take
 127 advantage of that.
 128
 129 The schema_class option, should be a proper Perl package name that
 130 Dancer2::Plugin::DBIC will use as a L<DBIx::Class::Schema> class.
 131 Optionally, a database configuration may have user, password, and options
 132 parameters as described in the documentation for C<connect()> in L<DBI>.
 133
 134 You may also declare your connection information in the following format
 135 (which may look more familiar to DBIC users):
 136
 137     plugins:
 138       DBIC:
 139         default:
 140           connect_info:
 141             - dbi:mysql:foo
 142             - bob
 143             - secret
 144             -
 145               RaiseError: 1
 146               PrintError: 1
 147
 148 =head1 FUNCTIONS
 149
 150 =head2 schema
 151
 152     my $user = schema->resultset('User')->find('bob');
 153
 154 The C<schema> keyword returns a L<DBIx::Class::Schema> object ready for you to
 155 use.
 156 If you have configured only one database, then you can simply call C<schema>
 157 with no arguments.
 158 If you have configured multiple databases,
 159 you can still call C<schema> with no arguments if there is a database
 160 named C<default> in the configuration.
 161 With no argument, the C<default> schema is returned.
 162 Otherwise, you B<must> provide C<schema()> with the name of the database:
 163
 164     my $user = schema('foo')->resultset('User')->find('bob');
 165
 166 =head2 resultset
 167
 168 This is a convenience method that will save you some typing.
 169 Use this B<only> when accessing the C<default> schema.
 170
 171     my $user = resultset('User')->find('bob');
 172
 173 is equivalent to:
 174
 175     my $user = schema->resultset('User')->find('bob');
 176
 177 =head2 rset
 178
 179     my $user = rset('User')->find('bob');
 180
 181 This is simply an alias for C<resultset>.
 182
 183 =head1 SCHEMA GENERATION
 184
 185 There are two approaches for generating schema classes.
 186 You may generate your own L<DBIx::Class> classes and set
 187 the corresponding C<schema_class> setting in your configuration as shown above.
 188 This is the recommended approach for performance and stability.
 189
 190 It is also possible to have schema classes dynamically generated
 191 if you omit the C<schema_class> configuration setting.
 192 This requires you to have L<DBIx::Class::Schema::Loader> installed.
 193 The C<v7> naming scheme will be used for naming the auto generated classes.
 194 See L<DBIx::Class::Schema::Loader::Base/naming> for more information about
 195 naming.
 196
 197 For generating your own schema classes,
 198 you can use the L<dbicdump> command line tool provided by
 199 L<DBIx::Class::Schema::Loader> to help you.
 200 For example, if your app were named Foo, then you could run the following
 201 from the root of your project directory:
 202
 203     dbicdump -o dump_directory=./lib Foo::Schema dbi:SQLite:/path/to/foo.db
 204
 205 For that example, your C<schema_class> setting would be C<Foo::Schema>.
 206
 207 =head1 SEE ALSO
 208
 209 =over 4
 210
 211 =item *
 212
 213 L<DBICx::Sugar>
 214
 215 =back
 216
 217 =head1 CONTRIBUTORS
 218
 219 =over 4
 220
 221 =item *
 222
 223 Alexis Sukrieh <sukria@sukria.net>
 224
 225 =item *
 226
 227 Dagfinn Ilmari Mannsåker <L<https://github.com/ilmari>>
 228
 229 =item *
 230
 231 David Precious <davidp@preshweb.co.uk>
 232
 233 =item *
 234
 235 ennio <L<https://github.com/scriplit>>
 236
 237 =item *
 238
 239 Fabrice Gabolde <L<https://github.com/fgabolde>>
 240
 241 =item *
 242
 243 Franck Cuny <franck@lumberjaph.net>
 244
 245 =item *
 246
 247 Steven Humphrey <L<https://github.com/shumphrey>>
 248
 249 =item *
 250
 251 Yanick Champoux <L<https://github.com/yanick>>
 252
 253 =back
 254
 255 =head1 AUTHOR
 256
 257 Naveed Massjouni <naveed@vt.edu>
 258
 259 =head1 COPYRIGHT AND LICENSE
 260
 261 This software is copyright (c) 2013 by Naveed Massjouni.
 262
 263 This is free software; you can redistribute it and/or modify it under
 264 the same terms as the Perl 5 programming language system itself.
 265
 266 =cut