Laravel Local Development
Every Laravel project we deliver runs locally in one command. Docker Sail, seeded data, Mailpit, MinIO, and Xdebug configured and documented before handover.
Laravel local development environment quality is the difference between a client team that onboards in 20 minutes and one that spends three days debugging environment mismatches. NextEnvision delivers every laravel local development engagement for agencies in Australia, the United Kingdom and Singapore with a fully configured local environment: Docker Sail with all required services, Vite hot reloading, Xdebug debugging, Mailpit email testing, and a written developer onboarding guide. Your client's first developer runs the application locally before they read a line of application code.
What a Production-Grade Laravel Local Development Environment Includes
Laravel Sail is the official Docker Compose development environment for Laravel — a lightweight command-line interface that boots a complete local stack including PHP, MySQL, Redis, Mailpit, and MinIO with a single command. A well-configured laravel local development setup means every developer on the project, whether they are a new team member, a freelancer brought in for a sprint, or the client’s in-house developer receiving the handover, starts from the same environment with no manual configuration required.
The laravel local development environment we configure on every project goes beyond the default Sail setup. We add Xdebug for step-through debugging in VS Code and PhpStorm, configure Mailpit so all outbound emails are captured locally rather than delivered to real addresses, set up MinIO as a local S3-compatible storage service so file upload flows work correctly in development, and seed the database with realistic factory data so developers can explore the application immediately without manually creating test records. The entire environment is documented in a SETUP.md file committed to the repository.
Laravel Local Development Services We Configure
Six laravel local development services. Configured from sprint zero. Documented at handover. Running in one command.
Laravel Sail Docker Environment Configuration
We configure Laravel Sail with a custom docker-compose.yml tailored to the project — PHP version locked to match production, MySQL or PostgreSQL with the correct charset, Redis for queue and cache, and only the services the application actually uses.
Sail aliases and project-specific artisan shortcuts are documented in the onboarding guide so a single ./vendor/bin/sail up -d boots the full stack.
Local Service Stack: MySQL, Redis, Mailpit, MinIO
Mailpit captures all outgoing email from any Mailable or Notification class locally, so developers test email templates without the risk of sending real messages to real users.
MinIO provides a local S3-compatible storage server so file upload, download, and signed URL generation work identically in local development and in production on S3.
Vite and Hot Module Reloading Configuration
We configure the Vite development server inside the Sail container with hot module reloading enabled, so CSS and JavaScript changes reflect in the browser instantly without a full page reload.
For Vue, React, or Inertia.js frontends, we configure entry points, alias paths, and environment variables so the frontend build works identically across local, CI, staging, and production.
Xdebug and Laravel Telescope Local Debugging
Xdebug is configured in the Sail PHP container with VS Code launch.json and PhpStorm run configurations committed to the repository — any developer can set a breakpoint without any IDE setup beyond installing the Xdebug extension.
Laravel Telescope is enabled for local and staging environments, displaying a real-time dashboard of requests, queries, queued jobs, and mail. Explicitly excluded from production.
Database Seeding and Factories for Local Development
Every Eloquent model has a Faker-powered factory generating realistic test data. DatabaseSeeder seeds the full application state — users, content, reference data — so developers explore every feature from a clean database with one artisan command.
Specific seeders cover each user role and permission combination so access-controlled features are testable immediately without manually assigning roles through Tinker.
Developer Onboarding Documentation and Environment Runbook
SETUP.md covers prerequisites, every .env variable with explanation, and the exact commands to boot the environment, seed the database, and run the test suite for the first time.
RUNBOOK.md covers day-to-day development commands, local service UI URLs, and how to connect Xdebug to VS Code and PhpStorm. A new developer reads both and is productive the same day.
The Laravel Local Development Standard We Deliver on Every Project
The laravel local development environment is not a deliverable that gets attention after the application is built. It is configured in sprint zero alongside the CI/CD pipeline, before the first feature is implemented. This means that from the very first pull request, every developer is running an identical local environment, database queries are profiled through Telescope on every development request, and outgoing emails are captured by Mailpit rather than delivered to real addresses.
The standard we apply has three non-negotiable components. First, environment parity: the PHP version, database engine, Redis version, and storage configuration in the local Sail environment match production exactly, preventing the “works on my machine” failures that arise when development and production diverge. Second, zero-configuration onboarding: a developer who clones the repository and runs two commands — cp .env.example .env and ./vendor/bin/sail up -d — has a running, seeded application with no additional steps. Third, documentation completeness: every environment variable is documented with its purpose, its format, and where to obtain its value. No undocumented variables. No tribal knowledge required to run the application. Our case studies show this standard applied to delivered laravel local development projects.
4 Advanced Laravel Local Development Capabilities We Configure
Docker Compose Environment Parity Across Dev, Staging, and Production
Laravel Herd and Valet as Sail Alternatives
Environment parity means the PHP version, database engine, charset, Redis version, and filesystem driver in the local Docker Compose stack match the staging and production server configuration exactly. We configure Docker Compose services using the same base images as the production Docker environment, so the local environment is not a simplified approximation of production but a faithful replica.
Any dependency that behaves differently in local versus production — a MySQL 5.7 versus 8.0 full-text index, a Redis 6 versus 7 command — is detected in local development rather than discovered after a staging deployment.
Environment Variable Management and .env Documentation
Laravel Herd is the native macOS Laravel development environment that replaces Docker with a single-binary installation providing PHP, Nginx, and DNS routing without container overhead. For agency teams on macOS whose developers prefer native performance over Docker, we configure the project for both Sail and Herd compatibility.
Laravel Valet remains an option for teams on older macOS versions or with specific PHP version management requirements using Homebrew. We document both setup paths in the onboarding guide so developers on either environment can get started without needing to consult the team.
Laravel Mix to Vite Migration
Every Laravel project we deliver has a fully documented .env.example file where each variable is grouped by service, named descriptively, and annotated with a comment explaining its purpose and where to obtain its value in each environment. The .env.example is the contract between the application and its configuration.
For projects with sensitive credentials, we use Laravel’s php artisan env:encrypt command to produce an encrypted .env file that can be committed safely to the repository and shared with authorised team members without exposing raw credentials.
Local Queue Worker and Scheduler Development Setup
Laravel Mix reached end-of-life with the adoption of Vite as Laravel’s default frontend toolchain. For projects still using Mix, we execute the migration to Vite as part of the laravel local development environment setup: updating the vite.config.js, adjusting Blade directives from mix() to @vite(), and verifying hot module reloading functions correctly in the Sail container.
The Vite migration also enables faster development build times — typically 10x faster than Webpack-based Mix — which meaningfully improves developer iteration speed for projects with large frontend asset bundles.
White Label Laravel Local Development Setup for Agencies
When agencies deliver Laravel projects to clients, the laravel local development environment is part of what the client inherits. A project handed over without a working local environment setup forces the client’s first developer to spend their first day troubleshooting environment configuration rather than contributing code. That experience reflects on the agency, not the engineering team.
Our white label Laravel development includes the complete local environment deliverable: Sail configuration, service stack, Vite setup, Xdebug, factories, seeders, SETUP.md, and RUNBOOK.md — all committed to the repository and delivered under your agency brand.
NDA protected. Full IP transfer. Zero NextEnvision identifiers in the repository, documentation, or any client-facing material. AEST and GMT coverage for same-day communication with your Australian and UK agency clients.
See our agency partner programme for structured options if your agency delivers multiple Laravel projects with recurring laravel local development environment setup requirements.
Why Broken Laravel Local Development Environments Cost More Than They Appear To
A broken laravel local development environment is not a one-time setup cost. It is a recurring tax on every developer’s productivity for the lifetime of the project. A developer who cannot reliably reproduce a bug locally because their environment uses a different PHP version than production will push fixes that fail in staging. A developer whose local email capturing is not configured will use production credentials during testing and accidentally send real notifications to real users. A developer whose local storage is not configured will add hard-coded file path workarounds that break on every other developer’s machine.
These problems compound across a team. Each additional developer who joins the project inherits the same environment problems and invents the same local workarounds. By the time a project has had three developers and twelve months of active development, the gap between the stated local environment and what each developer actually runs is wide enough that no two machines produce identical test results. NextEnvision prevents this by configuring the laravel local development environment to production-parity standard in sprint zero, documenting it completely, and verifying it in CI so the environment specification is enforced rather than aspirational. Contact us via the contact page to discuss your project requirements.
Laravel Local Development Engagement Models
Full Project Delivery with Local Environment as Standard
Standalone Local Environment Setup and Documentation Sprint
Every laravel local development project NextEnvision delivers includes the complete local environment as a non-optional deliverable. Sail configuration, Vite setup, Xdebug, Mailpit, MinIO, seeders, factories, SETUP.md, and RUNBOOK.md committed to the repository and verified in CI before handover.
The local environment is configured in sprint zero. No developer working on the project at any point during delivery encounters an undocumented environment requirement.
Laravel Local Environment Audit and Remediation
A two to three day sprint configuring a production-grade laravel local development environment for an existing Laravel project that was delivered without one. Sail setup, service configuration, Vite, Xdebug, factories, seeders, SETUP.md, and RUNBOOK.md produced and committed. Suitable for agencies preparing a received codebase for client handover or onboarding a new development team.
Legacy Mix to Vite Migration Sprint
An existing laravel local development environment reviewed against the production-parity standard. Environment variable documentation completeness, Sail service version alignment with production, factory coverage for all Eloquent models, Telescope and Mailpit configuration, and Xdebug setup reviewed. Written audit report with gaps ranked by developer impact. Remediation available as a separate sprint engagement. Contact us via the contact page to discuss.
White Label Local Environment Configuration
A targeted sprint migrating a Laravel Mix frontend build to Vite, updating Blade directives, configuring Vite hot module reloading in Sail, and verifying the CI build pipeline against the new Vite asset compilation. Suitable for projects on Laravel 8 or 9 that need the Vite toolchain before a framework or PHP version upgrade. See our Laravel development page for the full service scope.
How We Configure the Laravel Local Development Environment on Every Project
Sprint Zero Day One: Sail Configuration and PHP Version Lock
Sprint Zero Day Two: Service Stack — MySQL, Redis, Mailpit, MinIO
The laravel local development environment is configured on the first day of sprint zero, before any application code is written. We create the custom docker-compose.yml with the PHP version matching production, add project-specific Sail aliases, and verify the stack boots cleanly on macOS and Linux developer machines.
Sprint Zero Day Three: Xdebug and Telescope Setup
MySQL or PostgreSQL is configured with the correct charset and collation matching the production database. Redis is added for queue and cache drivers. Mailpit captures all outgoing mail from any Mailable or Notification class. MinIO is configured as the local disk driver’s S3 endpoint with the same bucket names used in staging and production.
Sprint Zero Day Four: Vite Configuration and Hot Reloading Verification
Xdebug is configured in the PHP service container with the correct xdebug.mode and xdebug.client_host values for Sail’s Docker network. VS Code launch.json and PhpStorm run configuration files are committed to .vscode/ and .idea/ so debugging works immediately without IDE-specific manual setup. Laravel Telescope is registered and verified displaying requests and queries on the first application page load.
Sprint Zero Day Five: Factories, Seeders, and Database Seeding Verification
The Vite development server is configured to run inside the Sail container with the correct ASSET_URL and VITE_* environment variables. Hot module reloading is verified working for CSS and JavaScript changes. If the project includes a Vue, React, or Inertia.js frontend, the component entry point and alias configuration are tested end-to-end in the local environment.
Sprint Zero Completion: SETUP.md and RUNBOOK.md Committed to Repository
Database factories covering every Eloquent model are implemented using PHP 8 typed properties and Faker providers appropriate to the domain data. DatabaseSeeder calls all seeders in dependency order, creating a complete realistic application state. The seeder run is tested in CI to confirm it completes without errors on a clean database.
Project Handover: Local Environment Verification by Client Developer
At project handover, the client’s first developer follows SETUP.md on their machine and confirms the application runs locally before the handover is accepted. Any environment issue discovered at this stage is resolved as part of the delivery. Visit our Laravel development page for the full laravel local development service scope.
Laravel Local Development FAQs
Questions about Laravel Sail, Herd, Vite, Xdebug, Mailpit, and developer onboarding for Laravel projects.
What is Laravel Sail and why do you use it for laravel local development?
Laravel Sail is the official Docker Compose development environment for Laravel. It boots PHP, MySQL or PostgreSQL, Redis, Mailpit, and other services with a single command, ensuring every developer runs an identical local stack regardless of operating system or existing software. We use Sail as the default laravel local development environment because it most closely mirrors a production Linux server, reducing bugs that only surface in staging or production.
What is the difference between Laravel Sail and Laravel Herd for local development?
Laravel Sail runs the application inside Docker containers, providing full environment isolation and parity with production Linux servers at the cost of Docker Desktop overhead. Laravel Herd is a native macOS binary running PHP and Nginx directly on the host — faster on Apple Silicon but macOS-only. We configure projects for Sail as the default and document Herd as an alternative for macOS teams in the SETUP.md onboarding guide.
How does Mailpit work in a Laravel local development environment?
Mailpit is a local SMTP server and web-based inbox that captures every outgoing email sent by the Laravel application during development, displaying it at localhost:8025. When MAIL_HOST is set to the Mailpit container hostname and MAIL_PORT to 1025, all Mailables and Notifications are delivered to Mailpit rather than real addresses. Developers test email templates and variable interpolation safely without configuring a real SMTP provider for the local environment.
Why does the laravel local development environment need MinIO?
MinIO is a self-hosted S3-compatible object storage server that allows Laravel’s filesystem operations — file uploads, downloads, and signed URL generation — to work exactly as they do in production on S3 or Cloudflare R2, without real cloud credentials for local development. When AWS_ENDPOINT points to the MinIO container, the Storage facade routes all file operations through MinIO locally. This prevents developers from using the local disk driver locally and S3 in production, causing different file path behaviour.
Do you include laravel local development environment setup in white label project delivery?
Yes. The complete laravel local development environment setup is included as standard in every white label Laravel project delivery — Sail, service stack, Vite, Xdebug, Mailpit, MinIO, factories, seeders, SETUP.md, and RUNBOOK.md committed to the repository under your agency brand. No NextEnvision identifiers anywhere. See our white label development and agency partner programme pages for full details.
How do you configure Xdebug for laravel local development in VS Code?
Xdebug is configured in the Sail PHP container with xdebug.mode set to debug and develop, and xdebug.client_host set to host.docker.internal so breakpoints trigger in the IDE on the host machine. A .vscode/launch.json with correct pathMappings between the container path and the local workspace is committed to the repository, so any developer with the PHP Debug extension can start a debugging session immediately. A matching PhpStorm run configuration is included for JetBrains users.