Laravel Starter Kit

Tooling (pre-installed)

• Larastan: Static analysis for Laravel (via PHPStan + larastan).
• Pint: Opinionated PHP code formatter (run with Sail).
• Rector-Laravel: Automated refactoring and upgrades (use --dry-run first).
• Pest: Elegant PHP testing framework.

Requirements

• Docker Desktop (or Docker Engine) running
• VS Code (recommended) with the Docker and PHP Debug extensions

Project Setup

1. Use this repo as a GitHub template and create your project.
2. Copy .env.example to .env and update values as needed.
3. Initialize and start services:

./vendor/bin/sail up -d

./vendor/bin/sail artisan key:generate

./vendor/bin/sail artisan migrate

./vendor/bin/sail artisan db:seed

4. Access the app at http://localhost (port can be changed via APP_PORT).

Database

• Uses Postgres (pgsql) via Sail.
• Defaults from .env.example:
  • Host: pgsql, Port: 5432
  • Database: laravel
  • Username: sail, Password: password

Frontend (Vite)

./vendor/bin/sail npm install

./vendor/bin/sail npm run dev

• Vite port is exposed as ${VITE_PORT:-5173}; access http://localhost:5173 when running.

Development Commands

./vendor/bin/sail php vendor/bin/pest

./vendor/bin/sail php vendor/bin/pint -v

./vendor/bin/sail php vendor/bin/phpstan analyse

./vendor/bin/sail php vendor/bin/rector process --dry-run

./vendor/bin/sail php vendor/bin/rector process

Tips

./vendor/bin/sail shell

• To run any Composer binary inside Sail, prefix with ./vendor/bin/sail php.
• Inside the shell you can run tools directly (e.g., pest, pint, phpstan, rector).

Xdebug Setup

VS Code extensions:

• PHP Debug: https://marketplace.visualstudio.com/items?itemName=xdebug.php-pack
• Docker: https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker
• Remote Explorer (optional): https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-explorer

Configure VS Code (already included in .vscode/launch.json):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

Enable Xdebug in Sail:

• In .env, set SAIL_XDEBUG_MODE=develop,debug.
• Optional: override client host or port if needed
  • SAIL_XDEBUG_CONFIG=client_host=host.docker.internal,client_port=9003

Notes

• docker-compose.yml already passes XDEBUG_MODE and XDEBUG_CONFIG from .env (SAIL_* vars). No extra PHP extensions are required—Sail’s PHP image includes Xdebug and toggles it via these env vars.
• Ensure your VS Code debugger is listening on port 9003 and you’ve started Sail (./vendor/bin/sail up).
• For browser debugging, install the Xdebug Helper extension (Chrome): https://chromewebstore.google.com/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc and enable it for the site.
• On Windows/WSL and macOS, host.docker.internal is already configured in docker-compose.yml for the Xdebug client host.

Maintenance

./vendor/bin/sail artisan config:clear

./vendor/bin/sail artisan route:clear

./vendor/bin/sail artisan view:clear

Troubleshooting

• Breakpoints not hit: confirm SAIL_XDEBUG_MODE=develop,debug, restart Sail after changes, and verify VS Code is listening on port 9003.
• Path mapping issues: ensure /var/www/html maps to your ${workspaceFolder} in launch.json.
• Port conflicts: change APP_PORT (app) or FORWARD_DB_PORT (Postgres) in .env and restart Sail.