Download the PHP package charlielangridge/playa without Composer

Playa

Playa gives a Laravel app a lightweight Player model for visitors who are not necessarily logged in.

It is useful for QR-code journeys, event games, voting screens, kiosk flows, demos, and other places where you want to remember "this device came back" without making somebody create an account first.

The package stores the player in your database and keeps only the player's UUID in an HttpOnly cookie.

Installation

Install the package with Composer:

Publish and run the migration:

Publish the config if you want to change the cookie name, lifetime, table name, or user-linking behaviour:

Basic Usage

Add the playa middleware to any route that should have a temporary player.

When a visitor opens that URL, Playa will:

• create a playa_players row if the device has no valid player cookie
• store the player's UUID in a cookie
• resolve the same player on later visits
• refresh last_seen_at
• refresh expires_at when renewal is enabled
• make the player available from the request and the facade

This works well for direct links and QR codes. The QR code can point at a normal application route such as:

The route handles your application flow; Playa handles the device identity.

Accessing The Current Player

From a controller or route closure:

From somewhere that does not receive the request:

You can also resolve or create players directly:

Read an existing, active cookie identity without creating, renewing, or attaching it to the request:

Choose a persistence policy when identity should only be created after application validation succeeds:

Session identities use a browser-session cookie and keep their original server expiry. Rolling identities use the configured persistent lifetime and renew on visits. Requesting Rolling upgrades an existing Session identity without changing its UUID; requesting Session never downgrades an existing Rolling identity.

Storing Player Details

The Player model has first-class name and username columns, plus a data JSON column for application-specific details.

Playa does not ship profile routes or forms. Build those in your application so validation, copy, and consent match the flow you are building.

Extending The Player Model

If your application needs player-specific relationships, casts, scopes, or helpers, create an application model that extends Playa's model:

Then configure Playa to use it:

The configured model must extend CharlieLangridge\Playa\Models\Player. Add any extra columns, such as team_id, in your application's own migrations.

Linking A Player To A User

Players can be linked to your app's user model without becoming authenticated users themselves.

To remove the link:

Automatic linking is disabled by default. If you want any authenticated request with the playa middleware to claim the current player, enable it in config/playa.php:

Expiry And Renewal

By default, a player lasts for 30 days:

Renewal is enabled by default:

With renewal enabled, each visit through the playa middleware refreshes the database expires_at value and the cookie lifetime.

With renewal disabled, the player expires at the original expires_at time even if the device keeps visiting.

When a cookie points to an expired, missing, or invalid player, Playa creates a fresh player and sends a replacement cookie.

Pruning Expired Players

Expired rows are not deleted automatically. Schedule the prune command in your application if you want to clean them up:

You can keep recently expired rows around for a grace period:

Configuration

The published config looks like this:

Table Name

The default table is playa_players to avoid colliding with application tables that already use players.

Change this before publishing/running the migration:

Cookie Options

The cookie stores the player UUID only. By default it is HttpOnly and SameSite Lax.

Set secure to true in production if your app always runs over HTTPS:

If cookie.lifetime_minutes is null, Playa uses lifetime_minutes for the cookie as well.

User Id Type

The migration supports the common Laravel user key types:

Set this before publishing/running the migration.

If user_model is null, Playa falls back to config('auth.providers.users.model').

Events

Playa dispatches events for the main lifecycle points:

• CharlieLangridge\Playa\Events\PlayerCreated
• CharlieLangridge\Playa\Events\PlayerResolved
• CharlieLangridge\Playa\Events\PlayerRenewed
• CharlieLangridge\Playa\Events\PlayerExpired
• CharlieLangridge\Playa\Events\PlayerLinkedToUser

For example:

Forgetting The Current Player

If your application needs to clear the device identity, call:

When called during a request using the playa middleware, the response will clear the player cookie.

Troubleshooting

$request->player() is null

Make sure the route uses the playa middleware.

A new player is created on every visit

Check that the browser is receiving and returning the configured cookie. Common causes are a mismatched cookie domain, a path that does not include the route being visited, or secure being enabled on a non-HTTPS local site.

The cookie is visible but Laravel cannot resolve it

Use the middleware on web routes so Laravel's cookie middleware can decrypt incoming cookies and encrypt outgoing ones.

User linking is not happening

Manual linking is the default:

If you want automatic linking, enable auto_link_authenticated_user and make sure the request is already authenticated before the playa middleware runs.

Testing

Run the test suite:

Run static analysis:

Format the code:

Playa is an open-source Laravel package created and maintained by Ganda Studio.

Read the Ganda Studio case study.

Changelog

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

Credits

• Charlie Langridge

License

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