README

Laravel Time Period Reference

This Laravel package provides a simple way to convert time period references (e.g., "2 days", "1 week") into Carbon instances.

Installation

You can install the package via composer:

composer require davealex/laravel-time-period-reference

Configuration

Publish the configuration file to customize the time units and their corresponding time references:

php artisan vendor:publish --provider="Davealex\LaravelTimePeriodReference\LaravelTimePeriodReferenceServiceProvider"

Example configuration

<?php

return [
    'units' => [
        'day' => ['day', 'days'],
        'week' => ['week', 'weeks'],
        'month' => ['month', 'months'],
        'year' => ['year', 'years'],
    ],
];

Usage

Use the LaravelTimePeriodReference class to convert time period references into Carbon instances.

// 1. Using facade
use Davealex\LaravelTimePeriodReference\LaravelTimePeriodReferenceFacade;

$carbonInstance = LaravelTimePeriodReferenceFacade::toCarbonInstance('2 days ago');

dd($carbonInstance->toString())

// 2. Manually instantiating the service class
use Davealex\LaravelTimePeriodReference\LaravelTimePeriodReference;
use Illuminate\Config\Repository;
use Illuminate\Support\Carbon;

// Create a configuration array or use the config repository.
$config = new Repository(config('time-period-reference'));

$timePeriodReference = new LaravelTimePeriodReference($config);

// Convert a string time reference to a Carbon instance.
$carbonInstance = $timePeriodReference->toCarbonInstance('2 days ago');

if ($carbonInstance instanceof Carbon) {
    echo $carbonInstance->toDateString(); // Output: e.g., 2024-10-26 (if today is 2024-10-28)
}

// Convert a BackedEnum time reference to a Carbon instance.
enum TimeReferenceEnum: string
{
    case TWO_WEEKS = '2 weeks ago';
}

$enumInstance = TimeReferenceEnum::TWO_WEEKS;

$carbonInstanceFromEnum = $timePeriodReference->toCarbonInstance($enumInstance);

if ($carbonInstanceFromEnum instanceof Carbon) {
    echo $carbonInstanceFromEnum->toDateString();
}

Exceptions

The package throws Davealex\LaravelTimePeriodReference\Exceptions\InvalidTimeReferenceCarbonInstance in the following cases:

Invalid time reference format (e.g., non-numeric value before unit).
Unknown time unit.
Error during Carbon instance creation.

Testing

To run the tests, use PHPUnit:

./vendor/bin/phpunit

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please feel free to contribute by submitting issues or pull requests.

Security

If you discover any security related issues, please email daveabiola@gmail.com instead of using the issue tracker.

Credits

David Olaleye

License

This package is open-source and available under the MIT license.

davealex / laravel-time-period-reference

Maintainers

Details