view release on metacpan or  search on metacpan

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

        {
            $keep = ( $best_q_for{ $_->{token} } == $_->{quality} ) ? 1 : 0;
            delete( $best_q_for{ $_->{token} } ) if( $keep );
        }
        $keep;
    } @$elements;
    return( $elements );
}

sub _partial_match
{
    my( $self, $their, $our ) = @_;
    # Here, nothing beyond the type/* already handled in _full_match.
    return(0);
}

sub _specificity
{
    my( $self, $their, $our ) = @_;
    # The more there are wildcard parts on the preferences side, the more it is specific.
    # */* => 0, type/* => 1, type/subtype => 2
    return(2) if( $their->{type} ne '*' && $their->{subtype} ne '*' && $their->{type} eq $our->{type} && $their->{subtype} eq $our->{subtype} );
    return(1) if( $their->{type} eq $our->{type} && $their->{subtype} eq '*' );
    return(0);
}

1;
# NOTE: POD
__END__

=encoding utf-8

=head1 NAME

Apache2::API::Headers::Accept - Parser and matcher for HTTP Accept header

=head1 SYNOPSIS

    use Apache2::API::Headers::Accept;
    my $accept = Apache2::API::Headers::Accept->new('text/html;q=0.9,application/json');
    my $mime = $accept->match(['text/html', 'application/json']); # => 'text/html'
    # inspect client preferences (by q, desc):
    my $prefs = $a->preferences; # [ 'application/json', 'text/html' ]

=head1 DESCRIPTION

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.