README

A Laravel library that lets developers and QA test Laravel apps directly from the browser — run Tinker code, artisan commands, manipulate the fake clock, and impersonate users.

Requirements: PHP ^8.2, Laravel ^11

Install

Run from inside your Laravel project root:

bash <(curl -fsSL https://raw.githubusercontent.com/elitedevsquad/sidecar-laravel/3.x/install.sh)

The script handles everything automatically:

composer require elitedevsquad/sidecar-laravel --dev
Publishes config/devsquad-sidecar.php
Writes all .env variables (auto-detects APP_URL, mail server, git remote)
Mirrors keys into .env.example
Injects the CSRF meta tag into any blade layout that has <html>, <body> and <meta>

After running, complete the User Mapping step below.

Manual Setup

If you prefer not to use the install script:

composer require elitedevsquad/sidecar-laravel --dev
php artisan vendor:publish --tag="devsquad-sidecar"

Then add the env variables below, configure user mapping, and ensure the CSRF meta tag is in your main layout:

<meta name="csrf-token" content="{{ csrf_token() }}">

User Mapping

In AppServiceProvider.php, configure Sidecar inside a class_exists() guard so the app does not break when the package is absent (e.g. production with --no-dev):

public function boot(): void
{
    if (class_exists(\EliteDevSquad\SidecarLaravel\Sidecar::class)) {
        \EliteDevSquad\SidecarLaravel\Sidecar::$userMap = [
            'id'    => 'id',
            'name'  => 'first_name',
            'role'  => 'role.name',
            'email' => 'email',
        ];

        \EliteDevSquad\SidecarLaravel\Sidecar::$userBuilder = \App\Models\User::with('role');
    }
}

Environment Variables

The install script writes these automatically. Reference for manual setup or code review:

# DevSquad Sidecar
DS_SIDECAR_ENABLED=true
VITE_DS_SIDECAR_ENABLED="${DS_SIDECAR_ENABLED}"
DS_SIDECAR_TINKER_ENABLED=true
DS_SIDECAR_TINKER_USE_BATCH=true
DS_SIDECAR_COMMANDS_ENABLED=true
DS_SIDECAR_FAKE_CLOCK_ENABLED=true
DS_SIDECAR_ALLOWED_IPS="127.0.0.1"
DS_SIDECAR_BRANCH_URL=https://github.com/your-org/your-repo/tree/
DS_SIDECAR_LINK_MAIL=http://localhost:8025
DS_SIDECAR_LINK_ENVOYER=""

DS_SIDECAR_ALLOWED_IPS supports exact IPs, CIDR ranges, and prefix matching:

DS_SIDECAR_ALLOWED_IPS="127.0.0.1,192.168.1.0/24,10.0.0"

HEADER_BRANCH_NAME — on servers without git (e.g. Envoyer), inject via release hook:

cd {{ release }}
sed -i '/HEADER_BRANCH_NAME/d' .env
echo HEADER_BRANCH_NAME="{{ branch }}" >> .env

Frontend

Laravel apps (auto-inject enabled): no action needed. The Sidecar JS is injected automatically before </body> on every non-production HTML response.

Laravel apps with Vite (auto-inject disabled): if you set DS_SIDECAR_AUTO_INJECT_ASSETS=false in your .env, load Sidecar manually in your JavaScript entry point:

touch resources/js/devsquad-sidecar.js

// resources/js/devsquad-sidecar.js
import { Sidecar } from "../../vendor/elitedevsquad/sidecar-laravel/resources/js/index.js";

if (import.meta.env.VITE_DS_SIDECAR_ENABLED === "true") {
    document.addEventListener("DOMContentLoaded", () => new Sidecar());
}

// resources/js/app.js
import "./devsquad-sidecar";

Then build your assets:

npm run build

External apps (Next.js, Nuxt, etc.): the bundle is served by the Laravel route GET /__devsquad-sidecar/assets/js and reads window.__sidecarBaseUrl at runtime to prefix all API calls.

// e.g. pages/_app.js, app/layout.js, plugins/sidecar.js
if (process.env.NODE_ENV !== 'production') {
    window.__sidecarBaseUrl = process.env.NEXT_PUBLIC_APP_URL ?? 'https://your-laravel-app.com';
    const s = document.createElement('script');
    s.src = window.__sidecarBaseUrl + '/__devsquad-sidecar/assets/js';
    s.defer = true;
    document.head.appendChild(s);
}

elitedevsquad / sidecar-laravel

Maintainers

Package info

Statistics

Security