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 );
27 use Koha::Exceptions::Object;
31 Koha::Objects - Koha Object set base class
36 my @objects = Koha::Objects->search({ borrowernumber => $borrowernumber});
40 This class must be subclassed.
48 =head3 Koha::Objects->new();
50 my $object = Koha::Objects->new();
58 bless( $self, $class );
61 =head3 Koha::Objects->_new_from_dbic();
63 my $object = Koha::Objects->_new_from_dbic( $resultset );
68 my ( $class, $resultset ) = @_;
69 my $self = { _resultset => $resultset };
71 bless( $self, $class );
74 =head3 Koha::Objects->find();
76 Similar to DBIx::Class::ResultSet->find this method accepts:
77 \%columns_values | @pk_values, { key => $unique_constraint, %attrs }?
78 Strictly speaking, columns_values should only refer to columns under an
81 It returns undef if no results were found
83 my $object = Koha::Objects->find( { col1 => $val1, col2 => $val2 } );
84 my $object = Koha::Objects->find( $id );
85 my $object = Koha::Objects->find( $idpart1, $idpart2, $attrs ); # composite PK
90 my ( $self, @pars ) = @_;
94 unless (!@pars || none { defined($_) } @pars) {
95 my $result = $self->_resultset()->find(@pars);
97 $object = $self->object_class()->_new_from_dbic($result);
104 =head3 Koha::Objects->find_or_create();
106 my $object = Koha::Objects->find_or_create( $attrs );
111 my ( $self, $params ) = @_;
113 my $result = $self->_resultset->find_or_create($params);
115 return unless $result;
117 my $object = $self->object_class->_new_from_dbic($result);
125 my @objects = Koha::Objects->search([$params, $attributes]);
127 my $objects = Koha::Objects->search([$params, $attributes]);
128 while (my $object = $objects->next) {
132 This B<instantiates> the I<Koha::Objects> class, and generates a resultset
133 based on the query I<$params> and I<$attributes> that are passed (like in DBIC).
135 In B<list context> it returns an array of I<Koha::Object> objects.
136 In B<scalar context> it returns an iterator.
141 my ( $self, $params, $attributes ) = @_;
144 my @dbic_rows = $self->_resultset()->search($params, $attributes);
146 return $self->_wrap(@dbic_rows);
150 my $class = ref($self) ? ref($self) : $self;
151 my $rs = $self->_resultset()->search($params, $attributes);
153 return $class->_new_from_dbic($rs);
157 =head3 search_related
159 my @objects = Koha::Objects->search_related( $rel_name, $cond?, \%attrs? );
160 my $objects = Koha::Objects->search_related( $rel_name, $cond?, \%attrs? );
162 Searches the specified relationship, optionally specifying a condition and attributes for matching records.
167 my ( $self, $rel_name, @params ) = @_;
169 return if !$rel_name;
171 my @dbic_rows = $self->_resultset()->search_related($rel_name, @params);
172 return if !@dbic_rows;
173 my $object_class = _get_objects_class( $dbic_rows[0]->result_class );
175 eval "require $object_class";
176 return _wrap( $object_class, @dbic_rows );
179 my $rs = $self->_resultset()->search_related($rel_name, @params);
181 my $object_class = _get_objects_class( $rs->result_class );
183 eval "require $object_class";
184 return _new_from_dbic( $object_class, $rs );
195 if ( Class::Inspector->function_exists( $self->object_class, 'delete' ) ) {
197 $self->_resultset->result_source->schema->txn_do( sub {
198 $self->reset; # If we iterated already over the set
199 while ( my $o = $self->next ) {
204 return $objects_deleted;
207 return $self->_resultset->delete;
212 my $objects = Koha::Objects->new; # or Koha::Objects->search
213 $objects->update( $fields, [ { no_triggers => 0/1 } ] );
215 This method overloads the DBIC inherited one so if code-level triggers exist
216 (through the use of an overloaded I<update> or I<store> method in the Koha::Object
217 based class) those are called in a loop on the resultset.
219 If B<no_triggers> is passed and I<true>, then the DBIC update method is called
220 directly. This feature is important for performance, in cases where no code-level
221 triggers should be triggered. The developer will explicitly ask for this and QA should
222 catch wrong uses as well.
227 my ($self, $fields, $options) = @_;
229 Koha::Exceptions::Object::NotInstantiated->throw(
234 my $no_triggers = $options->{no_triggers};
238 && ( Class::Inspector->function_exists( $self->object_class, 'update' )
239 or Class::Inspector->function_exists( $self->object_class, 'store' ) )
243 $self->_resultset->result_source->schema->txn_do( sub {
244 while ( my $o = $self->next ) {
249 return $objects_updated;
252 return $self->_resultset->update($fields);
255 sub filter_by_last_update {
256 my ( $self, $params ) = @_;
257 my $timestamp_column_name = $params->{timestamp_column_name} || 'timestamp';
258 return $self->_resultset->search(
260 $timestamp_column_name => {
262 [ \'DATE_SUB(CURDATE(), INTERVAL ? DAY)', $params->{days} ]
270 my $object = Koha::Objects->search({}, { rows => 1 })->single
272 Returns one and only one object that is part of this set.
273 Returns undef if there are no objects found.
275 This is optimal as it will grab the first returned result without instantiating
279 http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class/Manual/Cookbook.pod#Retrieve_one_and_only_one_row_from_a_resultset
286 my $single = $self->_resultset()->single;
287 return unless $single;
289 return $self->object_class()->_new_from_dbic($single);
292 =head3 Koha::Objects->next();
294 my $object = Koha::Objects->next();
296 Returns the next object that is part of this set.
297 Returns undef if there are no more objects to return.
304 my $result = $self->_resultset()->next();
305 return unless $result;
307 my $object = $self->object_class()->_new_from_dbic( $result );
312 =head3 Koha::Objects->last;
314 my $object = Koha::Objects->last;
316 Returns the last object that is part of this set.
317 Returns undef if there are no object to return.
324 my $count = $self->_resultset->count;
325 return unless $count;
327 my ( $result ) = $self->_resultset->slice($count - 1, $count - 1);
329 my $object = $self->object_class()->_new_from_dbic( $result );
336 my $empty_rs = Koha::Objects->new->empty;
338 Sets the resultset empty. This is handy for consistency on method returns
339 (e.g. if we know in advance we won't have results but want to keep returning
347 Koha::Exceptions::Object::NotInstantiated->throw(
352 $self->_resultset()->set_cache([]);
357 =head3 Koha::Objects->reset();
359 Koha::Objects->reset();
361 resets iteration so the next call to next() will start agein
362 with the first object in a set.
369 $self->_resultset()->reset();
374 =head3 Koha::Objects->as_list();
376 Koha::Objects->as_list();
378 Returns an arrayref of the objects in this set.
385 my @dbic_rows = $self->_resultset()->all();
387 my @objects = $self->_wrap(@dbic_rows);
389 return wantarray ? @objects : \@objects;
392 =head3 Koha::Objects->unblessed
394 Returns an unblessed representation of objects.
401 return [ map { $_->unblessed } $self->as_list ];
404 =head3 Koha::Objects->get_column
406 Return all the values of this set for a given column
411 my ($self, $column_name) = @_;
412 return $self->_resultset->get_column( $column_name )->all;
415 =head3 Koha::Objects->TO_JSON
417 Returns an unblessed representation of objects, suitable for JSON output.
424 return [ map { $_->TO_JSON } $self->as_list ];
427 =head3 Koha::Objects->to_api
429 Returns a representation of the objects, suitable for API output .
434 my ($self, $params) = @_;
436 return [ map { $_->to_api($params) } $self->as_list ];
439 =head3 attributes_from_api
441 my $attributes = $objects->attributes_from_api( $api_attributes );
443 Translates attributes from the API to DBIC
447 sub attributes_from_api {
448 my ( $self, $attributes ) = @_;
450 $self->{_singular_object} ||= $self->object_class->new();
451 return $self->{_singular_object}->attributes_from_api( $attributes );
454 =head3 from_api_mapping
456 my $mapped_attributes_hash = $objects->from_api_mapping;
458 Attributes map from the API to DBIC
462 sub from_api_mapping {
465 $self->{_singular_object} ||= $self->object_class->new();
466 return $self->{_singular_object}->from_api_mapping;
469 =head3 prefetch_whitelist
471 my $whitelist = $object->prefetch_whitelist()
473 Returns a hash of prefetchable subs and the type it returns
477 sub prefetch_whitelist {
480 $self->{_singular_object} ||= $self->object_class->new();
482 $self->{_singular_object}->prefetch_whitelist;
485 =head3 Koha::Objects->_wrap
487 wraps the DBIC object in a corresponding Koha object
492 my ( $self, @dbic_rows ) = @_;
494 my @objects = map { $self->object_class->_new_from_dbic( $_ ) } @dbic_rows;
499 =head3 Koha::Objects->_resultset
501 Returns the internal resultset or creates it if undefined
509 $self->{_resultset} ||=
510 Koha::Database->new()->schema()->resultset( $self->_type() );
512 return $self->{_resultset};
515 return Koha::Database->new()->schema()->resultset( $self->_type() );
519 sub _get_objects_class {
523 if( $type->can('koha_objects_class') ) {
524 return $type->koha_objects_class;
526 $type =~ s|Schema::Result::||;
532 my @columns = Koha::Objects->columns
534 Return the table columns
540 return Koha::Database->new->schema->resultset( $class->_type )->result_source->columns;
545 The autoload method is used call DBIx::Class method on a resultset.
547 Important: If you plan to use one of the DBIx::Class methods you must provide
548 relevant tests in t/db_dependent/Koha/Objects.t
549 Currently count, is_paged, pager, result_class, single and slice are covered.
554 my ( $self, @params ) = @_;
556 my @known_methods = qw( count is_paged pager result_class single slice );
557 my $method = our $AUTOLOAD;
561 unless ( grep { $_ eq $method } @known_methods ) {
562 my $class = ref($self) ? ref($self) : $self;
563 Koha::Exceptions::Object::MethodNotCoveredByTests->throw(
564 error => sprintf("The method %s->%s is not covered by tests!", $class, $method),
569 my $r = eval { $self->_resultset->$method(@params) };
571 carp "No method $method found for " . ref($self) . " " . $@;
579 The _type method must be set for all child classes.
580 The value returned by it should be the DBIC resultset name.
581 For example, for holds, _type should return 'Reserve'.
589 This method must be set for all child classes.
590 The value returned by it should be the name of the Koha
591 object class that is returned by this class.
592 For example, for holds, object_class should return 'Koha::Hold'.
602 Kyle M Hall <kyle@bywatersolutions.com>