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 );
30 Koha::Objects - Koha Object set base class
35 my @objects = Koha::Objects->search({ borrowernumber => $borrowernumber});
39 This class must be subclassed.
47 =head3 Koha::Objects->new();
49 my $object = Koha::Objects->new();
57 bless( $self, $class );
60 =head3 Koha::Objects->_new_from_dbic();
62 my $object = Koha::Objects->_new_from_dbic( $resultset );
67 my ( $class, $resultset ) = @_;
68 my $self = { _resultset
=> $resultset };
70 bless( $self, $class );
73 =head3 Koha::Objects->find();
75 Similar to DBIx::Class::ResultSet->find this method accepts:
76 \%columns_values | @pk_values, { key => $unique_constraint, %attrs }?
77 Strictly speaking, columns_values should only refer to columns under an
80 It returns undef if no results were found
82 my $object = Koha::Objects->find( { col1 => $val1, col2 => $val2 } );
83 my $object = Koha::Objects->find( $id );
84 my $object = Koha::Objects->find( $idpart1, $idpart2, $attrs ); # composite PK
89 my ( $self, @pars ) = @_;
93 unless (!@pars || none
{ defined($_) } @pars) {
94 my $result = $self->_resultset()->find(@pars);
96 $object = $self->object_class()->_new_from_dbic($result);
103 =head3 Koha::Objects->find_or_create();
105 my $object = Koha::Objects->find_or_create( $attrs );
110 my ( $self, $params ) = @_;
112 my $result = $self->_resultset->find_or_create($params);
114 return unless $result;
116 my $object = $self->object_class->_new_from_dbic($result);
121 =head3 Koha::Objects->search();
123 my @objects = Koha::Objects->search($params);
128 my ( $self, $params, $attributes ) = @_;
131 my @dbic_rows = $self->_resultset()->search($params, $attributes);
133 return $self->_wrap(@dbic_rows);
137 my $class = ref($self) ?
ref($self) : $self;
138 my $rs = $self->_resultset()->search($params, $attributes);
140 return $class->_new_from_dbic($rs);
144 =head3 search_related
146 my @objects = Koha::Objects->search_related( $rel_name, $cond?, \%attrs? );
147 my $objects = Koha::Objects->search_related( $rel_name, $cond?, \%attrs? );
149 Searches the specified relationship, optionally specifying a condition and attributes for matching records.
154 my ( $self, $rel_name, @params ) = @_;
156 return if !$rel_name;
158 my @dbic_rows = $self->_resultset()->search_related($rel_name, @params);
159 return if !@dbic_rows;
160 my $object_class = _get_objects_class
( $dbic_rows[0]->result_class );
162 eval "require $object_class";
163 return _wrap
( $object_class, @dbic_rows );
166 my $rs = $self->_resultset()->search_related($rel_name, @params);
168 my $object_class = _get_objects_class
( $rs->result_class );
170 eval "require $object_class";
171 return _new_from_dbic
( $object_class, $rs );
182 if ( Class
::Inspector
->function_exists( $self->object_class, 'delete' ) ) {
184 $self->_resultset->result_source->schema->txn_do( sub {
185 $self->reset; # If we iterated already over the set
186 while ( my $o = $self->next ) {
191 return $objects_deleted;
194 return $self->_resultset->delete;
199 my $object = Koha::Objects->search({}, { rows => 1 })->single
201 Returns one and only one object that is part of this set.
202 Returns undef if there are no objects found.
204 This is optimal as it will grab the first returned result without instantiating
208 http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class/Manual/Cookbook.pod#Retrieve_one_and_only_one_row_from_a_resultset
215 my $single = $self->_resultset()->single;
216 return unless $single;
218 return $self->object_class()->_new_from_dbic($single);
221 =head3 Koha::Objects->next();
223 my $object = Koha::Objects->next();
225 Returns the next object that is part of this set.
226 Returns undef if there are no more objects to return.
233 my $result = $self->_resultset()->next();
234 return unless $result;
236 my $object = $self->object_class()->_new_from_dbic( $result );
241 =head3 Koha::Objects->last;
243 my $object = Koha::Objects->last;
245 Returns the last object that is part of this set.
246 Returns undef if there are no object to return.
253 my $count = $self->_resultset->count;
254 return unless $count;
256 my ( $result ) = $self->_resultset->slice($count - 1, $count - 1);
258 my $object = $self->object_class()->_new_from_dbic( $result );
265 my $empty_rs = Koha::Objects->new->empty;
267 Sets the resultset empty. This is handy for consistency on method returns
268 (e.g. if we know in advance we won't have results but want to keep returning
276 unless (ref($self)) {
280 $self->_resultset()->set_cache([]);
285 =head3 Koha::Objects->reset();
287 Koha::Objects->reset();
289 resets iteration so the next call to next() will start agein
290 with the first object in a set.
297 $self->_resultset()->reset();
302 =head3 Koha::Objects->as_list();
304 Koha::Objects->as_list();
306 Returns an arrayref of the objects in this set.
313 my @dbic_rows = $self->_resultset()->all();
315 my @objects = $self->_wrap(@dbic_rows);
317 return wantarray ?
@objects : \
@objects;
320 =head3 Koha::Objects->unblessed
322 Returns an unblessed representation of objects.
329 return [ map { $_->unblessed } $self->as_list ];
332 =head3 Koha::Objects->get_column
334 Return all the values of this set for a given column
339 my ($self, $column_name) = @_;
340 return $self->_resultset->get_column( $column_name )->all;
343 =head3 Koha::Objects->TO_JSON
345 Returns an unblessed representation of objects, suitable for JSON output.
352 return [ map { $_->TO_JSON } $self->as_list ];
355 =head3 Koha::Objects->to_api
357 Returns a representation of the objects, suitable for API output .
362 my ($self, $params) = @_;
364 return [ map { $_->to_api($params) } $self->as_list ];
367 =head3 attributes_from_api
369 my $attributes = $objects->attributes_from_api( $api_attributes );
371 Translates attributes from the API to DBIC
375 sub attributes_from_api
{
376 my ( $self, $attributes ) = @_;
378 $self->{_singular_object
} ||= $self->object_class->new();
379 return $self->{_singular_object
}->attributes_from_api( $attributes );
382 =head3 from_api_mapping
384 my $mapped_attributes_hash = $objects->from_api_mapping;
386 Attributes map from the API to DBIC
390 sub from_api_mapping
{
393 $self->{_singular_object
} ||= $self->object_class->new();
394 return $self->{_singular_object
}->from_api_mapping;
397 =head3 prefetch_whitelist
399 my $whitelist = $object->prefetch_whitelist()
401 Returns a hash of prefetchable subs and the type it returns
405 sub prefetch_whitelist
{
408 $self->{_singular_object
} ||= $self->object_class->new();
410 $self->{_singular_object
}->prefetch_whitelist;
413 =head3 Koha::Objects->_wrap
415 wraps the DBIC object in a corresponding Koha object
420 my ( $self, @dbic_rows ) = @_;
422 my @objects = map { $self->object_class->_new_from_dbic( $_ ) } @dbic_rows;
427 =head3 Koha::Objects->_resultset
429 Returns the internal resultset or creates it if undefined
437 $self->{_resultset
} ||=
438 Koha
::Database
->new()->schema()->resultset( $self->_type() );
440 return $self->{_resultset
};
443 return Koha
::Database
->new()->schema()->resultset( $self->_type() );
447 sub _get_objects_class
{
451 if( $type->can('koha_objects_class') ) {
452 return $type->koha_objects_class;
454 $type =~ s
|Schema
::Result
::||;
460 my @columns = Koha::Objects->columns
462 Return the table columns
468 return Koha
::Database
->new->schema->resultset( $class->_type )->result_source->columns;
473 The autoload method is used call DBIx::Class method on a resultset.
475 Important: If you plan to use one of the DBIx::Class methods you must provide
476 relevant tests in t/db_dependent/Koha/Objects.t
477 Currently count, is_paged, pager, update, result_class, single and slice are covered.
482 my ( $self, @params ) = @_;
484 my @known_methods = qw( count is_paged pager update result_class single slice );
485 my $method = our $AUTOLOAD;
489 unless ( grep { $_ eq $method } @known_methods ) {
490 my $class = ref($self) ?
ref($self) : $self;
491 Koha
::Exceptions
::Object
::MethodNotCoveredByTests
->throw(
492 error
=> sprintf("The method %s->%s is not covered by tests!", $class, $method),
497 my $r = eval { $self->_resultset->$method(@params) };
499 carp
"No method $method found for " . ref($self) . " " . $@
;
507 The _type method must be set for all child classes.
508 The value returned by it should be the DBIC resultset name.
509 For example, for holds, _type should return 'Reserve'.
517 This method must be set for all child classes.
518 The value returned by it should be the name of the Koha
519 object class that is returned by this class.
520 For example, for holds, object_class should return 'Koha::Hold'.
530 Kyle M Hall <kyle@bywatersolutions.com>