1DBIx::Class::Candy(3) User Contributed Perl DocumentationDBIx::Class::Candy(3)
2
6 DBIx::Class::Candy - Sugar for your favorite ORM, DBIx::Class
7
9 package MyApp::Schema::Result::Artist;
10 use DBIx::Class::Candy -autotable => v1;
12 primary_column id => {
14 data_type => 'int',
15 is_auto_increment => 1,
16 };
17 column name => {
19 data_type => 'varchar',
20 size => 25,
21 is_nullable => 1,
22 };
23 has_many albums => 'A::Schema::Result::Album', 'artist_id';
25 1;
27
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 • turns on strict and warnings
35 • sets your parent class
37 • exports a bunch of the package methods that you normally use to
39 define your DBIx::Class results
40 • makes a few aliases to make some of the original method names
42 shorter or more clear
43 • defines very few new subroutines that transform the arguments
45 passed to them
46 It assumes a DBIx::Class::Core-like API, but you can tailor it to suit
48 your needs.
49
51 See "SETTING DEFAULT IMPORT OPTIONS" for information on setting these
52 schema wide.
53 -base
55 use DBIx::Class::Candy -base => 'MyApp::Schema::Result';
56 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 -autotable
62 use DBIx::Class::Candy -autotable => v1;
63 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 -components
69 use DBIx::Class::Candy -components => ['FilterColumn'];
70 "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 -perl5
77 use DBIx::Class::Candy -perl5 => v10;
78 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 -experimental
84 use DBIx::Class::Candy -experimental => ['signatures'];
85 I would like to use signatures and postfix dereferencing in all of my
87 "DBIx::Class" classes. This makes that goal trivial.
88
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 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 There are some exceptions though, which brings us to:
112
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 column => 'add_columns',
122 primary_key => 'set_primary_key',
123 unique_constraint => 'add_unique_constraint',
124 relationship => 'add_relationship',
125
127 Eventually you will get tired of writing the following in every single
128 one of your results:
129 use DBIx::Class::Candy
131 -base => 'MyApp::Schema::Result',
132 -perl5 => v12,
133 -autotable => v1,
134 -experimental => ['signatures'];
135 You can set all of these for your whole schema if you define your own
137 "Candy" subclass as follows:
138 package MyApp::Schema::Candy;
140 use base 'DBIx::Class::Candy';
142 sub base { $_[1] || 'MyApp::Schema::Result' }
144 sub perl_version { 12 }
145 sub autotable { 1 }
146 sub experimental { ['signatures'] }
147 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 use MyApp::Schema::Candy
154 -base => 'MyApp::Schema::Result',
155 -perl5 => v18,
156 -autotable => v1,
157 -experimental => ['postderef'];
158 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
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 Example usage:
170 has_column foo => (
172 data_type => 'varchar',
173 size => 25,
174 is_nullable => 1,
175 );
176 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 primary_column id => {
182 data_type => 'int',
183 is_auto_increment => 1,
184 };
185 If your table has multiple columns in its primary key, merely call this
187 method for each column:
188 primary_column person_id => { data_type => 'int' };
190 primary_column friend_id => { data_type => 'int' };
191 unique_column
193 This allows you to define a column and set it as unique in a single
194 call:
195 unique_column name => {
197 data_type => 'varchar',
198 size => 30,
199 };
200
202 Currently there are two versions:
203 "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 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 '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 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 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 sub gen_table {
235 my ($self, $class) = @_;
236 $class =~ s/::/_/g;
238 lc $class;
239 }
240 Which would transform "MyApp::Schema::Result::Foo" into
242 "myapp_schema_result_foo".
243 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 sub gen_table {
250 my $self = shift;
251 my $class = $_[0];
252 $class =~ s/::DB::Table::/::Schema::Result::/;
254 return $self->next::method(@_);
255 }
256
258 Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
259
261 This software is copyright (c) 2017 by Arthur Axel "fREW" Schmidt.
262 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.
265perl v5.34.0 2021-07-22 DBIx::Class::Candy(3)