Download the PHP package wyxos/shift-php without Composer

SHIFT PHP for Laravel

wyxos/shift-php adds issue reporting and task follow-up inside a Laravel application. It ships the /shift dashboard, an optional in-app report widget, task and thread routes, external collaborator lookup, browser-based installation, and cleaned backend error reporting.

A Laravel app user reports an issue from the page where it happened, the package sends the page URL, route, environment, and user details to the portal, and the developer follows up on the resulting task.

Installation

The default installer uses browser verification:

• Reads APP_ENV and APP_URL from the Laravel app.
• Creates an install session in the portal.
• Prints a verification URL and short code for browser approval.
• Waits for approval through Reverb when available, with polling fallback.
• Lets you choose a project or create one when the account has no available option.
• Writes SHIFT_TOKEN and SHIFT_PROJECT to the app .env.
• Registers the current app environment and URL.
• Scaffolds App\Services\ShiftCollaboratorResolver when the app does not already have one.
• Publishes config and frontend assets.

If SHIFT_TOKEN and SHIFT_PROJECT already exist, the installer keeps those values and skips browser verification.

For manual token setup, run:

Configuration

Typical .env values:

Hosted portal:

Local or self-hosted portal:

Local, .test, .local, localhost, and private IP portal URLs are treated as private by the package client, so SSL verification is skipped for package-to-portal requests. The active portal still needs network access to the app URL when it calls the app for collaborator lookup.

Publish the config when you need to customize middleware, widget behavior, or error-reporting settings:

Important config keys:

Task Creation From A Laravel App

After installation, the dashboard is available at:

It uses the configured route middleware, which defaults to web and auth. Authenticated users can create tasks, edit task details, comment in threads, upload attachments, and manage collaborators for the linked project.

For a lightweight report form inside the host app, use the widget endpoint:

Example browser submission:

For the authenticated dashboard and task routes, the package passes these requests through to SHIFT:

• GET /shift/api/tasks
• POST /shift/api/tasks
• GET /shift/api/tasks/{id}
• PUT /shift/api/tasks/{id}
• PATCH /shift/api/tasks/{id}/collaborators
• GET /shift/api/tasks/{taskId}/threads
• POST /shift/api/tasks/{taskId}/threads

Backend Error Reports

When SHIFT_ERROR_REPORTING_ENABLED=true, the package registers a Laravel exception reporter. It sends cleaned backend exception details to the configured portal without blocking the app's normal exception handling.

The reporter never blocks the app. Missing credentials, disabled reporting, connection failures, timeouts, or failed portal responses are ignored.

The package detects the revision from deployment commit metadata or the app Git checkout. If the checkout has an exact tag for that revision, the tag is sent as the release.

Data Sent

Task and dashboard requests include:

• Project token.
• Authenticated app user name, email, and ID when available.
• App environment from APP_ENV.
• App URL from APP_URL.
• User-entered task fields such as title, description, status, priority, comments, attachments, and collaborator choices.

Widget submissions include:

• Report kind, title, and description.
• Anonymous flag.
• Page details supplied by the widget, such as current page URL, page title, and referrer.
• Authenticated app user details, or guest name/email when guest details are submitted and anonymous mode is not used.
• Linked app name, environment, and URL.

Backend error reports include:

• Project token.
• App environment, app URL, release, and revision.
• Exception class and cleaned message.
• Stack frames and limited source code for in-app files.
• Request method, URL, path, referrer, IP, user agent, query, and body after scrubbing.
• PHP and Laravel versions.
• Authenticated user details when available.

The error cleaner removes common sensitive fields such as password, token, authorization, and cookie values. You should still avoid adding secrets or sensitive customer data to task descriptions, widget details, or exception messages.

Local Testing Path

shift:test creates a QA task in the configured project. Use a local or self-hosted portal unless you intentionally want that task in a hosted project.

Troubleshooting

SHIFT configuration missing

Run the installer or set both SHIFT_TOKEN and SHIFT_PROJECT, then clear cached config:

Browser verification cannot run

The default installer needs an interactive terminal. In CI or non-interactive setup, obtain an API token and project token first, then run:

Local or private URL warning

The installer warns when APP_URL is local or private. Task submission still works when the package can reach the portal, but external collaborator lookup requires that portal to reach the app's /shift/api/collaborators/external endpoint.

/shift loads old assets or a blank UI

In a consuming Laravel app, publish the current package assets:

Widget returns 401 or 403

Check whether the portal project allows widget reports and whether guest submissions are allowed. If guest submissions are disabled, the app user must be authenticated through the configured widget guard.

Task creation returns 422

Check the validation response from the portal. Common causes are missing title/description, an invalid project token, or project configuration that does not allow the requested report path.

Error reports do not appear

Check that error reporting is enabled and fully configured:

The reporter is intentionally silent on network failures and failed portal responses so it does not interfere with application error handling.

License

MIT Wyxos. See LICENSE.md for details.