Range Validator

The If-Range and Range preconditions make use of RangeValidator component, whenever they are evaluated. A default validator is automatically bound in the service container, when you register this package's service container.

• Default Behaviour
• Custom Validator
  • Register Custom Validator

Default Behaviour

The default validator will ensure that the following are meet, when a Range header is available.

• Verify range unit (e.g. bytes) is supported / allowed.
• Verify that requested range-sets do not exceed maximum amount (See resource context's $maxRangeSets argument)
• Verify that requested ranges-sets do not overlap.
• Wrap requested range-sets into a collection, which can then be set in the assigned resource context.

Depending on what verification fails to meet desired expectation, the validator will abort the request via its assigned actions. The result is that either of the following responses are returned by your application:

• 400 Bad Request
• 416 Range Not Satisfiable

Custom Validator

If the default provided range validator is not to your liking, you can create your own. This can be done either by extending the default or by inheriting from \Aedart\Contracts\ETags\Preconditions\RangeValidator.

use Aedart\Contracts\ETags\Preconditions\RangeValidator;
use Aedart\ETags\Preconditions\Concerns;
use Aedart\Contracts\ETags\Preconditions\Ranges\RangeSet;
use Ramsey\Collection\CollectionInterface;

class MyCustomRangeValidator implements RangeValidator
{
    use Concerns\CurrentRequest;
    use Concerns\Actions;
    
    public function __construct(
        protected string $rangeUnit,
        protected int $maxRangeSets
    ) {}

    /**
     * Validates requested "Range" header field, for given resource
     *
     * @param  ResourceContext  $resource
     *
     * @return CollectionInterface<RangeSet>

     * @throws HttpExceptionInterface
     */
    public function validate(ResourceContext $resource): CollectionInterface
    {
        // ... validation logic not shown here...
    }

    public function allowedRangeUnit(): string
    {
        return $this->rangeUnit;
    }

    public function maximumRangeSets(): int
    {
        return $this->maximumRangeSets;
    }
}

Constructor Arguments

The __construct() arguments (rangeUnit and maxRangeSets) are required. These will be provided by the internal mechanisms of the If-Range and Range preconditions.

Register Custom Validator

To use your custom range validator, you must bind it in the application's service container. This can, for instance, be done in your AppServiceProvider.

namespace App\Providers;

use Aedart\Contracts\ETags\Preconditions\RangeValidator;
use App\Validators\Http\MyCustomRangeValidator;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->bind(RangeValidator::class, function ($app, array $args = []) {
            $unit = $args['rangeUnit'] ?? 'bytes';
            $maxRanges = $args['maxRangeSets'] ?? 5;

            return new MyCustomRangeValidator($unit, $maxRanges);
        });
    }
    
    // ... remaining not shown ...
}