1DBIx::Class::Candy(3) User Contributed Perl DocumentationDBIx::Class::Candy(3)
2
3
4

NAME

6       DBIx::Class::Candy - Sugar for your favorite ORM, DBIx::Class
7

SYNOPSIS

9        package MyApp::Schema::Result::Artist;
10
11        use DBIx::Class::Candy -autotable => v1;
12
13        primary_column id => {
14          data_type => 'int',
15          is_auto_increment => 1,
16        };
17
18        column name => {
19          data_type => 'varchar',
20          size => 25,
21          is_nullable => 1,
22        };
23
24        has_many albums => 'A::Schema::Result::Album', 'artist_id';
25
26        1;
27

DESCRIPTION

29       "DBIx::Class::Candy" is a simple sugar layer for definition of
30       DBIx::Class results.  Note that it may later be expanded to add sugar
31       for more "DBIx::Class" related things.  By default
32       "DBIx::Class::Candy":
33
34       •   turns on strict and warnings
35
36       •   sets your parent class
37
38       •   exports a bunch of the package methods that you normally use to
39           define your DBIx::Class results
40
41       •   makes a few aliases to make some of the original method names
42           shorter or more clear
43
44       •   defines very few new subroutines that transform the arguments
45           passed to them
46
47       It assumes a DBIx::Class::Core-like API, but you can tailor it to suit
48       your needs.
49

IMPORT OPTIONS

51       See "SETTING DEFAULT IMPORT OPTIONS" for information on setting these
52       schema wide.
53
54   -base
55        use DBIx::Class::Candy -base => 'MyApp::Schema::Result';
56
57       The first thing you can do to customize your usage of
58       "DBIx::Class::Candy" is change the parent class.  Do that by using the
59       "-base" import option.
60
61   -autotable
62        use DBIx::Class::Candy -autotable => v1;
63
64       Don't waste your precious keystrokes typing "table 'buildings'", let
65       "DBIx::Class::Candy" do that for you!  See "AUTOTABLE VERSIONS" for
66       what the existing versions will generate for you.
67
68   -components
69        use DBIx::Class::Candy -components => ['FilterColumn'];
70
71       "DBIx::Class::Candy" allows you to set which components you are using
72       at import time so that the components can define their own sugar to
73       export as well.  See DBIx::Class::Candy::Exports for details on how
74       that works.
75
76   -perl5
77        use DBIx::Class::Candy -perl5 => v10;
78
79       I love the new features in Perl 5.10 and 5.12, so I felt that it would
80       be nice to remove the boiler plate of doing "use feature ':5.10'" and
81       add it to my sugar importer.  Feel free not to use this.
82
83   -experimental
84        use DBIx::Class::Candy -experimental => ['signatures'];
85
86       I would like to use signatures and postfix dereferencing in all of my
87       "DBIx::Class" classes.  This makes that goal trivial.
88

IMPORTED SUBROUTINES

90       Most of the imported subroutines are the same as what you get when you
91       use the normal interface for result definition: they have the same
92       names and take the same arguments.  In general write the code the way
93       you normally would, leaving out the "__PACKAGE__->" part.  The
94       following are methods that are exported with the same name and
95       arguments:
96
97        belongs_to
98        has_many
99        has_one
100        inflate_column
101        many_to_many
102        might_have
103        remove_column
104        remove_columns
105        resultset_attributes
106        resultset_class
107        sequence
108        source_name
109        table
110
111       There are some exceptions though, which brings us to:
112

IMPORTED ALIASES

114       These are merely renamed versions of the functions you know and love.
115       The idea is to make your result classes a tiny bit prettier by aliasing
116       some methods.  If you know your "DBIx::Class" API you noticed that in
117       the "SYNOPSIS" I used "column" instead of "add_columns" and
118       "primary_key" instead of "set_primary_key".  The old versions work,
119       this is just nicer.  A list of aliases are as follows:
120
121        column            => 'add_columns',
122        primary_key       => 'set_primary_key',
123        unique_constraint => 'add_unique_constraint',
124        relationship      => 'add_relationship',
125

SETTING DEFAULT IMPORT OPTIONS

127       Eventually you will get tired of writing the following in every single
128       one of your results:
129
130        use DBIx::Class::Candy
131          -base      => 'MyApp::Schema::Result',
132          -perl5     => v12,
133          -autotable => v1,
134          -experimental => ['signatures'];
135
136       You can set all of these for your whole schema if you define your own
137       "Candy" subclass as follows:
138
139        package MyApp::Schema::Candy;
140
141        use base 'DBIx::Class::Candy';
142
143        sub base { $_[1] || 'MyApp::Schema::Result' }
144        sub perl_version { 12 }
145        sub autotable { 1 }
146        sub experimental { ['signatures'] }
147
148       Note the "$_[1] ||" in "base".  All of these methods are passed the
149       values passed in from the arguments to the subclass, so you can either
150       throw them away, honor them, die on usage, or whatever.  To be clear,
151       if you define your subclass, and someone uses it as follows:
152
153        use MyApp::Schema::Candy
154           -base => 'MyApp::Schema::Result',
155           -perl5 => v18,
156           -autotable => v1,
157           -experimental => ['postderef'];
158
159       Your "base" method will get "MyApp::Schema::Result", your
160       "perl_version" will get 18, your "experimental" will get
161       "['postderef']", and your "autotable" will get 1.
162

SECONDARY API

164   has_column
165       There is currently a single "transformer" for "add_columns", so that
166       people used to the Moose api will feel more at home.  Note that this
167       may go into a "Candy Component" at some point.
168
169       Example usage:
170
171        has_column foo => (
172          data_type => 'varchar',
173          size => 25,
174          is_nullable => 1,
175        );
176
177   primary_column
178       Another handy little feature that allows you to define a column and set
179       it as the primary key in a single call:
180
181        primary_column id => {
182          data_type => 'int',
183          is_auto_increment => 1,
184        };
185
186       If your table has multiple columns in its primary key, merely call this
187       method for each column:
188
189        primary_column person_id => { data_type => 'int' };
190        primary_column friend_id => { data_type => 'int' };
191
192   unique_column
193       This allows you to define a column and set it as unique in a single
194       call:
195
196        unique_column name => {
197          data_type => 'varchar',
198          size => 30,
199        };
200

AUTOTABLE VERSIONS

202       Currently there are two versions:
203
204   "v1"
205       It looks at your class name, grabs everything after
206       "::Schema::Result::" (or "::Result::"), removes the "::"'s, converts it
207       to underscores instead of camel-case, and pluralizes it.  Here are some
208       examples if that's not clear:
209
210        MyApp::Schema::Result::Cat -> cats
211        MyApp::Schema::Result::Software::Building -> software_buildings
212        MyApp::Schema::Result::LonelyPerson -> lonely_people
213        MyApp::DB::Result::FriendlyPerson -> friendly_people
214        MyApp::DB::Result::Dog -> dogs
215
216   'singular'
217       It looks at your class name, grabs everything after
218       "::Schema::Result::" (or "::Result::"), removes the "::"'s and converts
219       it to underscores instead of camel-case.  Here are some examples if
220       that's not clear:
221
222        MyApp::Schema::Result::Cat -> cat
223        MyApp::Schema::Result::Software::Building -> software_building
224        MyApp::Schema::Result::LonelyPerson -> lonely_person
225        MyApp::DB::Result::FriendlyPerson -> friendly_person
226        MyApp::DB::Result::Dog -> dog
227
228       Also, if you just want to be different, you can easily set up your own
229       naming scheme.  Just add a "gen_table" method to your candy subclass.
230       The method gets passed the class name and the autotable version, which
231       of course you may ignore.  For example, one might just do the
232       following:
233
234        sub gen_table {
235          my ($self, $class) = @_;
236
237          $class =~ s/::/_/g;
238          lc $class;
239        }
240
241       Which would transform "MyApp::Schema::Result::Foo" into
242       "myapp_schema_result_foo".
243
244       Or maybe instead of using the standard "MyApp::Schema::Result"
245       namespace you decided to be different and do "MyApp::DB::Table" or
246       something silly like that.  You could pre-process your class name so
247       that the default "gen_table" will still work:
248
249        sub gen_table {
250          my $self = shift;
251          my $class = $_[0];
252
253          $class =~ s/::DB::Table::/::Schema::Result::/;
254          return $self->next::method(@_);
255        }
256

AUTHOR

258       Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
259
261       This software is copyright (c) 2017 by Arthur Axel "fREW" Schmidt.
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
267
268perl v5.34.0                      2022-01-21             DBIx::Class::Candy(3)
Impressum