From: Karen Etheridge <ether@cpan.org>
Date: Tue, 4 Feb 2014 22:54:31 +0000 (-0800)
Subject: doc amendments to clarify that "where" should not be used for foreign relationship... 
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e3022a2ccf9344fe916e013086f7d25988d9aea7;p=dbsrgits%2FDBIx-Class-Historic.git

doc amendments to clarify that "where" should not be used for foreign relationship conditions
---

diff --git a/lib/DBIx/Class/Relationship/Base.pm b/lib/DBIx/Class/Relationship/Base.pm
index 1587403..90c798a 100644
--- a/lib/DBIx/Class/Relationship/Base.pm
+++ b/lib/DBIx/Class/Relationship/Base.pm
@@ -288,14 +288,36 @@ metadata. Currently the supplied coderef is executed as:
 =head3 attributes
 
 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
-be used as relationship attributes. In particular, the 'where' attribute is
-useful for filtering relationships:
+be used as relationship attributes. However, the 'where' attribute should
+B<only> be used for adding additional conditions to other tables joined in,
+B<not> the foreign table brought in as a result of the join:
 
-     __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
+    # WRONG!
+    __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
         { 'foreign.user_id' => 'self.user_id' },
         { where => { valid => 1 } }
     );
 
+    # RIGHT!
+    __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
+        sub {
+            my $self = shift;
+            return +{
+                "$args->{foreign_alias}.user_id" => { -ident => "$args->{self_alias}.user_id" },
+                "$args->{foreign_alias}.valid => 1,
+            }
+        },
+    );
+
+    # proper use of the 'where' clause in a relationship:
+    __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
+        { 'foreign.user_id' => 'self.user_id' },
+        {
+            join => 'album',
+            where => { 'album.valid' => 1 } },
+        }
+    );
+
 The following attributes are also valid:
 
 =over 4