README

This package provides an automated way to replace tokens in user-entered text with model/relation data. This is useful for things like email templates.

Model attributes are available as tokens - as well as relation data accessed through dot notation. Any attribute listed in the model's $hidden is excluded, and $appends accessors are included.

For a model that exists in the database, Model::getAttributes() is used. For a model that doesn't yet exist, the factory definition keys are used when a factory is available, otherwise Model::getFillable().

Installation

You can install the package via composer:

composer require eighteen73/laravel-tokens

Usage

List available tokens

plainTokens() returns an array of the tokens available for a model, including tokens for its BelongsTo/HasOne relations (dot notation) and its HasMany/BelongsToMany relations (dot notation with a numeric index).

use Eighteen73\LaravelTokens\TokenManager;

$tokenManager = new TokenManager();

print_r($tokenManager->forModel(App\Models\User::class)->plainTokens());

// [
//     '##name##',
//     '##posts.0.title##',
//     '##category.name##',
// ]

Relations are traversed to a depth of 2 by default. You can change or disable this:

$tokenManager->forModel(App\Models\User::class)->maxDepth(1)->plainTokens();
$tokenManager->forModel(App\Models\User::class)->withoutRelationships()->plainTokens();

Replace tokens in a string

use Eighteen73\LaravelTokens\TokenManager;

$tokenManager = new TokenManager();

echo $tokenManager->forModel(User::factory()->make(['email' => 'test@example.com']))
    ->replaceTokens("My email address is ##email##.");

// My email address is test@example.com

Tokens for relations are resolved from the model too:

echo $tokenManager->forModel($user)
    ->replaceTokens("My first post is ##posts.0.title## in ##category.name##.");

Custom tokens within a model

Implement the CustomTokens contract. getCustomTokens() returns a list of token names, and replaceCustomToken() returns the value for a given name.

use Eighteen73\LaravelTokens\Contracts\CustomTokens;

class User extends Model implements CustomTokens
{
    public function getCustomTokens(): array
    {
        return [
            'my_custom_token',
        ];
    }

    public function replaceCustomToken(string $token): string
    {
        return match ($token) {
            'my_custom_token' => 'Use this custom text.',
        };
    }
}

$tokenManager = new Eighteen73\LaravelTokens\TokenManager();

echo $tokenManager->forModel(User::factory()->make())
    ->replaceTokens("Example text - ##my_custom_token##.");

// Example text - Use this custom text.

Facade

The Tokens facade resolves the same TokenManager out of the container:

use Eighteen73\LaravelTokens\Facades\Tokens;

echo Tokens::forModel($user)->replaceTokens("Hello ##name##.");

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

eighteen73 / laravel-tokens

Maintainers

Package info

Fund package maintenance!

Statistics

Security