lib/DBIx/Class/ResultSource/View.pm

   1 package DBIx::Class::ResultSource::View;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base 'DBIx::Class::ResultSource';
   7
   8 __PACKAGE__->mk_group_accessors( rsrc_instance_specific_attribute => qw(
   9   is_virtual view_definition deploy_depends_on
  10 ));
  11
  12 =head1 NAME
  13
  14 DBIx::Class::ResultSource::View - ResultSource object representing a view
  15
  16 =head1 SYNOPSIS
  17
  18   package MyApp::Schema::Result::Year2000CDs;
  19
  20   use base qw/DBIx::Class::Core/;
  21
  22   __PACKAGE__->table_class('DBIx::Class::ResultSource::View');
  23
  24   __PACKAGE__->table('year2000cds');
  25   __PACKAGE__->result_source->is_virtual(1);
  26   __PACKAGE__->result_source->view_definition(
  27       "SELECT cdid, artist, title FROM cd WHERE year ='2000'"
  28   );
  29   __PACKAGE__->add_columns(
  30     'cdid' => {
  31       data_type => 'integer',
  32       is_auto_increment => 1,
  33     },
  34     'artist' => {
  35       data_type => 'integer',
  36     },
  37     'title' => {
  38       data_type => 'varchar',
  39       size      => 100,
  40     },
  41   );
  42
  43 =head1 DESCRIPTION
  44
  45 View object that inherits from L<DBIx::Class::ResultSource>
  46
  47 This class extends ResultSource to add basic view support.
  48
  49 A view has a L</view_definition>, which contains a SQL query. The query can
  50 only have parameters if L</is_virtual> is set to true. It may contain JOINs,
  51 sub selects and any other SQL your database supports.
  52
  53 For virtual views the column names returned by the view definition SQL
  54 must match the names in
  55 L<add_columns|DBIx::Class::ResultSource/add_columns>, while for
  56 non-vritual views the order must match.
  57
  58 View definition SQL is deployed to your database on
  59 L<DBIx::Class::Schema/deploy> unless you set L</is_virtual> to true.
  60
  61 Deploying the view does B<not> translate it between different database
  62 syntaxes, so be careful what you write in your view SQL.
  63
  64 Virtual views (L</is_virtual> true), are assumed to not
  65 exist in your database as a real view. The L</view_definition> in this
  66 case replaces the view name in a FROM clause in a subselect.
  67
  68 =head1 EXAMPLES
  69
  70 Having created the MyApp::Schema::Result::Year2000CDs schema as shown in the
  71 SYNOPSIS above, you can then:
  72
  73   $y2000_cds = $schema->resultset('Year2000CDs')
  74                       ->search()
  75                       ->all();
  76   $count     = $schema->resultset('Year2000CDs')
  77                       ->search()
  78                       ->count();
  79
  80 If you modified the schema to include a placeholder
  81
  82   __PACKAGE__->result_source->view_definition(
  83       "SELECT cdid, artist, title FROM cd WHERE year = ?"
  84   );
  85
  86 and ensuring you have is_virtual set to true:
  87
  88   __PACKAGE__->result_source->is_virtual(1);
  89
  90 You could now say:
  91
  92   $y2001_cds = $schema->resultset('Year2000CDs')
  93                       ->search({}, { bind => [2001] })
  94                       ->all();
  95   $count     = $schema->resultset('Year2000CDs')
  96                       ->search({}, { bind => [2001] })
  97                       ->count();
  98
  99 =head1 SQL EXAMPLES
 100
 101 =over
 102
 103 =item is_virtual set to false
 104
 105   $schema->resultset('Year2000CDs')->all();
 106
 107   SELECT cdid, artist, title FROM year2000cds me
 108
 109 =item is_virtual set to true
 110
 111   $schema->resultset('Year2000CDs')->all();
 112
 113   SELECT cdid, artist, title FROM
 114     (SELECT cdid, artist, title FROM cd WHERE year ='2000') me
 115
 116 =back
 117
 118 =head1 METHODS
 119
 120 =head2 is_virtual
 121
 122   __PACKAGE__->result_source->is_virtual(1);
 123
 124 Set to true for a virtual view, false or unset for a real
 125 database-based view.
 126
 127 =head2 view_definition
 128
 129   __PACKAGE__->result_source->view_definition(
 130       "SELECT cdid, artist, title FROM cd WHERE year ='2000'"
 131       );
 132
 133 An SQL query for your view. Will not be translated across database
 134 syntaxes.
 135
 136 =head2 deploy_depends_on
 137
 138   __PACKAGE__->result_source->deploy_depends_on(
 139       ["MyApp::Schema::Result::Year","MyApp::Schema::Result::CD"]
 140       );
 141
 142 Specify the views (and only the views) that this view depends on.
 143 Pass this an array reference of fully qualified result classes.
 144
 145 =head1 OVERRIDDEN METHODS
 146
 147 =head2 from
 148
 149 Returns the FROM entry for the table (i.e. the view name)
 150 or the SQL as a subselect if this is a virtual view.
 151
 152 =cut
 153
 154 sub from {
 155     $_[0]->throw_exception('from() is not a setter method') if @_ > 1;
 156     $_[0]->is_virtual
 157       ? \( '(' . $_[0]->view_definition .')' )
 158       : $_[0]->name
 159     ;
 160 }
 161
 162 =head1 OTHER METHODS
 163
 164 =head2 new
 165
 166 The constructor.
 167
 168 =cut
 169
 170 sub new {
 171     my ( $self, @args ) = @_;
 172     my $new = $self->next::method(@args);
 173     $new->{deploy_depends_on} =
 174       { map { $_ => 1 }
 175           @{ $new->{deploy_depends_on} || [] } }
 176       unless ref $new->{deploy_depends_on} eq 'HASH';
 177     return $new;
 178 }
 179
 180 =head1 FURTHER QUESTIONS?
 181
 182 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
 183
 184 =head1 COPYRIGHT AND LICENSE
 185
 186 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
 187 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
 188 redistribute it and/or modify it under the same terms as the
 189 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
 190
 191 =cut
 192
 193 1;