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 under the
   6 # terms of the GNU General Public License as published by the Free Software
   7 # Foundation; either version 3 of the License, or (at your option) any later
   8 # version.
   9 #
  10 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  12 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU General Public License along
  15 # with Koha; if not, write to the Free Software Foundation, Inc.,
  16 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17
  18 use Modern::Perl;
  19
  20 use Mojo::Base 'Mojolicious::Plugin';
  21
  22 use Koha::Exceptions;
  23
  24 =head1 NAME
  25
  26 Koha::REST::Plugin::Query
  27
  28 =head1 API
  29
  30 =head2 Mojolicious::Plugin methods
  31
  32 =head3 register
  33
  34 =cut
  35
  36 sub register {
  37     my ( $self, $app ) = @_;
  38
  39 =head2 Helper methods
  40
  41 =head3 extract_reserved_params
  42
  43     my ( $filtered_params, $reserved_params ) = $c->extract_reserved_params($params);
  44
  45 Generates the DBIC query from the query parameters.
  46
  47 =cut
  48
  49     $app->helper(
  50         'extract_reserved_params' => sub {
  51             my ( $c, $params ) = @_;
  52
  53             my $reserved_params;
  54             my $filtered_params;
  55
  56             my $reserved_words = _reserved_words();
  57
  58             foreach my $param ( keys %{$params} ) {
  59                 if ( grep { $param eq $_ } @{$reserved_words} ) {
  60                     $reserved_params->{$param} = $params->{$param};
  61                 }
  62                 else {
  63                     $filtered_params->{$param} = $params->{$param};
  64                 }
  65             }
  66
  67             return ( $filtered_params, $reserved_params );
  68         }
  69     );
  70
  71 =head3 dbic_merge_sorting
  72
  73     $attributes = $c->dbic_merge_sorting({ attributes => $attributes, params => $params });
  74
  75 Generates the DBIC order_by attributes based on I<$params>, and merges into I<$attributes>.
  76
  77 =cut
  78
  79     $app->helper(
  80         'dbic_merge_sorting' => sub {
  81             my ( $c, $args ) = @_;
  82             my $attributes = $args->{attributes};
  83
  84             if ( defined $args->{params}->{_order_by} ) {
  85                 my @order_by = map { _build_order_atom($_) }
  86                                @{ $args->{params}->{_order_by} };
  87                 $attributes->{order_by} = \@order_by;
  88             }
  89
  90             return $attributes;
  91         }
  92     );
  93
  94 =head3 _build_query_params_from_api
  95
  96     my $params = _build_query_params_from_api( $filtered_params, $reserved_params );
  97
  98 Builds the params for searching on DBIC based on the selected matching algorithm.
  99 Valid options are I<contains>, I<starts_with>, I<ends_with> and I<exact>. Default is
 100 I<contains>. If other value is passed, a Koha::Exceptions::WrongParameter exception
 101 is raised.
 102
 103 =cut
 104
 105     $app->helper(
 106         'build_query_params' => sub {
 107
 108             my ( $c, $filtered_params, $reserved_params ) = @_;
 109
 110             my $params;
 111             my $match = $reserved_params->{_match} // 'contains';
 112
 113             foreach my $param ( keys %{$filtered_params} ) {
 114                 if ( $match eq 'contains' ) {
 115                     $params->{$param} =
 116                       { like => '%' . $filtered_params->{$param} . '%' };
 117                 }
 118                 elsif ( $match eq 'starts_with' ) {
 119                     $params->{$param} = { like => $filtered_params->{$param} . '%' };
 120                 }
 121                 elsif ( $match eq 'ends_with' ) {
 122                     $params->{$param} = { like => '%' . $filtered_params->{$param} };
 123                 }
 124                 elsif ( $match eq 'exact' ) {
 125                     $params->{$param} = $filtered_params->{$param};
 126                 }
 127                 else {
 128                     # We should never reach here, because the OpenAPI plugin should
 129                     # prevent invalid params to be passed
 130                     Koha::Exceptions::WrongParameter->throw(
 131                         "Invalid value for _match param ($match)");
 132                 }
 133             }
 134
 135             return $params;
 136         }
 137     );
 138 }
 139
 140 =head2 Internal methods
 141
 142 =head3 _reserved_words
 143
 144     my $reserved_words = _reserved_words();
 145
 146 =cut
 147
 148 sub _reserved_words {
 149
 150     my @reserved_words = qw( _match _order_by _page _per_page );
 151     return \@reserved_words;
 152 }
 153
 154 =head3 _build_order_atom
 155
 156     my $order_atom = _build_order_atom( $string );
 157
 158 Parses I<$string> and outputs data valid for using in SQL::Abstract order_by attribute
 159 according to the following rules:
 160
 161      string -> I<string>
 162     +string -> I<{ -asc => string }>
 163     -string -> I<{ -desc => string }>
 164
 165 =cut
 166
 167 sub _build_order_atom {
 168     my $string = shift;
 169
 170     if ( $string =~ m/^\+/ or
 171          $string =~ m/^\s/ ) {
 172         # asc order operator present
 173         $string =~ s/^(\+|\s)//;
 174         return { -asc => $string };
 175     }
 176     elsif ( $string =~ m/^\-/ ) {
 177         # desc order operator present
 178         $string =~ s/^\-//;
 179         return { -desc => $string };
 180     }
 181     else {
 182         # no order operator present
 183         return $string;
 184     }
 185 }
 186
 187 1;