Inflators are not respected by find() (being a ResultSet method)

Adjust docs and add an extra IC::DT-specific FAQ section

diff --git a/AUTHORS b/AUTHORS
index 509f54d..fe261d1 100644 (file)
--- a/AUTHORS
+++ b/AUTHORS
@@ -20,6 +20,7 @@ aherzog: Adam Herzog <adam@herzogdesigns.com>
 Alexander Keusch <cpan@keusch.at>
 alexrj: Alessandro Ranellucci <aar@cpan.org>
 alnewkirk: Al Newkirk <github@alnewkirk.com>
+Altreus: Alastair McGowan-Douglas <alastair.mcgowan@opusvl.com>
 amiri: Amiri Barksdale <amiribarksdale@gmail.com>
 amoore: Andrew Moore <amoore@cpan.org>
 Andrew Mehta <Andrew@unitedgames.co.uk>

diff --git a/Changes b/Changes
index a9db781..3618e50 100644 (file)
--- a/Changes
+++ b/Changes
@@ -28,7 +28,7 @@ Revision history for DBIx::Class
 
     * Misc
         - Remove warning about potential side effects of RT#79576 (scheduled)
-        - Various doc improvements (GH#62, GH#70, GH#71, GH#72)
+        - Various doc improvements (GH#62, GH#66, GH#70, GH#71, GH#72)
         - Skip tests in a way more intelligent and speedy manner when optional
           dependencies are missing
         - Make the Optional::Dependencies error messages cpanm-friendly

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index cf80dd8..d08022a 100644 (file)
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -1770,11 +1770,11 @@ C<< [column_name => value] >>.
 =head2 Formatting DateTime objects in queries
 
 To ensure C<WHERE> conditions containing L<DateTime> arguments are properly
-formatted to be understood by your RDBMS, you must use the C<DateTime>
+formatted to be understood by your RDBMS, you must use the L<DateTime>
 formatter returned by L<DBIx::Class::Storage::DBI/datetime_parser> to format
 any L<DateTime> objects you pass to L<search|DBIx::Class::ResultSet/search>
 conditions. Any L<Storage|DBIx::Class::Storage> object attached to your
-L<Schema|DBIx::Class::Schema> provides a correct C<DateTime> formatter, so
+L<Schema|DBIx::Class::Schema> provides a correct L<DateTime> formatter, so
 all you have to do is:
 
   my $dtf = $schema->storage->datetime_parser;
@@ -1793,12 +1793,11 @@ Without doing this the query will contain the simple stringification of the
 C<DateTime> object, which almost never matches the RDBMS expectations.
 
 This kludge is necessary only for conditions passed to
-L<DBIx::Class::ResultSet/search>, whereas
-L<create|DBIx::Class::ResultSet/create>,
-L<find|DBIx::Class::ResultSet/find>,
-L<DBIx::Class::Row/update> (but not L<DBIx::Class::ResultSet/update>) are all
+L<search|DBIx::Class::ResultSet/search> and L<DBIx::Class::ResultSet/find>,
+whereas L<create|DBIx::Class::ResultSet/create> and
+L<DBIx::Class::Row/update> (but not L<DBIx::Class::ResultSet/update>) are
 L<DBIx::Class::InflateColumn>-aware and will do the right thing when supplied
-an inflated C<DateTime> object.
+an inflated L<DateTime> object.
 
 =head2 Using Unicode
 

diff --git a/lib/DBIx/Class/Manual/FAQ.pod b/lib/DBIx/Class/Manual/FAQ.pod
index 92ac0f7..b8dbe17 100644 (file)
--- a/lib/DBIx/Class/Manual/FAQ.pod
+++ b/lib/DBIx/Class/Manual/FAQ.pod
@@ -262,6 +262,39 @@ alter session statements on database connection establishment:
  ->on_connect_do("ALTER SESSION SET NLS_SORT = 'BINARY_CI'");
  ->on_connect_do("ALTER SESSION SET NLS_SORT = 'GERMAN_CI'");
 
+=item .. format a DateTime object for searching?
+
+L<search|DBIx::Class::ResultSet/search> and L<find|DBIx::Class::ResultSet/find>
+do not take L<DBIx::Class::InflateColumn> into account, and so your L<DateTime>
+object will not be correctly deflated into a format your RDBMS expects.
+
+The L<datetime_parser|DBIx::Class::Storage::DBI/datetime_parser> method on your
+storage object can be used to return the object that would normally do this, so
+it's easy to do it manually:
+
+  my $dtf = $schema->storage->datetime_parser;
+  my $rs = $schema->resultset('users')->search(
+    {
+      signup_date => {
+        -between => [
+          $dtf->format_datetime($dt_start),
+          $dtf->format_datetime($dt_end),
+        ],
+      }
+    },
+  );
+
+With in a Result Class method, you can get this from the
+L<C<result_source>|DBIx::Class::Row/result_source>.
+
+  my $dtf = $self->result_source->storage->datetime_parser;
+
+This kludge is necessary only for conditions passed to
+L<search|DBIx::Class::ResultSet/search> and L<DBIx::Class::ResultSet/find>,
+whereas L<create|DBIx::Class::ResultSet/create> and L<DBIx::Class::Row/update>
+(but not L<DBIx::Class::ResultSet/update>) are
+L<DBIx::Class::InflateColumn>-aware and will do the right thing when supplied
+an inflated L<DateTime> object.
 
 =back
 

diff --git a/lib/DBIx/Class/Storage/DBI.pm b/lib/DBIx/Class/Storage/DBI.pm
index 044ecfa..d56dd00 100644 (file)
--- a/lib/DBIx/Class/Storage/DBI.pm
+++ b/lib/DBIx/Class/Storage/DBI.pm
@@ -1669,8 +1669,8 @@ sub _gen_sql_bind {
   ) {
     carp_unique 'DateTime objects passed to search() are not supported '
       . 'properly (InflateColumn::DateTime formats and settings are not '
-      . 'respected.) See "Formatting DateTime objects in queries" in '
-      . 'DBIx::Class::Manual::Cookbook. To disable this warning for good '
+      . 'respected.) See ".. format a DateTime object for searching?" in '
+      . 'DBIx::Class::Manual::FAQ. To disable this warning for good '
       . 'set $ENV{DBIC_DT_SEARCH_OK} to true'
   }