koha-dev.rot13.org Git - srvgit/blob - Koha/REST/Plugin/Query.pm

   1 package Koha::REST::Plugin::Query;
   2
   3 # This file is part of Koha.
   4 #
   5 # Koha is free software; you can redistribute it and/or modify it
   6 # under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 3 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # Koha is distributed in the hope that it will be useful, but
  11 # WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  17
  18 use Modern::Perl;
  19
  20 use Mojo::Base 'Mojolicious::Plugin';
  21 use List::MoreUtils qw(any);
  22 use Scalar::Util qw(reftype);
  23
  24 use Koha::Exceptions;
  25
  26 =head1 NAME
  27
  28 Koha::REST::Plugin::Query
  29
  30 =head1 API
  31
  32 =head2 Mojolicious::Plugin methods
  33
  34 =head3 register
  35
  36 =cut
  37
  38 sub register {
  39     my ( $self, $app ) = @_;
  40
  41 =head2 Helper methods
  42
  43 =head3 extract_reserved_params
  44
  45     my ( $filtered_params, $reserved_params ) = $c->extract_reserved_params($params);
  46
  47 Generates the DBIC query from the query parameters.
  48
  49 =cut
  50
  51     $app->helper(
  52         'extract_reserved_params' => sub {
  53             my ( $c, $params ) = @_;
  54
  55             my $reserved_params;
  56             my $filtered_params;
  57             my $path_params;
  58
  59             my $reserved_words = _reserved_words();
  60             my @query_param_names = keys %{$c->req->params->to_hash};
  61
  62             foreach my $param ( keys %{$params} ) {
  63                 if ( grep { $param eq $_ } @{$reserved_words} ) {
  64                     $reserved_params->{$param} = $params->{$param};
  65                 }
  66                 elsif ( grep { $param eq $_ } @query_param_names ) {
  67                     $filtered_params->{$param} = $params->{$param};
  68                 }
  69                 else {
  70                     $path_params->{$param} = $params->{$param};
  71                 }
  72             }
  73
  74             return ( $filtered_params, $reserved_params, $path_params );
  75         }
  76     );
  77
  78 =head3 dbic_merge_sorting
  79
  80     $attributes = $c->dbic_merge_sorting({ attributes => $attributes, params => $params });
  81
  82 Generates the DBIC order_by attributes based on I<$params>, and merges into I<$attributes>.
  83
  84 =cut
  85
  86     $app->helper(
  87         'dbic_merge_sorting' => sub {
  88             my ( $c, $args ) = @_;
  89             my $attributes = $args->{attributes};
  90             my $result_set = $args->{result_set};
  91
  92             if ( defined $args->{params}->{_order_by} ) {
  93                 my $order_by = $args->{params}->{_order_by};
  94                 if ( reftype($order_by) and reftype($order_by) eq 'ARRAY' ) {
  95                     my @order_by = map { _build_order_atom({ string => $_, result_set => $result_set }) }
  96                                 @{ $args->{params}->{_order_by} };
  97                     $attributes->{order_by} = \@order_by;
  98                 }
  99                 else {
 100                     $attributes->{order_by} = _build_order_atom({ string => $order_by, result_set => $result_set });
 101                 }
 102             }
 103
 104             return $attributes;
 105         }
 106     );
 107
 108 =head3 dbic_merge_prefetch
 109
 110     $attributes = $c->dbic_merge_prefetch({ attributes => $attributes, result_set => $result_set });
 111
 112 Generates the DBIC prefetch attribute based on embedded relations, and merges into I<$attributes>.
 113
 114 =cut
 115
 116     $app->helper(
 117         'dbic_merge_prefetch' => sub {
 118             my ( $c, $args ) = @_;
 119             my $attributes = $args->{attributes};
 120             my $result_set = $args->{result_set};
 121             my $embed = $c->stash('koha.embed');
 122
 123             return unless defined $embed;
 124
 125             my @prefetches;
 126             foreach my $key (keys %{$embed}) {
 127                 my $parsed = _parse_prefetch($key, $embed, $result_set);
 128                 push @prefetches, $parsed if defined $parsed;
 129             }
 130
 131             if(scalar(@prefetches)) {
 132                 $attributes->{prefetch} = \@prefetches;
 133             }
 134         }
 135     );
 136
 137 =head3 _build_query_params_from_api
 138
 139     my $params = _build_query_params_from_api( $filtered_params, $reserved_params );
 140
 141 Builds the params for searching on DBIC based on the selected matching algorithm.
 142 Valid options are I<contains>, I<starts_with>, I<ends_with> and I<exact>. Default is
 143 I<contains>. If other value is passed, a Koha::Exceptions::WrongParameter exception
 144 is raised.
 145
 146 =cut
 147
 148     $app->helper(
 149         'build_query_params' => sub {
 150
 151             my ( $c, $filtered_params, $reserved_params ) = @_;
 152
 153             my $params;
 154             my $match = $reserved_params->{_match} // 'contains';
 155
 156             foreach my $param ( keys %{$filtered_params} ) {
 157                 if ( $match eq 'contains' ) {
 158                     $params->{$param} =
 159                       { like => '%' . $filtered_params->{$param} . '%' };
 160                 }
 161                 elsif ( $match eq 'starts_with' ) {
 162                     $params->{$param} = { like => $filtered_params->{$param} . '%' };
 163                 }
 164                 elsif ( $match eq 'ends_with' ) {
 165                     $params->{$param} = { like => '%' . $filtered_params->{$param} };
 166                 }
 167                 elsif ( $match eq 'exact' ) {
 168                     $params->{$param} = $filtered_params->{$param};
 169                 }
 170                 else {
 171                     # We should never reach here, because the OpenAPI plugin should
 172                     # prevent invalid params to be passed
 173                     Koha::Exceptions::WrongParameter->throw(
 174                         "Invalid value for _match param ($match)");
 175                 }
 176             }
 177
 178             return $params;
 179         }
 180     );
 181
 182 =head3 stash_embed
 183
 184     $c->stash_embed( $c->match->endpoint->pattern->defaults->{'openapi.op_spec'} );
 185
 186 =cut
 187
 188     $app->helper(
 189         'stash_embed' => sub {
 190
 191             my ( $c, $args ) = @_;
 192
 193             my $spec = $args->{spec} // {};
 194
 195             my $embed_spec   = $spec->{'x-koha-embed'};
 196             my $embed_header = $c->req->headers->header('x-koha-embed');
 197
 198             Koha::Exceptions::BadParameter->throw("Embedding objects is not allowed on this endpoint.")
 199                 if $embed_header and !defined $embed_spec;
 200
 201             if ( $embed_header ) {
 202                 my $THE_embed = {};
 203                 foreach my $embed_req ( split /\s*,\s*/, $embed_header ) {
 204                     my $matches = grep {lc $_ eq lc $embed_req} @{ $embed_spec };
 205
 206                     Koha::Exceptions::BadParameter->throw(
 207                         error => 'Embeding '.$embed_req. ' is not authorised. Check your x-koha-embed headers or remove it.'
 208                     ) unless $matches;
 209
 210                     _merge_embed( _parse_embed($embed_req), $THE_embed);
 211                 }
 212
 213                 $c->stash( 'koha.embed' => $THE_embed )
 214                     if $THE_embed;
 215             }
 216
 217             return $c;
 218         }
 219     );
 220 }
 221
 222 =head2 Internal methods
 223
 224 =head3 _reserved_words
 225
 226     my $reserved_words = _reserved_words();
 227
 228 =cut
 229
 230 sub _reserved_words {
 231
 232     my @reserved_words = qw( _match _order_by _page _per_page );
 233     return \@reserved_words;
 234 }
 235
 236 =head3 _build_order_atom
 237
 238     my $order_atom = _build_order_atom( $string );
 239
 240 Parses I<$string> and outputs data valid for using in SQL::Abstract order_by attribute
 241 according to the following rules:
 242
 243      string -> I<string>
 244     +string -> I<{ -asc => string }>
 245     -string -> I<{ -desc => string }>
 246
 247 =cut
 248
 249 sub _build_order_atom {
 250     my ( $args )   = @_;
 251     my $string     = $args->{string};
 252     my $result_set = $args->{result_set};
 253
 254     my $param = $string;
 255     $param =~ s/^(\+|\-|\s)//;
 256     if ( $result_set ) {
 257         my $model_param = $result_set->from_api_mapping->{$param};
 258         $param = $model_param if defined $model_param;
 259     }
 260
 261     if ( $string =~ m/^\+/ or
 262          $string =~ m/^\s/ ) {
 263         # asc order operator present
 264         return { -asc => $param };
 265     }
 266     elsif ( $string =~ m/^\-/ ) {
 267         # desc order operator present
 268         return { -desc => $param };
 269     }
 270     else {
 271         # no order operator present
 272         return $param;
 273     }
 274 }
 275
 276 =head3 _parse_embed
 277
 278     my $embed = _parse_embed( $string );
 279
 280 Parses I<$string> and outputs data valid for passing to the Kohaa::Object(s)->to_api
 281 method.
 282
 283 =cut
 284
 285 sub _parse_embed {
 286     my $string = shift;
 287
 288     my $result;
 289     my ( $curr, $next ) = split /\s*\.\s*/, $string, 2;
 290
 291     if ( $next ) {
 292         $result->{$curr} = { children => _parse_embed( $next ) };
 293     }
 294     else {
 295         if ( $curr =~ m/^(?<relation>.*)\+count/ ) {
 296             my $key = $+{relation} . "_count";
 297             $result->{$key} = { is_count => 1 };
 298         }
 299         else {
 300             $result->{$curr} = {};
 301         }
 302     }
 303
 304     return $result;
 305 }
 306
 307 =head3 _merge_embed
 308
 309     _merge_embed( $parsed_embed, $global_embed );
 310
 311 Merges the hash referenced by I<$parsed_embed> into I<$global_embed>.
 312
 313 =cut
 314
 315 sub _merge_embed {
 316     my ( $structure, $embed ) = @_;
 317
 318     my ($root) = keys %{ $structure };
 319
 320     if ( any { $root eq $_ } keys %{ $embed } ) {
 321         # Recurse
 322         _merge_embed( $structure->{$root}, $embed->{$root} );
 323     }
 324     else {
 325         # Embed
 326         $embed->{$root} = $structure->{$root};
 327     }
 328 }
 329
 330 sub _parse_prefetch {
 331     my ( $key, $embed, $result_set) = @_;
 332
 333     return unless exists $result_set->prefetch_whitelist->{$key};
 334
 335     my $ko_class = $result_set->prefetch_whitelist->{$key};
 336     return $key unless defined $embed->{$key}->{children} && defined $ko_class;
 337
 338     my $prefetch = {};
 339     foreach my $child (keys %{$embed->{$key}->{children}}) {
 340         my $parsed = _parse_prefetch($child, $embed->{$key}->{children}, $ko_class->new);
 341         $prefetch->{$key} = $parsed if defined $parsed;
 342     }
 343
 344     return unless scalar(keys %{$prefetch});
 345
 346     return $prefetch;
 347 }
 348
 349 1;