README

Track user status automatically, or have custom statuses set by the user.

Originally, this package was going to be for users, but I realized that it could be used for any model that you want to track the status of (ie: Teams).

So, while it's called Laravel User Status, it can be used for any model that you want to track the status of.

Features

Automatically track user status
Custom statuses
Real-time status updates
Keep history of statuses
Customizable
Laravel Echo support

Installation

You can install the package via composer:

composer require brianclogan/laravel-user-status

You can publish and run the migrations with:

php artisan vendor:publish --tag="laravel-user-status-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="laravel-user-status-config"

This is the contents of the published config file:

return [

    /**
     * Tables
     *
     * The table names used by the package.
     */
    'tables' => [
        'status_table' => env('USER_STATUS_TABLE', 'user_statuses'),
    ],

    /**
     * Laravel Echo Configuration
     *
     * This is used to broadcast the status changes to the frontend
     * and update the status in real-time. (if enabled)
     */
    'echo' => [
        /**
         * Enable or disable the broadcasting of the status changes
         */
        'enabled' => env('USER_STATUS_ECHO_ENABLED', false),
        'channel' => 'statusable.{type}.{id}',
        /**
         * Enable or disable the broadcasting of the presence changes
         */
        'presences_enabled' => env('USER_STATUS_PRESENCES_ENABLED', false),
        'presences' => 'statusable.{type}.{id}.presences',
    ],

    /**
     * Middleware
     *
     * This is applied when a user makes a request. It will update the user's status
     * based on the configuration below.
     *
     * If you want to disable this, set `enabled` to false.
     *
     * If you want to apply this to a different group, you can add more groups to the `groups` array.
     * If you apply `api`, it will set the user status online for any API request which is not recommended.
     *
     * Feel free to disable this, and make your own middleware if you want.
     */
    'middleware' => [
        'enabled' => env('USER_STATUS_MIDDLEWARE_ENABLED', true),
        'groups' => [
            'web',
        ],
        'status' => 'online',
        'reason' => 'active',
        'meta' => null,
    ],

    /**
     * Status Model
     *
     * The model used to store the statuses, you can extend the model
     * and change the class here. NOT RECOMMENDED, but possible.
     */
    'status_model' => \BrianLogan\LaravelUserStatus\Models\Status::class,

    /**
     * Keep History
     *
     * If enabled, the package will keep past statuses in the database.
     *
     * This is useful for analytics and other purposes, but is disabled
     * by default to reduce the size of the database.
     *
     * If you enable this, you should also enable the `echo.enabled` option
     * to keep the frontend in sync with the backend.
     *
     * This will update the status model to use a morphMany relationship
     * instead of a morphOne relationship.
     */
    'keep_history' => env('USER_STATUS_KEEP_HISTORY', false),

];

Usage

Add the HasStatus trait to the model you want to track the status of.

use BrianLogan\LaravelUserStatus\Traits\HasStatus;

class User extends Model
{
    use HasStatus;
}

Get the latest status

$user = User::find(1);
$user->getLatestStatus();

Set a status

When calling setStatus, only the status is required. The reason and meta are optional.

meta can be used to store additional information about the status, such as colors, icons, custom messages, etc.

$user = User::find(1);
$user->setStatus(status: 'active', reason: 'User is active', meta: ['foo' => 'bar']);

NOTE: If you have keep_history enabled, rather than updating the status, it will create a new record.

Scopes

Get all with a specific status

User::whereStatus('active')->get();

NOTE: If you have keep_history enabled, it will return all records with the status, not just the latest.

Get all with a specific status reason

User::whereStatusReason('User is active')->get();

NOTE: If you have keep_history enabled, it will return all records with the status, not just the latest.

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.

brianclogan / laravel-user-status

Maintainers

Details