leshkens/laravel-read-time

A package for laravel framework that shows users the approximate time to read content.

v1.4.0 2024-04-08 06:37 UTC

Requires

• php: ^7.2.5|^8.0
• ext-json: *
• illuminate/support: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0

Requires (Dev)

• orchestra/testbench: ^4.0
• phpunit/phpunit: ^8.0

MIT

• Alexey Chugunov

• blog
• time
• content
• laravel
• article
• read
• reading
• Minutes
• laravel-read-time
• achugunov

README

A package for laravel that shows users the approximate time to read content.

Requirements

• Laravel version 6 or higher

Installation

You can install the package via composer:

composer require leshkens/laravel-read-time

Publish config file

php artisan vendor:publish --provider="Leshkens\LaravelReadTime\Providers\ReadTimeServiceProvider"

Config file config/read-time.php

Global options:

'options' => [
    // The number of words per minute, based on which the approximate  
    // time for reading will be calculated. Default is 230    
    'words_per_minute' => 230,
    
    // Clear result string of html tags
    'strip_tags' => false,
    
    // How many seconds does a new unit start with
    'units' => [
        'second' => 0,
        'minute' => 60,
        //'hour'   => 3600
    ]
],

Word counter class

'counter' => Leshkens\LaravelReadTime\Counter::class,

You can use your class and logic in word counting. Your class must implement the Leshkens\LaravelReadTime\Contracts\CounterInterface interface. The logic should be in the count() method.

For example, this is what a standard word counter logic looks like:

public function count(string $content): int
{
    return count(preg_split('/\s+/', $content, -1, PREG_SPLIT_NO_EMPTY));
}

Locale list

List of locales for forming the string "time to read":

'locales' => [
    'en' => Leshkens\LaravelReadTime\Locales\En::class
]

Locale class must implement the Leshkens\LaravelReadTime\Contracts\LocaleInterface interface. The logic should be in the result() method.

For example, let's add the Ru locale class:

namespace App\Support\ReadTimeLocales;

use Leshkens\LaravelReadTime\Contracts\LocaleInterface;
use function morphos\Russian\pluralize;

class Ru implements LocaleInterface
{
    protected $unitMap = [
        'second' => 'секунда',
        'minute' => 'минута',
        'hour'   => 'час'
    ];

    public function result(int $number, string $unit): string
    {
        return pluralize($number, $this->unitMap[$unit]);
    }
}

In config:

'locales' => [
    'en' => Leshkens\LaravelReadTime\Locales\En::class,
    'ru' => App\Support\ReadTimeLocales\Ru::class
]

Usage

Object

use Illuminate\Support\Str;
use Leshkens\LaravelReadTime\Facades\ReadTime;

$readTime = ReadTime::parse('Lorem ipsum dolor sit amet, consectetur adipiscing elit...');
// Or array
$readTime = ReadTime::parse(['Lorem ipsum dolor sit amet', 'consectetur adipiscing elit']);

$number = $readTime->number; // 3
$unit   = $readTime->unit;   // second

$result = Str::plural($unit, $number);

return "{$number} {$result} on read"; // 3 seconds on read

You can pass your array of settings (the same settings as the global ones) as the second argument of the ReadTime object.

Example:

$options = [
    'words_per_minute' => 1,
    'units'            => [
        'second' => 1 // leave only a seconds
    ]
];

$readTime = ReadTime::parse('Lorem ipsum dolor sit amet, consectetur adipiscing elit...', $options);

$number = $readTime->number; // 3
$unit   = $readTime->unit;   // second

$result = Str::plural($unit, $number);

return "{$number} {$result} on read"; // 480 seconds on read

String

Just add the get() method.

The method can take a locale (from package config locale list) string value as the first argument. If nothing is passed to the method, or the value is null, the current application locale is taken.

use Leshkens\LaravelReadTime\Facades\ReadTime;

ReadTime::parse('Lorem ipsum dolor sit amet, consectetur adipiscing elit...')
    ->get('ru');

Will return 3 секунды

Note: If the object of the desired locale is not in the config file of the package, then by default the string for English will be output

You can also use the readtime() helper to render a string:

readtime($content, $locale, $options);

In model

Add the HasReadTime trait and readTime() method with settings to your model:

use Illuminate\Database\Eloquent\Model;
use Leshkens\LaravelReadTime\Traits\HasReadTime;

class Article extends Model
{
    use HasReadTime;
    
    protected function readTime(): array
    {
        return [
            // Attribute for parse. You can split it with 
            // a dot (e.g 'content.text') if the desired 
            // attribute is inside a array or json
            'source' => 'content',
                    
            // No required. If this key is not present, then the current application locale is taken.
            'locale' => 'en',      
                  
            // No required. Options array.
            'options' => [
                'strip_tags' => true
            ]
        ];
    }
}

$article->read_time returns the string value of the time to read.

If your attribute contains an array or json with locales:

// array
[
    'ru' => 'Какой-то прекрасный текст',
    'en' => 'Lorem ipsum dolor sit amet, consectetur adipiscing elit'
]

// or json
{
    "ru": "Какой-то прекрасный текст",
    "en": "Lorem ipsum dolor sit amet, consectetur adipiscing elit"
}

you can set localable to true:

protected function readTime(): array
{
    return [
        'source'    => 'content',
        'localable' => true
    ];
}

$article->read_time returns the array value:

[
  'ru' => '1 секунда'
  'en' => '3 seconds on read'
]

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Alexey Chugunov
• All Contributors

License

The MIT License (MIT). Please see License File for more information.