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->count();
 134
 135 my @objects = Koha::Objects->count($params);
 136
 137 =cut
 138
 139 sub count {
 140     my ( $self, $params ) = @_;
 141
 142     return $self->_resultset()->count($params);
 143 }
 144
 145 =head3 Koha::Objects->pager();
 146
 147 my $pager = Koha::Objects->pager;
 148
 149 =cut
 150
 151 sub pager {
 152     my ( $self ) = @_;
 153     return $self->_resultset->pager;
 154 }
 155
 156 =head3 Koha::Objects->next();
 157
 158 my $object = Koha::Objects->next();
 159
 160 Returns the next object that is part of this set.
 161 Returns undef if there are no more objects to return.
 162
 163 =cut
 164
 165 sub next {
 166     my ( $self ) = @_;
 167
 168     my $result = $self->_resultset()->next();
 169     return unless $result;
 170
 171     my $object = $self->object_class()->_new_from_dbic( $result );
 172
 173     return $object;
 174 }
 175
 176 =head3 Koha::Objects->reset();
 177
 178 Koha::Objects->reset();
 179
 180 resets iteration so the next call to next() will start agein
 181 with the first object in a set.
 182
 183 =cut
 184
 185 sub reset {
 186     my ( $self ) = @_;
 187
 188     $self->_resultset()->reset();
 189
 190     return $self;
 191 }
 192
 193 =head3 Koha::Objects->as_list();
 194
 195 Koha::Objects->as_list();
 196
 197 Returns an arrayref of the objects in this set.
 198
 199 =cut
 200
 201 sub as_list {
 202     my ( $self ) = @_;
 203
 204     my @dbic_rows = $self->_resultset()->all();
 205
 206     my @objects = $self->_wrap(@dbic_rows);
 207
 208     return wantarray ? @objects : \@objects;
 209 }
 210
 211 =head3 Koha::Objects->unblessed
 212
 213 Returns an unblessed representation of objects.
 214
 215 =cut
 216
 217 sub unblessed {
 218     my ($self) = @_;
 219
 220     return [ map { $_->unblessed } $self->as_list ];
 221 }
 222
 223 =head3 Koha::Objects->_wrap
 224
 225 wraps the DBIC object in a corresponding Koha object
 226
 227 =cut
 228
 229 sub _wrap {
 230     my ( $self, @dbic_rows ) = @_;
 231
 232     my @objects = map { $self->object_class()->_new_from_dbic( $_ ) } @dbic_rows;
 233
 234     return @objects;
 235 }
 236
 237 =head3 update
 238
 239     Koha::Objects->search({ $key => $value})->update( \%values );
 240
 241 Sets the specified columns in the resultset to the supplied values in a single query.
 242
 243 =cut
 244
 245 sub update {
 246     my ( $self, $params ) = @_;
 247     return $self->_resultset()->update($params);
 248 }
 249
 250 =head3 Koha::Objects->_resultset
 251
 252 Returns the internal resultset or creates it if undefined
 253
 254 =cut
 255
 256 sub _resultset {
 257     my ($self) = @_;
 258
 259     if ( ref($self) ) {
 260         $self->{_resultset} ||=
 261           Koha::Database->new()->schema()->resultset( $self->_type() );
 262
 263         return $self->{_resultset};
 264     }
 265     else {
 266         return Koha::Database->new()->schema()->resultset( $self->_type() );
 267     }
 268 }
 269
 270 =head3 columns
 271
 272 my @columns = Koha::Objects->columns
 273
 274 Return the table columns
 275
 276 =cut
 277
 278 sub columns {
 279     my ( $class ) = @_;
 280     return Koha::Database->new->schema->resultset( $class->_type )->result_source->columns;
 281 }
 282
 283 =head3 AUTOLOAD
 284
 285 The autoload method is used call DBIx::Class method on a resultset.
 286
 287 Important: If you plan to use one of the DBIx::Class methods you must provide
 288 relevant tests in t/db_dependent/Koha/Objects.t
 289 Currently count, pager, reset and update are covered.
 290
 291 =cut
 292
 293 sub AUTOLOAD {
 294     my ( $self, @params ) = @_;
 295
 296     my $method = our $AUTOLOAD;
 297     $method =~ s/.*:://;
 298
 299     my $r = eval { $self->_resultset->$method(@params) };
 300     if ( $@ ) {
 301         carp "No method $method found for " . ref($self) . " " . $@;
 302         return
 303     }
 304     return $r;
 305 }
 306
 307 =head3 _type
 308
 309 The _type method must be set for all child classes.
 310 The value returned by it should be the DBIC resultset name.
 311 For example, for holds, _type should return 'Reserve'.
 312
 313 =cut
 314
 315 sub _type { }
 316
 317 =head3 object_class
 318
 319 This method must be set for all child classes.
 320 The value returned by it should be the name of the Koha
 321 object class that is returned by this class.
 322 For example, for holds, object_class should return 'Koha::Hold'.
 323
 324 =cut
 325
 326 sub object_class { }
 327
 328 sub DESTROY { }
 329
 330 =head1 AUTHOR
 331
 332 Kyle M Hall <kyle@bywatersolutions.com>
 333
 334 =cut
 335
 336 1;