Merge 'trunk' into 'DBIx-Class-current'

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Manual / Cookbook.pod

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index 7fed731..248c0b6 100644 (file)
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -442,6 +442,17 @@ Or just iterate through the values of this column only:
     print $c;
   }
 
+C<ResultSetColumn> only has a limited number of built-in functions, if
+you need one that it doesn't have, then you can use the C<func> method
+instead:
+
+  my $avg = $cost->func('AVERAGE');
+
+This will cause the following SQL statement to be run:
+
+  SELECT AVERAGE(Cost) FROM Items me
+
+Which will of course only work if your database supports this function.
 See L<DBIx::Class::ResultSetColumn> for more documentation.
 
 =head2 Using relationships
@@ -476,7 +487,7 @@ To order C<< $book->pages >> by descending page_number.
 =head2 Transactions
 
 As of version 0.04001, there is improved transaction support in
-L<DBIx::Class::Storage::DBI> and L<DBIx::Class::Schema>.  Here is an
+L<DBIx::Class::Storage> and L<DBIx::Class::Schema>.  Here is an
 example of the recommended way to use it:
 
   my $genus = $schema->resultset('Genus')->find(12);
@@ -894,7 +905,7 @@ method.
 
 =head2 Profiling
 
-When you enable L<DBIx::Class::Storage::DBI>'s debugging it prints the SQL
+When you enable L<DBIx::Class::Storage>'s debugging it prints the SQL
 executed as well as notifications of query completion and transaction
 begin/commit.  If you'd like to profile the SQL you can subclass the
 L<DBIx::Class::Storage::Statistics> class and write your own profiling
@@ -978,7 +989,7 @@ seperate proxy-class files for this.  We would be copying all the user
 methods into the Admin class.  There is a cleaner way to accomplish
 this.
 
-Overriding the C<inflate_results()> method within the User proxy-class
+Overriding the C<inflate_result> method within the User proxy-class
 gives us the effect we want.  This method is called by
 L<DBIx::Class::ResultSet> when inflating a result from storage.  So we
 grab the object being returned, inspect the values we are looking for,
@@ -1085,4 +1096,54 @@ B<Test File> test.pl
     ### The statement below will print 
     print "I can do admin stuff\n" if $admin->can('do_admin_stuff'); 
 
+=head2 Skip object creation for faster results
+
+DBIx::Class is not built for speed, it's built for convenience and
+ease of use, but sometimes you just need to get the data, and skip the
+fancy objects. Luckily this is also fairly easy using
+C<inflate_result>:
+
+  # Define a class which just returns the results as a hashref:
+  package My::HashRefInflator;
+
+  ## $me is the hashref of cols/data from the immediate resultsource
+  ## $prefetch is a deep hashref of all the data from the prefetched
+  ##   related sources.
+
+  sub mk_hash {
+     my ($me, $rest) = @_;
+
+     return { %$me, 
+        map { ($_ => mk_hash(@{$rest->{$_}})) } keys %$rest
+     };
+  }
+
+  sub inflate_result {
+     my ($self, $source, $me, $prefetch) = @_;
+     return mk_hash($me, $prefetch); 
+  }
+
+  # Change the object inflation to a hashref for just this resultset:
+  $rs->result_class('My::HashRefInflator');
+
+  my $datahashref = $rs->next;
+  foreach my $col (keys %$datahashref) {
+     if(!ref($datahashref->{$col})) {
+        # It's a plain value
+     }
+     elsif(ref($datahashref->{$col} eq 'HASH')) {
+        # It's a related value in a hashref
+     }
+  }
+
+=head2 Want to know if find_or_create found or created a row?
+
+Just use C<find_or_new> instead, then check C<in_storage>:
+
+  my $obj = $rs->find_or_new({ blah => 'blarg' });
+  unless ($obj->in_storage) {
+    $obj->insert;
+    # do whatever else you wanted if it was a new row
+  }
+
 =cut