3 # Copyright ByWater Solutions 2014
5 # This file is part of Koha.
7 # Koha is free software; you can redistribute it and/or modify it
8 # under the terms of the GNU General Public License as published by
9 # the Free Software Foundation; either version 3 of the License, or
10 # (at your option) any later version.
12 # Koha is distributed in the hope that it will be useful, but
13 # WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
17 # You should have received a copy of the GNU General Public License
18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
23 use List::MoreUtils qw( none );
29 Koha::Objects - Koha Object set base class
34 my @objects = Koha::Objects->search({ borrowernumber => $borrowernumber});
38 This class must be subclassed.
46 =head3 Koha::Objects->new();
48 my $object = Koha::Objects->new();
56 bless( $self, $class );
59 =head3 Koha::Objects->_new_from_dbic();
61 my $object = Koha::Objects->_new_from_dbic( $resultset );
66 my ( $class, $resultset ) = @_;
67 my $self = { _resultset => $resultset };
69 bless( $self, $class );
72 =head3 Koha::Objects->find();
74 Similar to DBIx::Class::ResultSet->find this method accepts:
75 \%columns_values | @pk_values, { key => $unique_constraint, %attrs }?
76 Strictly speaking, columns_values should only refer to columns under an
79 It returns undef if no results were found
81 my $object = Koha::Objects->find( { col1 => $val1, col2 => $val2 } );
82 my $object = Koha::Objects->find( $id );
83 my $object = Koha::Objects->find( $idpart1, $idpart2, $attrs ); # composite PK
88 my ( $self, @pars ) = @_;
92 unless (!@pars || none { defined($_) } @pars) {
93 my $result = $self->_resultset()->find(@pars);
95 $object = $self->object_class()->_new_from_dbic($result);
102 =head3 Koha::Objects->find_or_create();
104 my $object = Koha::Objects->find_or_create( $attrs );
109 my ( $self, $params ) = @_;
111 my $result = $self->_resultset->find_or_create($params);
113 return unless $result;
115 my $object = $self->object_class->_new_from_dbic($result);
120 =head3 Koha::Objects->search();
122 my @objects = Koha::Objects->search($params);
127 my ( $self, $params, $attributes ) = @_;
130 my @dbic_rows = $self->_resultset()->search($params, $attributes);
132 return $self->_wrap(@dbic_rows);
136 my $class = ref($self) ? ref($self) : $self;
137 my $rs = $self->_resultset()->search($params, $attributes);
139 return $class->_new_from_dbic($rs);
143 =head3 search_related
145 my @objects = Koha::Objects->search_related( $rel_name, $cond?, \%attrs? );
146 my $objects = Koha::Objects->search_related( $rel_name, $cond?, \%attrs? );
148 Searches the specified relationship, optionally specifying a condition and attributes for matching records.
153 my ( $self, $rel_name, @params ) = @_;
155 return if !$rel_name;
157 my @dbic_rows = $self->_resultset()->search_related($rel_name, @params);
158 return if !@dbic_rows;
159 my $object_class = _get_objects_class( $dbic_rows[0]->result_class );
161 eval "require $object_class";
162 return _wrap( $object_class, @dbic_rows );
165 my $rs = $self->_resultset()->search_related($rel_name, @params);
167 my $object_class = _get_objects_class( $rs->result_class );
169 eval "require $object_class";
170 return _new_from_dbic( $object_class, $rs );
176 my $object = Koha::Objects->search({}, { rows => 1 })->single
178 Returns one and only one object that is part of this set.
179 Returns undef if there are no objects found.
181 This is optimal as it will grab the first returned result without instantiating
185 http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class/Manual/Cookbook.pod#Retrieve_one_and_only_one_row_from_a_resultset
192 my $single = $self->_resultset()->single;
193 return unless $single;
195 return $self->object_class()->_new_from_dbic($single);
198 =head3 Koha::Objects->next();
200 my $object = Koha::Objects->next();
202 Returns the next object that is part of this set.
203 Returns undef if there are no more objects to return.
210 my $result = $self->_resultset()->next();
211 return unless $result;
213 my $object = $self->object_class()->_new_from_dbic( $result );
218 =head3 Koha::Objects->last;
220 my $object = Koha::Objects->last;
222 Returns the last object that is part of this set.
223 Returns undef if there are no object to return.
230 my $count = $self->_resultset->count;
231 return unless $count;
233 my ( $result ) = $self->_resultset->slice($count - 1, $count - 1);
235 my $object = $self->object_class()->_new_from_dbic( $result );
242 my $empty_rs = Koha::Objects->new->empty;
244 Sets the resultset empty. This is handy for consistency on method returns
245 (e.g. if we know in advance we won't have results but want to keep returning
253 $self->_resultset()->set_cache([]);
258 =head3 Koha::Objects->reset();
260 Koha::Objects->reset();
262 resets iteration so the next call to next() will start agein
263 with the first object in a set.
270 $self->_resultset()->reset();
275 =head3 Koha::Objects->as_list();
277 Koha::Objects->as_list();
279 Returns an arrayref of the objects in this set.
286 my @dbic_rows = $self->_resultset()->all();
288 my @objects = $self->_wrap(@dbic_rows);
290 return wantarray ? @objects : \@objects;
293 =head3 Koha::Objects->unblessed
295 Returns an unblessed representation of objects.
302 return [ map { $_->unblessed } $self->as_list ];
305 =head3 Koha::Objects->get_column
307 Return all the values of this set for a given column
312 my ($self, $column_name) = @_;
313 return $self->_resultset->get_column( $column_name )->all;
316 =head3 Koha::Objects->TO_JSON
318 Returns an unblessed representation of objects, suitable for JSON output.
325 return [ map { $_->TO_JSON } $self->as_list ];
328 =head3 Koha::Objects->to_api
330 Returns a representation of the objects, suitable for API output .
335 my ($self, $params) = @_;
337 return [ map { $_->to_api($params) } $self->as_list ];
340 =head3 attributes_from_api
342 my $attributes = $objects->attributes_from_api( $api_attributes );
344 Translates attributes from the API to DBIC
348 sub attributes_from_api {
349 my ( $self, $attributes ) = @_;
351 $self->{_singular_object} ||= $self->object_class->new();
352 return $self->{_singular_object}->attributes_from_api( $attributes );
355 =head3 from_api_mapping
357 my $mapped_attributes_hash = $objects->from_api_mapping;
359 Attributes map from the API to DBIC
363 sub from_api_mapping {
366 $self->{_singular_object} ||= $self->object_class->new();
367 return $self->{_singular_object}->from_api_mapping;
370 =head3 prefetch_whitelist
372 my $whitelist = $object->prefetch_whitelist()
374 Returns a hash of prefetchable subs and the type it returns
378 sub prefetch_whitelist {
381 $self->{_singular_object} ||= $self->object_class->new();
383 $self->{_singular_object}->prefetch_whitelist;
386 =head3 Koha::Objects->_wrap
388 wraps the DBIC object in a corresponding Koha object
393 my ( $self, @dbic_rows ) = @_;
395 my @objects = map { $self->object_class->_new_from_dbic( $_ ) } @dbic_rows;
400 =head3 Koha::Objects->_resultset
402 Returns the internal resultset or creates it if undefined
410 $self->{_resultset} ||=
411 Koha::Database->new()->schema()->resultset( $self->_type() );
413 return $self->{_resultset};
416 return Koha::Database->new()->schema()->resultset( $self->_type() );
420 sub _get_objects_class {
424 if( $type->can('koha_objects_class') ) {
425 return $type->koha_objects_class;
427 $type =~ s|Schema::Result::||;
433 my @columns = Koha::Objects->columns
435 Return the table columns
441 return Koha::Database->new->schema->resultset( $class->_type )->result_source->columns;
446 The autoload method is used call DBIx::Class method on a resultset.
448 Important: If you plan to use one of the DBIx::Class methods you must provide
449 relevant tests in t/db_dependent/Koha/Objects.t
450 Currently count, pager, update and delete are covered.
455 my ( $self, @params ) = @_;
457 my @known_methods = qw( count is_paged pager update delete result_class single slice );
458 my $method = our $AUTOLOAD;
462 unless ( grep { $_ eq $method } @known_methods ) {
463 my $class = ref($self) ? ref($self) : $self;
464 Koha::Exceptions::Object::MethodNotCoveredByTests->throw(
465 error => sprintf("The method %s->%s is not covered by tests!", $class, $method),
470 my $r = eval { $self->_resultset->$method(@params) };
472 carp "No method $method found for " . ref($self) . " " . $@;
480 The _type method must be set for all child classes.
481 The value returned by it should be the DBIC resultset name.
482 For example, for holds, _type should return 'Reserve'.
490 This method must be set for all child classes.
491 The value returned by it should be the name of the Koha
492 object class that is returned by this class.
493 For example, for holds, object_class should return 'Koha::Hold'.
503 Kyle M Hall <kyle@bywatersolutions.com>