README

A development-only package that publishes and updates a shared set of Laravel starter files into an existing project through a single Artisan command. Use it to bootstrap new projects and keep existing ones in sync with the latest starter improvements.

Requirements: Laravel 13 and PHP 8.3+.

Installation

Install the package as a development dependency:

composer require --dev taras-koval/laravel-starter

Local development

When working on the package itself, register it as a path repository with a symlink so changes are reflected immediately without reinstalling, then require it:

"repositories": [
    {
        "type": "path",
        "url": "packages/laravel-starter",
        "options": { "symlink": true }
    }
]

composer require --dev taras-koval/laravel-starter

Prerequisites

The published stubs reference third-party packages. The starter package does not require them itself — they are declared under suggest so they remain explicit in the consuming project's composer.json. Install them before running starter:publish.

Install everything at once:

composer require laravel/sanctum dedoc/scramble spatie/laravel-query-builder geoip2/geoip2 jenssegers/agent mcamara/laravel-localization

Or install only what a specific feature requires:

# API token authentication (User model, AuthController, SessionResource)
composer require laravel/sanctum

# OpenAPI documentation generation
composer require dedoc/scramble

# Includable relations feature
composer require spatie/laravel-query-builder

# GeoIP session metadata (RequestMetadataService, UpdateGeoIpDatabaseCommand)
composer require geoip2/geoip2

# Device detection in sessions (RequestMetadataService)
composer require jenssegers/agent

# Localized web routes
composer require mcamara/laravel-localization

Usage

A single command applies every change:

php artisan starter:publish

Warning: Publishing overwrites the files listed under Overwritten without confirmation. Commit or stash your work first so you can review the diff afterwards.

The command uses three publishing strategies, described below.

Overwritten (always replaced)

bootstrap/app.php is overwritten wholesale, so it already registers routes/auth.php (under the api middleware group and /api prefix). Keep your own application routes in the host-owned routes/api.php; the starter routes live in the standalone, overwritable routes/auth.php.

Copied only when missing

Migrations (published with a fresh timestamp)

Post-install steps

Storage symlink

After publishing, create the public storage symlink:

php artisan storage:link

Laravel Boost

The starter ships boost.json (the shared Boost config), but the generated AI guidelines and MCP configs are not published — they embed machine-specific absolute paths and version-pinned guidelines, and are git-ignored (.cursor/, .ai/, AGENTS.md). Regenerate them locally after publishing:

php artisan boost:install

This recreates AGENTS.md, .cursor/*, and .ai/mcp/mcp.json for the local machine and the project's installed package versions.

If you prefer to copy the MCP configs manually instead of running the installer, use the templates below and replace every path that points at this project (the PHP binary, the project root, and SITE_PATH) with the new project's values.

.ai/mcp/mcp.json:

{
  "mcpServers": {
    "laravel-boost": {
      "command": "C:\\Users\\Taras\\.config\\herd\\bin\\php84\\php.exe",
      "args": [
        "S:\\herd\\YOUR-PROJECT\\artisan",
        "boost:mcp"
      ]
    },
    "herd": {
      "command": "C:\\Users\\Taras\\.config\\herd\\bin\\php84\\php.exe",
      "args": [
        "C:/Users/Taras/.config/herd/bin/herd-mcp.phar"
      ],
      "env": {
        "SITE_PATH": "S:\\herd\\YOUR-PROJECT"
      }
    }
  }
}

.cursor/mcp.json:

{
    "mcpServers": {
        "laravel-boost": {
            "command": "php",
            "args": [
                "artisan",
                "boost:mcp"
            ]
        },
        "herd": {
            "command": "php",
            "args": [
                "C:/Users/Taras/.config/herd/bin/herd-mcp.phar"
            ],
            "env": {
                "SITE_PATH": "S:\\herd\\YOUR-PROJECT"
            }
        }
    }
}

Trusted Proxies

The published application reads the client IP from X-Forwarded-* headers when running behind a reverse proxy or load balancer. To prevent IP spoofing, you must tell Laravel which proxies to trust via the TRUSTED_PROXIES environment variable.

Configuration

When to use each option

Why it matters

Without trusted-proxy configuration, an attacker can send an arbitrary X-Forwarded-For header on every request. Laravel reads this as the client IP and uses it for:

• Rate limiting (login throttle, API throttle) — circumvented.
• GeoIP detection — falsified country and city in personal_access_tokens.
• Audit logs — rendered useless for tracking the real source.

Trusting only specific proxies makes any spoofing attempt fall back to the real REMOTE_ADDR.

CI/CD auto-deploy

The published .github/workflows/deploy-prod.yml and deploy-staging.yml ship with the push trigger commented out, so a freshly cloned project will not deploy on push. Only workflow_dispatch (manual run) is active.

To enable auto-deploy on a new project:

1. Set the workflow env values in each workflow file:
   • DEPLOY_DOMAIN — your domain (for example, app.example.com, staging.example.com)
   • DEPLOY_BRANCH — branch to deploy (main for production, develop for staging)
2. Add the repository secrets (Settings → Secrets and variables → Actions):
   • SSH_HOST — server host or IP
   • SSH_USERNAME — SSH user
   • SSH_PORT — SSH port
   • SSH_KEY — private SSH key
3. Uncomment the push trigger at the top of each workflow file.

deploy.sh is environment-driven and usually needs no edits, but review these defaults at the top of the script for your server:

• APP_USER / APP_GROUP — file ownership (defaults ubuntu / www-data)
• DEPLOY_APP_DIR — overrides the app path (defaults /var/www/$DEPLOY_DOMAIN)
• DEPLOY_APP_URL — overrides the health-check URL (defaults https://$DEPLOY_DOMAIN)