| 1 |
NAME |
| 2 |
DBIx::Class::Candy - Sugar for your favorite ORM, DBIx::Class |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
package MyApp::Schema::Result::Artist; |
| 6 |
|
| 7 |
use DBIx::Class::Candy -autotable => v1; |
| 8 |
|
| 9 |
primary_column id => { |
| 10 |
data_type => 'int', |
| 11 |
is_auto_increment => 1, |
| 12 |
}; |
| 13 |
|
| 14 |
column name => { |
| 15 |
data_type => 'varchar', |
| 16 |
size => 25, |
| 17 |
is_nullable => 1, |
| 18 |
}; |
| 19 |
|
| 20 |
has_many albums => 'A::Schema::Result::Album', 'artist_id'; |
| 21 |
|
| 22 |
1; |
| 23 |
|
| 24 |
DESCRIPTION |
| 25 |
"DBIx::Class::Candy" is a simple sugar layer for definition of |
| 26 |
DBIx::Class results. Note that it may later be expanded to add sugar for |
| 27 |
more "DBIx::Class" related things. By default "DBIx::Class::Candy": |
| 28 |
|
| 29 |
* turns on strict and warnings |
| 30 |
|
| 31 |
* sets your parent class |
| 32 |
|
| 33 |
* exports a bunch of the package methods that you normally use to |
| 34 |
define your DBIx::Class results |
| 35 |
|
| 36 |
* makes a few aliases to make some of the original method names |
| 37 |
shorter or more clear |
| 38 |
|
| 39 |
* defines very few new subroutines that transform the arguments passed |
| 40 |
to them |
| 41 |
|
| 42 |
It assumes a DBIx::Class::Core-like API, but you can tailor it to suit |
| 43 |
your needs. |
| 44 |
|
| 45 |
IMPORT OPTIONS |
| 46 |
See "SETTING DEFAULT IMPORT OPTIONS" for information on setting these |
| 47 |
schema wide. |
| 48 |
|
| 49 |
-base |
| 50 |
use DBIx::Class::Candy -base => 'MyApp::Schema::Result'; |
| 51 |
|
| 52 |
The first thing you can do to customize your usage of |
| 53 |
"DBIx::Class::Candy" is change the parent class. Do that by using the |
| 54 |
"-base" import option. |
| 55 |
|
| 56 |
-autotable |
| 57 |
use DBIx::Class::Candy -autotable => v1; |
| 58 |
|
| 59 |
Don't waste your precious keystrokes typing "table 'buildings'", let |
| 60 |
"DBIx::Class::Candy" do that for you! See "AUTOTABLE VERSIONS" for what |
| 61 |
the existing versions will generate for you. |
| 62 |
|
| 63 |
-components |
| 64 |
use DBIx::Class::Candy -components => ['FilterColumn']; |
| 65 |
|
| 66 |
"DBIx::Class::Candy" allows you to set which components you are using at |
| 67 |
import time so that the components can define their own sugar to export |
| 68 |
as well. See DBIx::Class::Candy::Exports for details on how that works. |
| 69 |
|
| 70 |
-perl5 |
| 71 |
use DBIx::Class::Candy -perl5 => v10; |
| 72 |
|
| 73 |
I love the new features in Perl 5.10 and 5.12, so I felt that it would |
| 74 |
be nice to remove the boiler plate of doing "use feature ':5.10'" and |
| 75 |
add it to my sugar importer. Feel free not to use this. |
| 76 |
|
| 77 |
-experimental |
| 78 |
use DBIx::Class::Candy -experimental => ['signatures']; |
| 79 |
|
| 80 |
I would like to use signatures and postfix dereferencing in all of my |
| 81 |
"DBIx::Class" classes. This makes that goal trivial. |
| 82 |
|
| 83 |
IMPORTED SUBROUTINES |
| 84 |
Most of the imported subroutines are the same as what you get when you |
| 85 |
use the normal interface for result definition: they have the same names |
| 86 |
and take the same arguments. In general write the code the way you |
| 87 |
normally would, leaving out the "__PACKAGE__->" part. The following are |
| 88 |
methods that are exported with the same name and arguments: |
| 89 |
|
| 90 |
belongs_to |
| 91 |
has_many |
| 92 |
has_one |
| 93 |
inflate_column |
| 94 |
many_to_many |
| 95 |
might_have |
| 96 |
remove_column |
| 97 |
remove_columns |
| 98 |
resultset_attributes |
| 99 |
resultset_class |
| 100 |
sequence |
| 101 |
source_name |
| 102 |
table |
| 103 |
|
| 104 |
There are some exceptions though, which brings us to: |
| 105 |
|
| 106 |
IMPORTED ALIASES |
| 107 |
These are merely renamed versions of the functions you know and love. |
| 108 |
The idea is to make your result classes a tiny bit prettier by aliasing |
| 109 |
some methods. If you know your "DBIx::Class" API you noticed that in the |
| 110 |
"SYNOPSIS" I used "column" instead of "add_columns" and "primary_key" |
| 111 |
instead of "set_primary_key". The old versions work, this is just nicer. |
| 112 |
A list of aliases are as follows: |
| 113 |
|
| 114 |
column => 'add_columns', |
| 115 |
primary_key => 'set_primary_key', |
| 116 |
unique_constraint => 'add_unique_constraint', |
| 117 |
relationship => 'add_relationship', |
| 118 |
|
| 119 |
SETTING DEFAULT IMPORT OPTIONS |
| 120 |
Eventually you will get tired of writing the following in every single |
| 121 |
one of your results: |
| 122 |
|
| 123 |
use DBIx::Class::Candy |
| 124 |
-base => 'MyApp::Schema::Result', |
| 125 |
-perl5 => v12, |
| 126 |
-autotable => v1, |
| 127 |
-experimental => ['signatures']; |
| 128 |
|
| 129 |
You can set all of these for your whole schema if you define your own |
| 130 |
"Candy" subclass as follows: |
| 131 |
|
| 132 |
package MyApp::Schema::Candy; |
| 133 |
|
| 134 |
use base 'DBIx::Class::Candy'; |
| 135 |
|
| 136 |
sub base { $_[1] || 'MyApp::Schema::Result' } |
| 137 |
sub perl_version { 12 } |
| 138 |
sub autotable { 1 } |
| 139 |
sub experimental { ['signatures'] } |
| 140 |
|
| 141 |
Note the "$_[1] ||" in "base". All of these methods are passed the |
| 142 |
values passed in from the arguments to the subclass, so you can either |
| 143 |
throw them away, honor them, die on usage, or whatever. To be clear, if |
| 144 |
you define your subclass, and someone uses it as follows: |
| 145 |
|
| 146 |
use MyApp::Schema::Candy |
| 147 |
-base => 'MyApp::Schema::Result', |
| 148 |
-perl5 => v18, |
| 149 |
-autotable => v1, |
| 150 |
-experimental => ['postderef']; |
| 151 |
|
| 152 |
Your "base" method will get "MyApp::Schema::Result", your "perl_version" |
| 153 |
will get 18, your "experimental" will get "['postderef']", and your |
| 154 |
"autotable" will get 1. |
| 155 |
|
| 156 |
SECONDARY API |
| 157 |
has_column |
| 158 |
There is currently a single "transformer" for "add_columns", so that |
| 159 |
people used to the Moose api will feel more at home. Note that this may |
| 160 |
go into a "Candy Component" at some point. |
| 161 |
|
| 162 |
Example usage: |
| 163 |
|
| 164 |
has_column foo => ( |
| 165 |
data_type => 'varchar', |
| 166 |
size => 25, |
| 167 |
is_nullable => 1, |
| 168 |
); |
| 169 |
|
| 170 |
primary_column |
| 171 |
Another handy little feature that allows you to define a column and set |
| 172 |
it as the primary key in a single call: |
| 173 |
|
| 174 |
primary_column id => { |
| 175 |
data_type => 'int', |
| 176 |
is_auto_increment => 1, |
| 177 |
}; |
| 178 |
|
| 179 |
If your table has multiple columns in its primary key, merely call this |
| 180 |
method for each column: |
| 181 |
|
| 182 |
primary_column person_id => { data_type => 'int' }; |
| 183 |
primary_column friend_id => { data_type => 'int' }; |
| 184 |
|
| 185 |
unique_column |
| 186 |
This allows you to define a column and set it as unique in a single |
| 187 |
call: |
| 188 |
|
| 189 |
unique_column name => { |
| 190 |
data_type => 'varchar', |
| 191 |
size => 30, |
| 192 |
}; |
| 193 |
|
| 194 |
AUTOTABLE VERSIONS |
| 195 |
Currently there are two versions: |
| 196 |
|
| 197 |
"v1" |
| 198 |
It looks at your class name, grabs everything after "::Schema::Result::" |
| 199 |
(or "::Result::"), removes the "::"'s, converts it to underscores |
| 200 |
instead of camel-case, and pluralizes it. Here are some examples if |
| 201 |
that's not clear: |
| 202 |
|
| 203 |
MyApp::Schema::Result::Cat -> cats |
| 204 |
MyApp::Schema::Result::Software::Building -> software_buildings |
| 205 |
MyApp::Schema::Result::LonelyPerson -> lonely_people |
| 206 |
MyApp::DB::Result::FriendlyPerson -> friendly_people |
| 207 |
MyApp::DB::Result::Dog -> dogs |
| 208 |
|
| 209 |
'singular' |
| 210 |
It looks at your class name, grabs everything after "::Schema::Result::" |
| 211 |
(or "::Result::"), removes the "::"'s and converts it to underscores |
| 212 |
instead of camel-case. Here are some examples if that's not clear: |
| 213 |
|
| 214 |
MyApp::Schema::Result::Cat -> cat |
| 215 |
MyApp::Schema::Result::Software::Building -> software_building |
| 216 |
MyApp::Schema::Result::LonelyPerson -> lonely_person |
| 217 |
MyApp::DB::Result::FriendlyPerson -> friendly_person |
| 218 |
MyApp::DB::Result::Dog -> dog |
| 219 |
|
| 220 |
Also, if you just want to be different, you can easily set up your own |
| 221 |
naming scheme. Just add a "gen_table" method to your candy subclass. The |
| 222 |
method gets passed the class name and the autotable version, which of |
| 223 |
course you may ignore. For example, one might just do the following: |
| 224 |
|
| 225 |
sub gen_table { |
| 226 |
my ($self, $class) = @_; |
| 227 |
|
| 228 |
$class =~ s/::/_/g; |
| 229 |
lc $class; |
| 230 |
} |
| 231 |
|
| 232 |
Which would transform "MyApp::Schema::Result::Foo" into |
| 233 |
"myapp_schema_result_foo". |
| 234 |
|
| 235 |
Or maybe instead of using the standard "MyApp::Schema::Result" namespace |
| 236 |
you decided to be different and do "MyApp::DB::Table" or something silly |
| 237 |
like that. You could pre-process your class name so that the default |
| 238 |
"gen_table" will still work: |
| 239 |
|
| 240 |
sub gen_table { |
| 241 |
my $self = shift; |
| 242 |
my $class = $_[0]; |
| 243 |
|
| 244 |
$class =~ s/::DB::Table::/::Schema::Result::/; |
| 245 |
return $self->next::method(@_); |
| 246 |
} |
| 247 |
|
| 248 |
AUTHOR |
| 249 |
Arthur Axel "fREW" Schmidt <[email protected]> |
| 250 |
|
| 251 |
COPYRIGHT AND LICENSE |
| 252 |
This software is copyright (c) 2024 by Arthur Axel "fREW" Schmidt. |
| 253 |
|
| 254 |
This is free software; you can redistribute it and/or modify it under |
| 255 |
the same terms as the Perl 5 programming language system itself. |
| 256 |
|