# Laravel Herd

[Laravel Herd](https://herd.laravel.com) is a native macOS and Windows application that provides a complete local development environment for PHP and Laravel. It bundles PHP, nginx, and dnsmasq into a zero-configuration setup — every project you link gets a `.test` domain (like `myapp.test`) that just works, with optional HTTPS and per-project PHP version management. If you're new to PHP, Herd paired with the [Laravel framework](https://laravel.com) is a great starting point — Laravel is a full-featured web framework that scales from quick prototypes to production applications, and Herd gets you up and running in seconds.

Polyscope automatically detects Laravel Herd when you add a repository. If the project is linked as a Herd site, Polyscope suggests a `polyscope.json` configuration that keeps each workspace registered with Herd — giving every workspace its own `.test` preview URL with no manual setup.

## How Detection Works

When you add a repository to Polyscope, it checks whether:

1. The `herd` CLI is installed on your system
2. The repository path matches one of your Herd-linked sites (via `herd sites`)

If both conditions are met, Polyscope shows a configuration suggestion dialog with a pre-filled `polyscope.json` tailored to your Herd setup.

![Herd integration](/images/docs/herd-integration.png)

## Suggested Configuration

The suggested configuration includes setup and archive scripts, plus a preview URL template. Here's an example of what Polyscope might suggest:

```json
{
  "scripts": {
    "setup": ["herd link", "herd secure"],
    "archive": ["herd unsecure", "herd unlink"]
  },
  "preview": {
    "url": "https://{{folder}}.test"
  }
}
```

The exact configuration depends on your Herd site settings:

- **`herd link`** — Always included. Registers the workspace directory as a Herd site so it gets a `.test` domain.
- **`herd secure`** — Included when your site uses HTTPS. Generates a trusted SSL certificate for the workspace.
- **`herd isolate <version>`** — Included when your site uses an isolated PHP version (e.g., PHP 8.3). Ensures the workspace runs the same PHP version as your main site.

The archive scripts reverse these steps when a workspace is deleted, keeping Herd clean.

## Preview URLs

The preview URL uses the `{{folder}}` token, which Polyscope replaces with the workspace directory name at runtime. For example, if you create a workspace in a folder called `fix-login-bug`, the preview URL becomes `https://fix-login-bug.test`.

Because Herd handles DNS resolution and serves your project automatically, the preview is available in Polyscope's built-in browser as soon as the setup script finishes.

## Accepting the Configuration

When the suggestion dialog appears:

1. Review the suggested `polyscope.json`
2. Click **Accept** to save it to your repository root
3. All new workspaces will automatically run the setup scripts and use the preview URL

You only need to accept this once per repository. After that, every workspace you create will be set up with Herd automatically.

## Tips

- **Works without changes** — If Herd is already set up for your project, Polyscope picks up the configuration automatically. No extra steps needed.
- **Customize after accepting** — The generated `polyscope.json` is a starting point. You can edit it to add additional setup steps like running migrations or installing dependencies.
- **HTTPS matches your site** — If your main Herd site uses HTTPS, workspaces will too. If it uses plain HTTP, workspaces will follow suit.
- **Not using Herd?** — You can create a `polyscope.json` manually with any setup scripts and preview URL that fit your development environment. See [Workflow](/docs/core-concepts/workflows) for more details.