view release on metacpan or  search on metacpan

lib/Apache2/API/Headers/Accept.pm  view on Meta::CPAN

Parses the C<Accept> header and selects the best media type among the types you can serve. It supports exact matches (C<type/subtype>), type wildcards (C<type/*>), and full wildcards (C<*/*>), with quality values (C<q>) per RFC 7231 and RFC 9110.

It inherits from L<Apache2::API::Headers::AcceptCommon>.

The algorithm is as follows:

=over 4

=item * Specificity order (highest first): C<type/subtype> E<gt> C<type/*> E<gt> C<*/*>

=item * C<q> value primary sort; on tie, prefer more specific matches.

=item * C<*/*> at same C<q> never outranks a specific match; at strictly higher C<q> it picks the first supported item.

=item * Non-C<q> parameters (e.g. C<charset>, C<version>) do not influence matching; they are parsed but ignored for selection.

=back

=head1 CONSTRUCTOR

=head2 new( $header )

Creates a new instance with the given C<Accept> header string, and returns it.

If an error occurred, it sets an error that can be retrieved with the L<error method|Module::Generic/error>, and it returns C<undef> in scalar context, or an empty list in list context.

=head1 METHODS

=head2 match( \@supported_media_types )

Returns the best matching media type, as a string, from the provided list.

If no suitable media type could be found, it returns an empty string, so you need to check the return value if it is defined or not to differentiate from errors.

If an error occurred, it sets an error that can be retrieved with the L<error method|Module::Generic/error>, and it returns C<undef> in scalar context, or an empty list in list context.

=head2 media_types

This is an alias to L</preferences>

=head2 preferences

Read-only.

Returns an array reference of media types, submitted by the user in his HTTP request, sorted by decreasing quality (C<q>), with duplicates removed (highest C<q> kept).

If an error occurred, it sets an error that can be retrieved with the L<error method|Module::Generic/error>, and it returns C<undef> in scalar context, or an empty list in list context.

=head1 EXAMPLES

=head2 1. More specific beats wildcard at same q

    my $a = Apache2::API::Headers::Accept->new( 'text/html;q=0.9, text/*;q=0.9' );
    $a->match( [ 'text/plain', 'text/html' ] );
    # "text/html"

=head2 2. */* is a fallback only

    my $a = Apache2::API::Headers::Accept->new( '*/*;q=0.9, application/json;q=0.9' );
    $a->match( [ 'image/png', 'text/html', 'application/json' ] );
    # "application/json"

=head2 3. */* with higher q wins and chooses first supported

    my $a = Apache2::API::Headers::Accept->new( '*/*;q=1.0, application/json;q=0.9' );
    $a->match( [ 'image/png', 'text/html', 'application/json' ] );
    # "image/png"

=head1 LEGACY MATCH PRIORITY

Set C<$Apache2::API::Headers::Accept::MATCH_PRIORITY_0_01_STYLE> to true to make equal-C<q> ties follow the order of your offers (the array reference of supported medias), instead of the header order. Full matches still outrank partial ones. Wildcard...

=head1 PERFORMANCE

The matchers called with L<Apache2::API::Headers::AcceptCommon/match> loops through the array reference of supported medias times the number of parsed acceptable medias as submitted by the client.

Typical HTTP C<Accept> headers are small, so the performance should be very good.

L<Apache2::API::Headers::AcceptCommon/preferences> and sorted results are cached per object.

=head1 AUTHOR

Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>

=head1 SEE ALSO

L<Apache2::API::Headers::AcceptCommon>, L<Apache2::API::Headers::AcceptLanguage>, RFC 7231, RFC 9110.

L<Apache2::API::DateTime>, L<Apache2::API::Query>, L<Apache2::API::Request>, L<Apache2::API::Request::Params>, L<Apache2::API::Request::Upload>, L<Apache2::API::Response>, L<Apache2::API::Status>

L<Apache2::Request>, L<Apache2::RequestRec>, L<Apache2::RequestUtil>

=head1 COPYRIGHT & LICENSE

Copyright (c) 2023 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated
files under the same terms as Perl itself.

=cut