Koha/Objects.pm

   1 package Koha::Objects;
   2
   3 # Copyright ByWater Solutions 2014
   4 #
   5 # This file is part of Koha.
   6 #
   7 # Koha is free software; you can redistribute it and/or modify it under the
   8 # terms of the GNU General Public License as published by the Free Software
   9 # Foundation; either version 3 of the License, or (at your option) any later
  10 # version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License along
  17 # with Koha; if not, write to the Free Software Foundation, Inc.,
  18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  19
  20 use Modern::Perl;
  21
  22 use Carp;
  23
  24 use Koha::Database;
  25
  26 =head1 NAME
  27
  28 Koha::Objects - Koha Object set base class
  29
  30 =head1 SYNOPSIS
  31
  32     use Koha::Objects;
  33     my @objects = Koha::Objects->search({ borrowernumber => $borrowernumber});
  34
  35 =head1 DESCRIPTION
  36
  37 This class must be subclassed.
  38
  39 =head1 API
  40
  41 =head2 Class Methods
  42
  43 =cut
  44
  45 =head3 Koha::Objects->new();
  46
  47 my $object = Koha::Objects->new();
  48
  49 =cut
  50
  51 sub new {
  52     my ($class) = @_;
  53     my $self = {};
  54
  55     bless( $self, $class );
  56 }
  57
  58 =head3 Koha::Objects->_new_from_dbic();
  59
  60 my $object = Koha::Objects->_new_from_dbic( $resultset );
  61
  62 =cut
  63
  64 sub _new_from_dbic {
  65     my ( $class, $resultset ) = @_;
  66     my $self = { _resultset => $resultset };
  67
  68     bless( $self, $class );
  69 }
  70
  71 =head3 Koha::Objects->find();
  72
  73 my $object = Koha::Objects->find($id);
  74 my $object = Koha::Objects->find( { keypart1 => $keypart1, keypart2 => $keypart2 } );
  75
  76 =cut
  77
  78 sub find {
  79     my ( $self, $id ) = @_;
  80
  81     return unless defined($id);
  82
  83     my $result = $self->_resultset()->find($id);
  84
  85     return unless $result;
  86
  87     my $object = $self->object_class()->_new_from_dbic( $result );
  88
  89     return $object;
  90 }
  91
  92 =head3 Koha::Objects->find_or_create();
  93
  94 my $object = Koha::Objects->find_or_create( $attrs );
  95
  96 =cut
  97
  98 sub find_or_create {
  99     my ( $self, $params ) = @_;
 100
 101     my $result = $self->_resultset->find_or_create($params);
 102
 103     return unless $result;
 104
 105     my $object = $self->object_class->_new_from_dbic($result);
 106
 107     return $object;
 108 }
 109
 110 =head3 Koha::Objects->search();
 111
 112 my @objects = Koha::Objects->search($params);
 113
 114 =cut
 115
 116 sub search {
 117     my ( $self, $params, $attributes ) = @_;
 118
 119     if (wantarray) {
 120         my @dbic_rows = $self->_resultset()->search($params, $attributes);
 121
 122         return $self->_wrap(@dbic_rows);
 123
 124     }
 125     else {
 126         my $class = ref($self) ? ref($self) : $self;
 127         my $rs = $self->_resultset()->search($params, $attributes);
 128
 129         return $class->_new_from_dbic($rs);
 130     }
 131 }
 132
 133 =head3 Koha::Objects->next();
 134
 135 my $object = Koha::Objects->next();
 136
 137 Returns the next object that is part of this set.
 138 Returns undef if there are no more objects to return.
 139
 140 =cut
 141
 142 sub next {
 143     my ( $self ) = @_;
 144
 145     my $result = $self->_resultset()->next();
 146     return unless $result;
 147
 148     my $object = $self->object_class()->_new_from_dbic( $result );
 149
 150     return $object;
 151 }
 152
 153 =head3 Koha::Objects->reset();
 154
 155 Koha::Objects->reset();
 156
 157 resets iteration so the next call to next() will start agein
 158 with the first object in a set.
 159
 160 =cut
 161
 162 sub reset {
 163     my ( $self ) = @_;
 164
 165     $self->_resultset()->reset();
 166
 167     return $self;
 168 }
 169
 170 =head3 Koha::Objects->as_list();
 171
 172 Koha::Objects->as_list();
 173
 174 Returns an arrayref of the objects in this set.
 175
 176 =cut
 177
 178 sub as_list {
 179     my ( $self ) = @_;
 180
 181     my @dbic_rows = $self->_resultset()->all();
 182
 183     my @objects = $self->_wrap(@dbic_rows);
 184
 185     return wantarray ? @objects : \@objects;
 186 }
 187
 188 =head3 Koha::Objects->unblessed
 189
 190 Returns an unblessed representation of objects.
 191
 192 =cut
 193
 194 sub unblessed {
 195     my ($self) = @_;
 196
 197     return [ map { $_->unblessed } $self->as_list ];
 198 }
 199
 200 =head3 Koha::Objects->_wrap
 201
 202 wraps the DBIC object in a corresponding Koha object
 203
 204 =cut
 205
 206 sub _wrap {
 207     my ( $self, @dbic_rows ) = @_;
 208
 209     my @objects = map { $self->object_class()->_new_from_dbic( $_ ) } @dbic_rows;
 210
 211     return @objects;
 212 }
 213
 214 =head3 Koha::Objects->_resultset
 215
 216 Returns the internal resultset or creates it if undefined
 217
 218 =cut
 219
 220 sub _resultset {
 221     my ($self) = @_;
 222
 223     if ( ref($self) ) {
 224         $self->{_resultset} ||=
 225           Koha::Database->new()->schema()->resultset( $self->_type() );
 226
 227         return $self->{_resultset};
 228     }
 229     else {
 230         return Koha::Database->new()->schema()->resultset( $self->_type() );
 231     }
 232 }
 233
 234 =head3 columns
 235
 236 my @columns = Koha::Objects->columns
 237
 238 Return the table columns
 239
 240 =cut
 241
 242 sub columns {
 243     my ( $class ) = @_;
 244     return Koha::Database->new->schema->resultset( $class->_type )->result_source->columns;
 245 }
 246
 247 =head3 AUTOLOAD
 248
 249 The autoload method is used call DBIx::Class method on a resultset.
 250
 251 Important: If you plan to use one of the DBIx::Class methods you must provide
 252 relevant tests in t/db_dependent/Koha/Objects.t
 253 Currently count, pager, reset and update are covered.
 254
 255 =cut
 256
 257 sub AUTOLOAD {
 258     my ( $self, @params ) = @_;
 259
 260     my $method = our $AUTOLOAD;
 261     $method =~ s/.*:://;
 262
 263     my $r = eval { $self->_resultset->$method(@params) };
 264     if ( $@ ) {
 265         carp "No method $method found for " . ref($self) . " " . $@;
 266         return
 267     }
 268     return $r;
 269 }
 270
 271 =head3 _type
 272
 273 The _type method must be set for all child classes.
 274 The value returned by it should be the DBIC resultset name.
 275 For example, for holds, _type should return 'Reserve'.
 276
 277 =cut
 278
 279 sub _type { }
 280
 281 =head3 object_class
 282
 283 This method must be set for all child classes.
 284 The value returned by it should be the name of the Koha
 285 object class that is returned by this class.
 286 For example, for holds, object_class should return 'Koha::Hold'.
 287
 288 =cut
 289
 290 sub object_class { }
 291
 292 sub DESTROY { }
 293
 294 =head1 AUTHOR
 295
 296 Kyle M Hall <kyle@bywatersolutions.com>
 297
 298 =cut
 299
 300 1;