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;
28 use Koha::DateUtils qw( dt_from_string );
32 Koha::Objects - Koha Object set base class
37 my @objects = Koha::Objects->search({ borrowernumber => $borrowernumber});
41 This class must be subclassed.
49 =head3 Koha::Objects->new();
51 my $object = Koha::Objects->new();
59 bless( $self, $class );
62 =head3 Koha::Objects->_new_from_dbic();
64 my $object = Koha::Objects->_new_from_dbic( $resultset );
69 my ( $class, $resultset ) = @_;
70 my $self = { _resultset => $resultset };
72 bless( $self, $class );
75 =head3 Koha::Objects->find();
77 Similar to DBIx::Class::ResultSet->find this method accepts:
78 \%columns_values | @pk_values, { key => $unique_constraint, %attrs }?
79 Strictly speaking, columns_values should only refer to columns under an
82 It returns undef if no results were found
84 my $object = Koha::Objects->find( { col1 => $val1, col2 => $val2 } );
85 my $object = Koha::Objects->find( $id );
86 my $object = Koha::Objects->find( $idpart1, $idpart2, $attrs ); # composite PK
91 my ( $self, @pars ) = @_;
95 unless (!@pars || none { defined($_) } @pars) {
96 my $result = $self->_resultset()->find(@pars);
98 $object = $self->object_class()->_new_from_dbic($result);
105 =head3 Koha::Objects->find_or_create();
107 my $object = Koha::Objects->find_or_create( $attrs );
112 my ( $self, $params ) = @_;
114 my $result = $self->_resultset->find_or_create($params);
116 return unless $result;
118 my $object = $self->object_class->_new_from_dbic($result);
126 my @objects = Koha::Objects->search([$params, $attributes]);
128 my $objects = Koha::Objects->search([$params, $attributes]);
129 while (my $object = $objects->next) {
133 This B<instantiates> the I<Koha::Objects> class, and generates a resultset
134 based on the query I<$params> and I<$attributes> that are passed (like in DBIC).
136 In B<list context> it returns an array of I<Koha::Object> objects.
137 In B<scalar context> it returns an iterator.
142 my ( $self, $params, $attributes ) = @_;
145 my @dbic_rows = $self->_resultset()->search($params, $attributes);
147 return $self->_wrap(@dbic_rows);
151 my $class = ref($self) ? ref($self) : $self;
152 my $rs = $self->_resultset()->search($params, $attributes);
154 return $class->_new_from_dbic($rs);
158 =head3 search_related
160 my @objects = Koha::Objects->search_related( $rel_name, $cond?, \%attrs? );
161 my $objects = Koha::Objects->search_related( $rel_name, $cond?, \%attrs? );
163 Searches the specified relationship, optionally specifying a condition and attributes for matching records.
168 my ( $self, $rel_name, @params ) = @_;
170 return if !$rel_name;
172 my @dbic_rows = $self->_resultset()->search_related($rel_name, @params);
173 return if !@dbic_rows;
174 my $object_class = _get_objects_class( $dbic_rows[0]->result_class );
176 eval "require $object_class";
177 return _wrap( $object_class, @dbic_rows );
180 my $rs = $self->_resultset()->search_related($rel_name, @params);
182 my $object_class = _get_objects_class( $rs->result_class );
184 eval "require $object_class";
185 return _new_from_dbic( $object_class, $rs );
196 if ( Class::Inspector->function_exists( $self->object_class, 'delete' ) ) {
198 $self->_resultset->result_source->schema->txn_do( sub {
199 $self->reset; # If we iterated already over the set
200 while ( my $o = $self->next ) {
205 return $objects_deleted;
208 return $self->_resultset->delete;
213 my $objects = Koha::Objects->new; # or Koha::Objects->search
214 $objects->update( $fields, [ { no_triggers => 0/1 } ] );
216 This method overloads the DBIC inherited one so if code-level triggers exist
217 (through the use of an overloaded I<update> or I<store> method in the Koha::Object
218 based class) those are called in a loop on the resultset.
220 If B<no_triggers> is passed and I<true>, then the DBIC update method is called
221 directly. This feature is important for performance, in cases where no code-level
222 triggers should be triggered. The developer will explicitly ask for this and QA should
223 catch wrong uses as well.
228 my ($self, $fields, $options) = @_;
230 Koha::Exceptions::Object::NotInstantiated->throw(
235 my $no_triggers = $options->{no_triggers};
239 && ( Class::Inspector->function_exists( $self->object_class, 'update' )
240 or Class::Inspector->function_exists( $self->object_class, 'store' ) )
244 $self->_resultset->result_source->schema->txn_do( sub {
245 while ( my $o = $self->next ) {
250 return $objects_updated;
253 return $self->_resultset->update($fields);
256 =head3 filter_by_last_update
258 my $filtered_objects = $objects->filter_by_last_update
260 days exclusive by default (will be inclusive if days_inclusive is passed and set)
266 sub filter_by_last_update {
267 my ( $self, $params ) = @_;
268 my $timestamp_column_name = $params->{timestamp_column_name} || 'timestamp';
269 my $days_inclusive = $params->{days_inclusive} || 0;
271 Koha::Exceptions::MissingParameter->throw(
272 "Missing mandatory parameter: days or from or to")
273 unless exists $params->{days}
274 or exists $params->{from}
275 or exists $params->{to};
277 my $dtf = Koha::Database->new->schema->storage->datetime_parser;
278 if ( exists $params->{days} ) {
279 my $dt = Koha::DateUtils::dt_from_string();
280 my $operator = $days_inclusive ? '<=' : '<';
281 $conditions->{$operator} = $dtf->format_date( $dt->subtract( days => $params->{days} ) );
283 if ( exists $params->{from} ) {
284 my $from = ref($params->{from}) ? $params->{from} : dt_from_string($params->{from});
285 $conditions->{'>='} = $dtf->format_date( $from );
287 if ( exists $params->{to} ) {
288 my $to = ref($params->{to}) ? $params->{to} : dt_from_string($params->{to});
289 $conditions->{'<='} = $dtf->format_date( $to );
292 return $self->search(
294 $timestamp_column_name => $conditions
301 my $object = Koha::Objects->search({}, { rows => 1 })->single
303 Returns one and only one object that is part of this set.
304 Returns undef if there are no objects found.
306 This is optimal as it will grab the first returned result without instantiating
310 http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class/Manual/Cookbook.pod#Retrieve_one_and_only_one_row_from_a_resultset
317 my $single = $self->_resultset()->single;
318 return unless $single;
320 return $self->object_class()->_new_from_dbic($single);
323 =head3 Koha::Objects->next();
325 my $object = Koha::Objects->next();
327 Returns the next object that is part of this set.
328 Returns undef if there are no more objects to return.
335 my $result = $self->_resultset()->next();
336 return unless $result;
338 my $object = $self->object_class()->_new_from_dbic( $result );
343 =head3 Koha::Objects->last;
345 my $object = Koha::Objects->last;
347 Returns the last object that is part of this set.
348 Returns undef if there are no object to return.
355 my $count = $self->_resultset->count;
356 return unless $count;
358 my ( $result ) = $self->_resultset->slice($count - 1, $count - 1);
360 my $object = $self->object_class()->_new_from_dbic( $result );
367 my $empty_rs = Koha::Objects->new->empty;
369 Sets the resultset empty. This is handy for consistency on method returns
370 (e.g. if we know in advance we won't have results but want to keep returning
378 Koha::Exceptions::Object::NotInstantiated->throw(
383 $self = $self->search(\'0 = 1');
384 $self->_resultset()->set_cache([]);
389 =head3 Koha::Objects->reset();
391 Koha::Objects->reset();
393 resets iteration so the next call to next() will start agein
394 with the first object in a set.
401 $self->_resultset()->reset();
406 =head3 Koha::Objects->as_list();
408 Koha::Objects->as_list();
410 Returns an arrayref of the objects in this set.
417 my @dbic_rows = $self->_resultset()->all();
419 my @objects = $self->_wrap(@dbic_rows);
421 return wantarray ? @objects : \@objects;
424 =head3 Koha::Objects->unblessed
426 Returns an unblessed representation of objects.
433 return [ map { $_->unblessed } $self->as_list ];
436 =head3 Koha::Objects->get_column
438 Return all the values of this set for a given column
443 my ($self, $column_name) = @_;
444 return $self->_resultset->get_column( $column_name )->all;
447 =head3 Koha::Objects->TO_JSON
449 Returns an unblessed representation of objects, suitable for JSON output.
456 return [ map { $_->TO_JSON } $self->as_list ];
459 =head3 Koha::Objects->to_api
461 Returns a representation of the objects, suitable for API output .
466 my ($self, $params) = @_;
468 return [ map { $_->to_api($params) } $self->as_list ];
471 =head3 attributes_from_api
473 my $attributes = $objects->attributes_from_api( $api_attributes );
475 Translates attributes from the API to DBIC
479 sub attributes_from_api {
480 my ( $self, $attributes ) = @_;
482 $self->{_singular_object} ||= $self->object_class->new();
483 return $self->{_singular_object}->attributes_from_api( $attributes );
486 =head3 from_api_mapping
488 my $mapped_attributes_hash = $objects->from_api_mapping;
490 Attributes map from the API to DBIC
494 sub from_api_mapping {
497 $self->{_singular_object} ||= $self->object_class->new();
498 return $self->{_singular_object}->from_api_mapping;
501 =head3 prefetch_whitelist
503 my $whitelist = $object->prefetch_whitelist()
505 Returns a hash of prefetchable subs and the type it returns
509 sub prefetch_whitelist {
512 $self->{_singular_object} ||= $self->object_class->new();
514 $self->{_singular_object}->prefetch_whitelist;
517 =head3 Koha::Objects->_wrap
519 wraps the DBIC object in a corresponding Koha object
524 my ( $self, @dbic_rows ) = @_;
526 my @objects = map { $self->object_class->_new_from_dbic( $_ ) } @dbic_rows;
531 =head3 Koha::Objects->_resultset
533 Returns the internal resultset or creates it if undefined
541 $self->{_resultset} ||=
542 Koha::Database->new()->schema()->resultset( $self->_type() );
544 return $self->{_resultset};
547 return Koha::Database->new()->schema()->resultset( $self->_type() );
551 sub _get_objects_class {
555 if( $type->can('koha_objects_class') ) {
556 return $type->koha_objects_class;
558 $type =~ s|Schema::Result::||;
564 my @columns = Koha::Objects->columns
566 Return the table columns
572 return Koha::Database->new->schema->resultset( $class->_type )->result_source->columns;
577 The autoload method is used call DBIx::Class method on a resultset.
579 Important: If you plan to use one of the DBIx::Class methods you must provide
580 relevant tests in t/db_dependent/Koha/Objects.t
581 Currently count, is_paged, pager, result_class, single and slice are covered.
586 my ( $self, @params ) = @_;
588 my @known_methods = qw( count is_paged pager result_class single slice );
589 my $method = our $AUTOLOAD;
593 unless ( grep { $_ eq $method } @known_methods ) {
594 my $class = ref($self) ? ref($self) : $self;
595 Koha::Exceptions::Object::MethodNotCoveredByTests->throw(
596 error => sprintf("The method %s->%s is not covered by tests!", $class, $method),
601 my $r = eval { $self->_resultset->$method(@params) };
603 carp "No method $method found for " . ref($self) . " " . $@;
611 The _type method must be set for all child classes.
612 The value returned by it should be the DBIC resultset name.
613 For example, for holds, _type should return 'Reserve'.
621 This method must be set for all child classes.
622 The value returned by it should be the name of the Koha
623 object class that is returned by this class.
624 For example, for holds, object_class should return 'Koha::Hold'.
634 Kyle M Hall <kyle@bywatersolutions.com>