| Filename | /2home/ss5/perl5/perlbrew/perls/perl-5.12.3/lib/site_perl/5.12.3/DBIx/Class/Relationship.pm |
| Statements | Executed 11 statements in 301µs |
| Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
|---|---|---|---|---|---|
| 1 | 1 | 1 | 14µs | 16µs | DBIx::Class::Relationship::BEGIN@3 |
| 1 | 1 | 1 | 9µs | 26µs | DBIx::Class::Relationship::BEGIN@4 |
| 1 | 1 | 1 | 7µs | 103µs | DBIx::Class::Relationship::BEGIN@6 |
| Line | State ments |
Time on line |
Calls | Time in subs |
Code |
|---|---|---|---|---|---|
| 1 | package DBIx::Class::Relationship; | ||||
| 2 | |||||
| 3 | 3 | 18µs | 2 | 18µs | # spent 16µs (14+2) within DBIx::Class::Relationship::BEGIN@3 which was called:
# once (14µs+2µs) by Class::C3::Componentised::ensure_class_loaded at line 3 # spent 16µs making 1 call to DBIx::Class::Relationship::BEGIN@3
# spent 2µs making 1 call to strict::import |
| 4 | 3 | 29µs | 2 | 43µs | # spent 26µs (9+17) within DBIx::Class::Relationship::BEGIN@4 which was called:
# once (9µs+17µs) by Class::C3::Componentised::ensure_class_loaded at line 4 # spent 26µs making 1 call to DBIx::Class::Relationship::BEGIN@4
# spent 17µs making 1 call to warnings::import |
| 5 | |||||
| 6 | 3 | 240µs | 2 | 199µs | # spent 103µs (7+96) within DBIx::Class::Relationship::BEGIN@6 which was called:
# once (7µs+96µs) by Class::C3::Componentised::ensure_class_loaded at line 6 # spent 103µs making 1 call to DBIx::Class::Relationship::BEGIN@6
# spent 96µs making 1 call to base::import |
| 7 | |||||
| 8 | 1 | 10µs | 1 | 10.1ms | __PACKAGE__->load_own_components(qw/ # spent 10.1ms making 1 call to Class::C3::Componentised::load_own_components |
| 9 | Helpers | ||||
| 10 | Accessor | ||||
| 11 | CascadeActions | ||||
| 12 | ProxyMethods | ||||
| 13 | Base | ||||
| 14 | /); | ||||
| 15 | |||||
| 16 | =head1 NAME | ||||
| 17 | |||||
| 18 | DBIx::Class::Relationship - Inter-table relationships | ||||
| 19 | |||||
| 20 | =head1 SYNOPSIS | ||||
| 21 | |||||
| 22 | ## Creating relationships | ||||
| 23 | MyApp::Schema::Actor->has_many('actorroles' => 'MyApp::Schema::ActorRole', | ||||
| 24 | 'actor'); | ||||
| 25 | MyApp::Schema::Role->has_many('actorroles' => 'MyApp::Schema::ActorRole', | ||||
| 26 | 'role'); | ||||
| 27 | MyApp::Schema::ActorRole->belongs_to('role' => 'MyApp::Schema::Role'); | ||||
| 28 | MyApp::Schema::ActorRole->belongs_to('actor' => 'MyApp::Schema::Actor'); | ||||
| 29 | |||||
| 30 | MyApp::Schema::Role->many_to_many('actors' => 'actorroles', 'actor'); | ||||
| 31 | MyApp::Schema::Actor->many_to_many('roles' => 'actorroles', 'role'); | ||||
| 32 | |||||
| 33 | ## Using relationships | ||||
| 34 | $schema->resultset('Actor')->find({ id => 1})->roles(); | ||||
| 35 | $schema->resultset('Role')->find({ id => 1 })->actorroles->search_related('actor', { Name => 'Fred' }); | ||||
| 36 | $schema->resultset('Actor')->add_to_roles({ Name => 'Sherlock Holmes'}); | ||||
| 37 | |||||
| 38 | See L<DBIx::Class::Manual::Cookbook> for more. | ||||
| 39 | |||||
| 40 | =head1 DESCRIPTION | ||||
| 41 | |||||
| 42 | The word I<Relationship> has a specific meaning in DBIx::Class, see | ||||
| 43 | the definition in the L<Glossary|DBIx::Class::Manual::Glossary/Relationship>. | ||||
| 44 | |||||
| 45 | This class provides methods to set up relationships between the tables | ||||
| 46 | in your database model. Relationships are the most useful and powerful | ||||
| 47 | technique that L<DBIx::Class> provides. To create efficient database queries, | ||||
| 48 | create relationships between any and all tables that have something in | ||||
| 49 | common, for example if you have a table Authors: | ||||
| 50 | |||||
| 51 | ID | Name | Age | ||||
| 52 | ------------------ | ||||
| 53 | 1 | Fred | 30 | ||||
| 54 | 2 | Joe | 32 | ||||
| 55 | |||||
| 56 | and a table Books: | ||||
| 57 | |||||
| 58 | ID | Author | Name | ||||
| 59 | -------------------- | ||||
| 60 | 1 | 1 | Rulers of the universe | ||||
| 61 | 2 | 1 | Rulers of the galaxy | ||||
| 62 | |||||
| 63 | Then without relationships, the method of getting all books by Fred goes like | ||||
| 64 | this: | ||||
| 65 | |||||
| 66 | my $fred = $schema->resultset('Author')->find({ Name => 'Fred' }); | ||||
| 67 | my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID }); | ||||
| 68 | |||||
| 69 | With a has_many relationship called "books" on Author (see below for details), | ||||
| 70 | we can do this instead: | ||||
| 71 | |||||
| 72 | my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books; | ||||
| 73 | |||||
| 74 | Each relationship sets up an accessor method on the | ||||
| 75 | L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items | ||||
| 76 | of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects, | ||||
| 77 | the relationships can be searched using the "search_related" method. | ||||
| 78 | In list context, each returns a list of Row objects for the related class, | ||||
| 79 | in scalar context, a new ResultSet representing the joined tables is | ||||
| 80 | returned. Thus, the calls can be chained to produce complex queries. | ||||
| 81 | Since the database is not actually queried until you attempt to retrieve | ||||
| 82 | the data for an actual item, no time is wasted producing them. | ||||
| 83 | |||||
| 84 | my $cheapfredbooks = $schema->resultset('Author')->find({ | ||||
| 85 | Name => 'Fred', | ||||
| 86 | })->books->search_related('prices', { | ||||
| 87 | Price => { '<=' => '5.00' }, | ||||
| 88 | }); | ||||
| 89 | |||||
| 90 | will produce a query something like: | ||||
| 91 | |||||
| 92 | SELECT * FROM Author me | ||||
| 93 | LEFT JOIN Books books ON books.author = me.id | ||||
| 94 | LEFT JOIN Prices prices ON prices.book = books.id | ||||
| 95 | WHERE prices.Price <= 5.00 | ||||
| 96 | |||||
| 97 | all without needing multiple fetches. | ||||
| 98 | |||||
| 99 | Only the helper methods for setting up standard relationship types | ||||
| 100 | are documented here. For the basic, lower-level methods, and a description | ||||
| 101 | of all the useful *_related methods that you get for free, see | ||||
| 102 | L<DBIx::Class::Relationship::Base>. | ||||
| 103 | |||||
| 104 | =head1 METHODS | ||||
| 105 | |||||
| 106 | All helper methods are called similar to the following template: | ||||
| 107 | |||||
| 108 | __PACKAGE__->$method_name('relname', 'Foreign::Class', \%cond|\@cond|\&cond?, \%attrs?); | ||||
| 109 | |||||
| 110 | Both C<cond> and C<attrs> are optional. Pass C<undef> for C<cond> if | ||||
| 111 | you want to use the default value for it, but still want to set C<attrs>. | ||||
| 112 | |||||
| 113 | See L<DBIx::Class::Relationship::Base/condition> for full documentation on | ||||
| 114 | definition of the C<cond> argument. | ||||
| 115 | |||||
| 116 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on the | ||||
| 117 | attributes that are allowed in the C<attrs> argument. | ||||
| 118 | |||||
| 119 | |||||
| 120 | =head2 belongs_to | ||||
| 121 | |||||
| 122 | =over 4 | ||||
| 123 | |||||
| 124 | =item Arguments: $accessor_name, $related_class, $our_fk_column|\%cond|\@cond|\$cond?, \%attrs? | ||||
| 125 | |||||
| 126 | =back | ||||
| 127 | |||||
| 128 | Creates a relationship where the calling class stores the foreign | ||||
| 129 | class's primary key in one (or more) of the calling class columns. | ||||
| 130 | This relationship defaults to using C<$accessor_name> as the column | ||||
| 131 | name in this class to resolve the join against the primary key from | ||||
| 132 | C<$related_class>, unless C<$our_fk_column> specifies the foreign key column | ||||
| 133 | in this class or C<cond> specifies a reference to a join condition. | ||||
| 134 | |||||
| 135 | =over | ||||
| 136 | |||||
| 137 | =item accessor_name | ||||
| 138 | |||||
| 139 | This argument is the name of the method you can call on a | ||||
| 140 | L<DBIx::Class::Row> object to retrieve the instance of the foreign | ||||
| 141 | class matching this relationship. This is often called the | ||||
| 142 | C<relation(ship) name>. | ||||
| 143 | |||||
| 144 | Use this accessor_name in L<DBIx::Class::ResultSet/join> | ||||
| 145 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table | ||||
| 146 | indicated by this relationship. | ||||
| 147 | |||||
| 148 | =item related_class | ||||
| 149 | |||||
| 150 | This is the class name of the table referenced by the foreign key in | ||||
| 151 | this class. | ||||
| 152 | |||||
| 153 | =item our_fk_column | ||||
| 154 | |||||
| 155 | The column name on this class that contains the foreign key. | ||||
| 156 | |||||
| 157 | OR | ||||
| 158 | |||||
| 159 | =item cond | ||||
| 160 | |||||
| 161 | A hashref, arrayref or coderef specifying a custom join expression. For | ||||
| 162 | more info see L<DBIx::Class::Relationship::Base/condition>. | ||||
| 163 | |||||
| 164 | =back | ||||
| 165 | |||||
| 166 | # in a Book class (where Author has many Books) | ||||
| 167 | My::DBIC::Schema::Book->belongs_to( | ||||
| 168 | author => | ||||
| 169 | 'My::DBIC::Schema::Author', | ||||
| 170 | 'author_id' | ||||
| 171 | ); | ||||
| 172 | |||||
| 173 | # OR (same result) | ||||
| 174 | My::DBIC::Schema::Book->belongs_to( | ||||
| 175 | author => | ||||
| 176 | 'My::DBIC::Schema::Author', | ||||
| 177 | { 'foreign.author_id' => 'self.author_id' } | ||||
| 178 | ); | ||||
| 179 | |||||
| 180 | # OR (similar result but uglier accessor name) | ||||
| 181 | My::DBIC::Schema::Book->belongs_to( | ||||
| 182 | author_id => | ||||
| 183 | 'My::DBIC::Schema::Author' | ||||
| 184 | ); | ||||
| 185 | |||||
| 186 | # Usage | ||||
| 187 | my $author_obj = $book->author; # get author object | ||||
| 188 | $book->author( $new_author_obj ); # set author object | ||||
| 189 | $book->author_id(); # get the plain id | ||||
| 190 | |||||
| 191 | # To retrieve the plain id if you used the ugly version: | ||||
| 192 | $book->get_column('author_id'); | ||||
| 193 | |||||
| 194 | |||||
| 195 | If the relationship is optional -- i.e. the column containing the | ||||
| 196 | foreign key can be NULL -- then the belongs_to relationship does the | ||||
| 197 | right thing. Thus, in the example above C<< $obj->author >> would | ||||
| 198 | return C<undef>. However in this case you would probably want to set | ||||
| 199 | the L<join_type|DBIx::Class::Relationship/join_type> attribute so that | ||||
| 200 | a C<LEFT JOIN> is done, which makes complex resultsets involving | ||||
| 201 | C<join> or C<prefetch> operations work correctly. The modified | ||||
| 202 | declaration is shown below: | ||||
| 203 | |||||
| 204 | # in a Book class (where Author has_many Books) | ||||
| 205 | __PACKAGE__->belongs_to( | ||||
| 206 | author => | ||||
| 207 | 'My::DBIC::Schema::Author', | ||||
| 208 | 'author', | ||||
| 209 | { join_type => 'left' } | ||||
| 210 | ); | ||||
| 211 | |||||
| 212 | |||||
| 213 | Cascading deletes are off by default on a C<belongs_to> | ||||
| 214 | relationship. To turn them on, pass C<< cascade_delete => 1 >> | ||||
| 215 | in the $attr hashref. | ||||
| 216 | |||||
| 217 | By default, DBIC will return undef and avoid querying the database if a | ||||
| 218 | C<belongs_to> accessor is called when any part of the foreign key IS NULL. To | ||||
| 219 | disable this behavior, pass C<< undef_on_null_fk => 0 >> in the C<\%attrs> | ||||
| 220 | hashref. | ||||
| 221 | |||||
| 222 | NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent | ||||
| 223 | of C<has_a>. | ||||
| 224 | |||||
| 225 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on relationship | ||||
| 226 | methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet> | ||||
| 227 | for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES> | ||||
| 228 | which can be assigned to relationships as well. | ||||
| 229 | |||||
| 230 | =head2 has_many | ||||
| 231 | |||||
| 232 | =over 4 | ||||
| 233 | |||||
| 234 | =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs? | ||||
| 235 | |||||
| 236 | =back | ||||
| 237 | |||||
| 238 | Creates a one-to-many relationship where the foreign class refers to | ||||
| 239 | this class's primary key. This relationship refers to zero or more | ||||
| 240 | records in the foreign table (e.g. a C<LEFT JOIN>). This relationship | ||||
| 241 | defaults to using the end of this classes namespace as the foreign key | ||||
| 242 | in C<$related_class> to resolve the join, unless C<$their_fk_column> | ||||
| 243 | specifies the foreign key column in C<$related_class> or C<cond> | ||||
| 244 | specifies a reference to a join condition. | ||||
| 245 | |||||
| 246 | =over | ||||
| 247 | |||||
| 248 | =item accessor_name | ||||
| 249 | |||||
| 250 | This argument is the name of the method you can call on a | ||||
| 251 | L<DBIx::Class::Row> object to retrieve a resultset of the related | ||||
| 252 | class restricted to the ones related to the row object. In list | ||||
| 253 | context it returns the row objects. This is often called the | ||||
| 254 | C<relation(ship) name>. | ||||
| 255 | |||||
| 256 | Use this accessor_name in L<DBIx::Class::ResultSet/join> | ||||
| 257 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table | ||||
| 258 | indicated by this relationship. | ||||
| 259 | |||||
| 260 | =item related_class | ||||
| 261 | |||||
| 262 | This is the class name of the table which contains a foreign key | ||||
| 263 | column containing PK values of this class. | ||||
| 264 | |||||
| 265 | =item their_fk_column | ||||
| 266 | |||||
| 267 | The column name on the related class that contains the foreign key. | ||||
| 268 | |||||
| 269 | OR | ||||
| 270 | |||||
| 271 | =item cond | ||||
| 272 | |||||
| 273 | A hashref, arrayref or coderef specifying a custom join expression. For | ||||
| 274 | more info see L<DBIx::Class::Relationship::Base/condition>. | ||||
| 275 | |||||
| 276 | =back | ||||
| 277 | |||||
| 278 | # in an Author class (where Author has_many Books) | ||||
| 279 | # assuming related class is storing our PK in "author_id" | ||||
| 280 | My::DBIC::Schema::Author->has_many( | ||||
| 281 | books => | ||||
| 282 | 'My::DBIC::Schema::Book', | ||||
| 283 | 'author_id' | ||||
| 284 | ); | ||||
| 285 | |||||
| 286 | # OR (same result) | ||||
| 287 | My::DBIC::Schema::Author->has_many( | ||||
| 288 | books => | ||||
| 289 | 'My::DBIC::Schema::Book', | ||||
| 290 | { 'foreign.author_id' => 'self.id' }, | ||||
| 291 | ); | ||||
| 292 | |||||
| 293 | # OR (similar result, assuming related_class is storing our PK, in "author") | ||||
| 294 | # (the "author" is guessed at from "Author" in the class namespace) | ||||
| 295 | My::DBIC::Schema::Author->has_many( | ||||
| 296 | books => | ||||
| 297 | 'My::DBIC::Schema::Book', | ||||
| 298 | ); | ||||
| 299 | |||||
| 300 | |||||
| 301 | # Usage | ||||
| 302 | # resultset of Books belonging to author | ||||
| 303 | my $booklist = $author->books; | ||||
| 304 | |||||
| 305 | # resultset of Books belonging to author, restricted by author name | ||||
| 306 | my $booklist = $author->books({ | ||||
| 307 | name => { LIKE => '%macaroni%' }, | ||||
| 308 | { prefetch => [qw/book/], | ||||
| 309 | }); | ||||
| 310 | |||||
| 311 | # array of Book objects belonging to author | ||||
| 312 | my @book_objs = $author->books; | ||||
| 313 | |||||
| 314 | # force resultset even in list context | ||||
| 315 | my $books_rs = $author->books; | ||||
| 316 | ( $books_rs ) = $obj->books_rs; | ||||
| 317 | |||||
| 318 | # create a new book for this author, the relation fields are auto-filled | ||||
| 319 | $author->create_related('books', \%col_data); | ||||
| 320 | # alternative method for the above | ||||
| 321 | $author->add_to_books(\%col_data); | ||||
| 322 | |||||
| 323 | |||||
| 324 | Three methods are created when you create a has_many relationship. | ||||
| 325 | The first method is the expected accessor method, C<$accessor_name()>. | ||||
| 326 | The second is almost exactly the same as the accessor method but "_rs" | ||||
| 327 | is added to the end of the method name, eg C<$accessor_name_rs()>. | ||||
| 328 | This method works just like the normal accessor, except that it always | ||||
| 329 | returns a resultset, even in list context. The third method, named C<< | ||||
| 330 | add_to_$relname >>, will also be added to your Row items; this allows | ||||
| 331 | you to insert new related items, using the same mechanism as in | ||||
| 332 | L<DBIx::Class::Relationship::Base/"create_related">. | ||||
| 333 | |||||
| 334 | If you delete an object in a class with a C<has_many> relationship, all | ||||
| 335 | the related objects will be deleted as well. To turn this behaviour off, | ||||
| 336 | pass C<< cascade_delete => 0 >> in the C<$attr> hashref. | ||||
| 337 | |||||
| 338 | The cascaded operations are performed after the requested delete or | ||||
| 339 | update, so if your database has a constraint on the relationship, it | ||||
| 340 | will have deleted/updated the related records or raised an exception | ||||
| 341 | before DBIx::Class gets to perform the cascaded operation. | ||||
| 342 | |||||
| 343 | If you copy an object in a class with a C<has_many> relationship, all | ||||
| 344 | the related objects will be copied as well. To turn this behaviour off, | ||||
| 345 | pass C<< cascade_copy => 0 >> in the C<$attr> hashref. The behaviour | ||||
| 346 | defaults to C<< cascade_copy => 1 >>. | ||||
| 347 | |||||
| 348 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on | ||||
| 349 | relationship methods and valid relationship attributes. Also see | ||||
| 350 | L<DBIx::Class::ResultSet> for a L<list of standard resultset | ||||
| 351 | attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to | ||||
| 352 | relationships as well. | ||||
| 353 | |||||
| 354 | =head2 might_have | ||||
| 355 | |||||
| 356 | =over 4 | ||||
| 357 | |||||
| 358 | =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs? | ||||
| 359 | |||||
| 360 | =back | ||||
| 361 | |||||
| 362 | Creates an optional one-to-one relationship with a class. This relationship | ||||
| 363 | defaults to using C<$accessor_name> as the foreign key in C<$related_class> to | ||||
| 364 | resolve the join, unless C<$their_fk_column> specifies the foreign key | ||||
| 365 | column in C<$related_class> or C<cond> specifies a reference to a join | ||||
| 366 | condition. | ||||
| 367 | |||||
| 368 | =over | ||||
| 369 | |||||
| 370 | =item accessor_name | ||||
| 371 | |||||
| 372 | This argument is the name of the method you can call on a | ||||
| 373 | L<DBIx::Class::Row> object to retrieve the instance of the foreign | ||||
| 374 | class matching this relationship. This is often called the | ||||
| 375 | C<relation(ship) name>. | ||||
| 376 | |||||
| 377 | Use this accessor_name in L<DBIx::Class::ResultSet/join> | ||||
| 378 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table | ||||
| 379 | indicated by this relationship. | ||||
| 380 | |||||
| 381 | =item related_class | ||||
| 382 | |||||
| 383 | This is the class name of the table which contains a foreign key | ||||
| 384 | column containing PK values of this class. | ||||
| 385 | |||||
| 386 | =item their_fk_column | ||||
| 387 | |||||
| 388 | The column name on the related class that contains the foreign key. | ||||
| 389 | |||||
| 390 | OR | ||||
| 391 | |||||
| 392 | =item cond | ||||
| 393 | |||||
| 394 | A hashref, arrayref or coderef specifying a custom join expression. For | ||||
| 395 | more info see L<DBIx::Class::Relationship::Base/condition>. | ||||
| 396 | |||||
| 397 | =back | ||||
| 398 | |||||
| 399 | # Author may have an entry in the pseudonym table | ||||
| 400 | My::DBIC::Schema::Author->might_have( | ||||
| 401 | pseudonym => | ||||
| 402 | 'My::DBIC::Schema::Pseudonym', | ||||
| 403 | 'author_id', | ||||
| 404 | ); | ||||
| 405 | |||||
| 406 | # OR (same result, assuming the related_class stores our PK) | ||||
| 407 | My::DBIC::Schema::Author->might_have( | ||||
| 408 | pseudonym => | ||||
| 409 | 'My::DBIC::Schema::Pseudonym', | ||||
| 410 | ); | ||||
| 411 | |||||
| 412 | # OR (same result) | ||||
| 413 | My::DBIC::Schema::Author->might_have( | ||||
| 414 | pseudonym => | ||||
| 415 | 'My::DBIC::Schema::Pseudonym', | ||||
| 416 | { 'foreign.author_id' => 'self.id' }, | ||||
| 417 | ); | ||||
| 418 | |||||
| 419 | # Usage | ||||
| 420 | my $pname = $author->pseudonym; # to get the Pseudonym object | ||||
| 421 | |||||
| 422 | If you update or delete an object in a class with a C<might_have> | ||||
| 423 | relationship, the related object will be updated or deleted as well. To | ||||
| 424 | turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr> | ||||
| 425 | hashref. | ||||
| 426 | |||||
| 427 | The cascaded operations are performed after the requested delete or | ||||
| 428 | update, so if your database has a constraint on the relationship, it | ||||
| 429 | will have deleted/updated the related records or raised an exception | ||||
| 430 | before DBIx::Class gets to perform the cascaded operation. | ||||
| 431 | |||||
| 432 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on | ||||
| 433 | relationship methods and valid relationship attributes. Also see | ||||
| 434 | L<DBIx::Class::ResultSet> for a L<list of standard resultset | ||||
| 435 | attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to | ||||
| 436 | relationships as well. | ||||
| 437 | |||||
| 438 | Note that if you supply a condition on which to join, and the column in the | ||||
| 439 | current table allows nulls (i.e., has the C<is_nullable> attribute set to a | ||||
| 440 | true value), than C<might_have> will warn about this because it's naughty and | ||||
| 441 | you shouldn't do that. The warning will look something like: | ||||
| 442 | |||||
| 443 | "might_have/has_one" must not be on columns with is_nullable set to true (MySchema::SomeClass/key) | ||||
| 444 | |||||
| 445 | If you must be naughty, you can suppress the warning by setting | ||||
| 446 | C<DBIC_DONT_VALIDATE_RELS> environment variable to a true value. Otherwise, | ||||
| 447 | you probably just meant to use C<DBIx::Class::Relationship/belongs_to>. | ||||
| 448 | |||||
| 449 | =head2 has_one | ||||
| 450 | |||||
| 451 | =over 4 | ||||
| 452 | |||||
| 453 | =item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs? | ||||
| 454 | |||||
| 455 | =back | ||||
| 456 | |||||
| 457 | Creates a one-to-one relationship with a class. This relationship | ||||
| 458 | defaults to using C<$accessor_name> as the foreign key in C<$related_class> to | ||||
| 459 | resolve the join, unless C<$their_fk_column> specifies the foreign key | ||||
| 460 | column in C<$related_class> or C<cond> specifies a reference to a join | ||||
| 461 | condition. | ||||
| 462 | |||||
| 463 | =over | ||||
| 464 | |||||
| 465 | =item accessor_name | ||||
| 466 | |||||
| 467 | This argument is the name of the method you can call on a | ||||
| 468 | L<DBIx::Class::Row> object to retrieve the instance of the foreign | ||||
| 469 | class matching this relationship. This is often called the | ||||
| 470 | C<relation(ship) name>. | ||||
| 471 | |||||
| 472 | Use this accessor_name in L<DBIx::Class::ResultSet/join> | ||||
| 473 | or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table | ||||
| 474 | indicated by this relationship. | ||||
| 475 | |||||
| 476 | =item related_class | ||||
| 477 | |||||
| 478 | This is the class name of the table which contains a foreign key | ||||
| 479 | column containing PK values of this class. | ||||
| 480 | |||||
| 481 | =item their_fk_column | ||||
| 482 | |||||
| 483 | The column name on the related class that contains the foreign key. | ||||
| 484 | |||||
| 485 | OR | ||||
| 486 | |||||
| 487 | =item cond | ||||
| 488 | |||||
| 489 | A hashref, arrayref or coderef specifying a custom join expression. For | ||||
| 490 | more info see L<DBIx::Class::Relationship::Base/condition>. | ||||
| 491 | |||||
| 492 | =back | ||||
| 493 | |||||
| 494 | # Every book has exactly one ISBN | ||||
| 495 | My::DBIC::Schema::Book->has_one( | ||||
| 496 | isbn => | ||||
| 497 | 'My::DBIC::Schema::ISBN', | ||||
| 498 | 'book_id', | ||||
| 499 | ); | ||||
| 500 | |||||
| 501 | # OR (same result, assuming related_class stores our PK) | ||||
| 502 | My::DBIC::Schema::Book->has_one( | ||||
| 503 | isbn => | ||||
| 504 | 'My::DBIC::Schema::ISBN', | ||||
| 505 | ); | ||||
| 506 | |||||
| 507 | # OR (same result) | ||||
| 508 | My::DBIC::Schema::Book->has_one( | ||||
| 509 | isbn => | ||||
| 510 | 'My::DBIC::Schema::ISBN', | ||||
| 511 | { 'foreign.book_id' => 'self.id' }, | ||||
| 512 | ); | ||||
| 513 | |||||
| 514 | # Usage | ||||
| 515 | my $isbn_obj = $book->isbn; # to get the ISBN object | ||||
| 516 | |||||
| 517 | Creates a one-to-one relationship with another class. This is just | ||||
| 518 | like C<might_have>, except the implication is that the other object is | ||||
| 519 | always present. The only difference between C<has_one> and | ||||
| 520 | C<might_have> is that C<has_one> uses an (ordinary) inner join, | ||||
| 521 | whereas C<might_have> defaults to a left join. | ||||
| 522 | |||||
| 523 | The has_one relationship should be used when a row in the table must | ||||
| 524 | have exactly one related row in another table. If the related row | ||||
| 525 | might not exist in the foreign table, use the | ||||
| 526 | L<DBIx::Class::Relationship/might_have> relationship. | ||||
| 527 | |||||
| 528 | In the above example, each Book in the database is associated with exactly one | ||||
| 529 | ISBN object. | ||||
| 530 | |||||
| 531 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on | ||||
| 532 | relationship methods and valid relationship attributes. Also see | ||||
| 533 | L<DBIx::Class::ResultSet> for a L<list of standard resultset | ||||
| 534 | attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to | ||||
| 535 | relationships as well. | ||||
| 536 | |||||
| 537 | Note that if you supply a condition on which to join, if the column in the | ||||
| 538 | current table allows nulls (i.e., has the C<is_nullable> attribute set to a | ||||
| 539 | true value), than warnings might apply just as with | ||||
| 540 | L<DBIx::Class::Relationship/might_have>. | ||||
| 541 | |||||
| 542 | =head2 many_to_many | ||||
| 543 | |||||
| 544 | =over 4 | ||||
| 545 | |||||
| 546 | =item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, \%attrs? | ||||
| 547 | |||||
| 548 | =back | ||||
| 549 | |||||
| 550 | C<many_to_many> is a I<Relationship bridge> which has a specific | ||||
| 551 | meaning in DBIx::Class, see the definition in the | ||||
| 552 | L<Glossary|DBIx::Class::Manual::Glossary/Relationship bridge>. | ||||
| 553 | |||||
| 554 | C<many_to_many> is not strictly a relationship in its own right. Instead, it is | ||||
| 555 | a bridge between two resultsets which provide the same kind of convenience | ||||
| 556 | accessors as true relationships provide. Although the accessor will return a | ||||
| 557 | resultset or collection of objects just like has_many does, you cannot call | ||||
| 558 | C<related_resultset> and similar methods which operate on true relationships. | ||||
| 559 | |||||
| 560 | =over | ||||
| 561 | |||||
| 562 | =item accessor_name | ||||
| 563 | |||||
| 564 | This argument is the name of the method you can call on a | ||||
| 565 | L<DBIx::Class::Row> object to retrieve the rows matching this | ||||
| 566 | relationship. | ||||
| 567 | |||||
| 568 | On a many_to_many, unlike other relationships, this cannot be used in | ||||
| 569 | L<DBIx::Class::ResultSet/search> to join tables. Use the relations | ||||
| 570 | bridged across instead. | ||||
| 571 | |||||
| 572 | =item link_rel_name | ||||
| 573 | |||||
| 574 | This is the accessor_name from the has_many relationship we are | ||||
| 575 | bridging from. | ||||
| 576 | |||||
| 577 | =item foreign_rel_name | ||||
| 578 | |||||
| 579 | This is the accessor_name of the belongs_to relationship in the link | ||||
| 580 | table that we are bridging across (which gives us the table we are | ||||
| 581 | bridging to). | ||||
| 582 | |||||
| 583 | =back | ||||
| 584 | |||||
| 585 | To create a many_to_many relationship from Actor to Role: | ||||
| 586 | |||||
| 587 | My::DBIC::Schema::Actor->has_many( actor_roles => | ||||
| 588 | 'My::DBIC::Schema::ActorRoles', | ||||
| 589 | 'actor' ); | ||||
| 590 | My::DBIC::Schema::ActorRoles->belongs_to( role => | ||||
| 591 | 'My::DBIC::Schema::Role' ); | ||||
| 592 | My::DBIC::Schema::ActorRoles->belongs_to( actor => | ||||
| 593 | 'My::DBIC::Schema::Actor' ); | ||||
| 594 | |||||
| 595 | My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles', | ||||
| 596 | 'role' ); | ||||
| 597 | |||||
| 598 | And, for the reverse relationship, from Role to Actor: | ||||
| 599 | |||||
| 600 | My::DBIC::Schema::Role->has_many( actor_roles => | ||||
| 601 | 'My::DBIC::Schema::ActorRoles', | ||||
| 602 | 'role' ); | ||||
| 603 | |||||
| 604 | My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' ); | ||||
| 605 | |||||
| 606 | To add a role for your actor, and fill in the year of the role in the | ||||
| 607 | actor_roles table: | ||||
| 608 | |||||
| 609 | $actor->add_to_roles($role, { year => 1995 }); | ||||
| 610 | |||||
| 611 | In the above example, ActorRoles is the link table class, and Role is the | ||||
| 612 | foreign class. The C<$link_rel_name> parameter is the name of the accessor for | ||||
| 613 | the has_many relationship from this table to the link table, and the | ||||
| 614 | C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship | ||||
| 615 | from the link table to the foreign table. | ||||
| 616 | |||||
| 617 | To use many_to_many, existing relationships from the original table to the link | ||||
| 618 | table, and from the link table to the end table must already exist, these | ||||
| 619 | relation names are then used in the many_to_many call. | ||||
| 620 | |||||
| 621 | In the above example, the Actor class will have 3 many_to_many accessor methods | ||||
| 622 | set: C<roles>, C<add_to_roles>, C<set_roles>, and similarly named accessors | ||||
| 623 | will be created for the Role class for the C<actors> many_to_many | ||||
| 624 | relationship. | ||||
| 625 | |||||
| 626 | See L<DBIx::Class::Relationship::Base/attributes> for documentation on | ||||
| 627 | relationship methods and valid relationship attributes. Also see | ||||
| 628 | L<DBIx::Class::ResultSet> for a L<list of standard resultset | ||||
| 629 | attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to | ||||
| 630 | relationships as well. | ||||
| 631 | |||||
| 632 | =cut | ||||
| 633 | |||||
| 634 | 1 | 5µs | 1; | ||
| 635 | |||||
| 636 | =head1 AUTHORS | ||||
| 637 | |||||
| 638 | see L<DBIx::Class> | ||||
| 639 | |||||
| 640 | =head1 LICENSE | ||||
| 641 | |||||
| 642 | You may distribute this code under the same terms as Perl itself. | ||||
| 643 | |||||
| 644 | =cut | ||||
| 645 |