Before making any rash decisions to "rewrite everything" - which is often a career-ending trap - you need a cold, objective assessment of what you actually have.

This checklist is divided into four critical pillars to help you map the land, manage operational risks, and plan your next strategic moves.

1. The Stability & Risk Pillar (Weeks 1-2)

Your immediate goal is to ensure the system doesn't collapse under your watch. Focus on observability and identifying operational blind spots.

Telemetry & Observability

• Centralized Logging: Are metrics, logs, and traces centralized in tools like Datadog, New Relic, or Honeycomb, or are engineers still SSH-ing into production servers to read raw log files?
• Time-to-Detection (TTD): Can you accurately pinpoint the root cause of a production failure within 5 minutes?
• Alerting Fidelity: Check the signal-to-noise ratio of existing alerts. If the team is plagued by constant, non-actionable Slack notifications or pager alerts, true emergencies will go unnoticed.

The Deployment Safety Net

• CI/CD Pipeline Maturity: Is there a modern, automated pipeline, or is deployment a manual, stressful event handled by one or two "gatekeeper" engineers?
• Rollback Speed: Can you roll back a bad deployment at the press of a button, or does a rollback require manual database surgery and code cherry-picks?
• Pre-production Environments: Do staging and development environments closely mirror production, or is "testing in production" the default workflow?

Disaster Recovery (DR) Reality Check

• The Restore Test: When was the last time database and file backups were actually restored and tested in an isolated sandbox?
• RTO & RPO: Do you have a verified, SLA-backed Recovery Time Objective (RTO) and Recovery Point Objective (RPO)?
• Single Region Vulnerabilities: Is the infrastructure confined to a single cloud provider zone or region without automatic failover?

Technical Debt & Security Vulnerabilities

• Automated Dependency Auditing: Run tools like Snyk, Dependabot, or Trivy. Legacy systems are notorious for running framework versions that haven't seen a security patch in years.
• Secret Management: Are production secrets, API keys, and certificates securely managed via systems like Vault or AWS Secrets Manager, or are they hardcoded in repositories?

2. The Architecture & Scale Pillar (Weeks 3-4)

Here, you are analyzing how the application handles data, traffic, and state under load.

Monolith vs. Distributed Footprint

• Code Coupling: Is it a "spaghetti monolith" where changing code in the billing module unexpectedly breaks the reporting engine?
• Domain Boundaries: Are domain boundaries cleanly separated, or is the business logic tightly coupled with database-specific implementations?

Data Integrity & Bottlenecks

• Database Single Point of Failure (SPOF): Is the primary relational database server overwhelmed? Look for missing indexes, bloated tables, and whether the application relies heavily on database-level stored procedures, which are notoriously hard to scale, debug, and version control.
• Read/Write Split: Does the system utilize read replicas to offload reporting and search traffic from the transactional primary?

State Management

• Horizontal Scalability: Does the application scale horizontally, or does it rely on sticky sessions, storing session state on the local server, making true cloud elasticity and autoscaling impossible?
• Caching Strategy: Is caching (Redis, Memcached) implemented as a strategic layer with proper TTLs, or is it used as a band-aid to cover up slow database queries?

API & Integration Contracts

• Documentation and Compliance: Are internal and external APIs versioned and documented using standards like OpenAPI/Swagger, or are you flying blind on what upstream and downstream services expect?
• Rate Limiting & Safety: Is there an API gateway enforcing rate limits to prevent malicious actors or misconfigured integration clients from taking down your API servers?

3. The Developer Velocity Pillar (Weeks 5-6)

A legacy system's worst trait isn't always its bugs; it's how much it slows your team down and destroys developer morale.

Local Environment Setup

• "Time to First Hello World": Can a newly hired engineer clone the repository and get a working environment running locally, for example using Docker Compose, within a few hours, or does it take weeks of manual configuration and dependency hunting?
• Mock Dependencies: Are external SaaS dependencies, such as Stripe or Twilio, cleanly mocked or sandboxed for local testing?

Test Coverage vs. Test Confidence

• Flakiness Index: Don't just look at the coverage percentage. Are the tests flaky, failing intermittently in CI/CD pipelines?
• Execution Time: Do developers skip running the test suite because it takes 45 minutes to execute? A slow test suite is a bypassed test suite.

Knowledge Silos & Tribal Knowledge

• Runbook Availability: Is the system's runtime architecture documented in an accessible format, or does it live entirely inside the heads of the two longest-tenured engineers?
• Bus Factor: If your lead developer were to leave tomorrow, would the team still be able to deploy and support the system?

4. The Financial & Legal Pillar (Ongoing)

Legacy infrastructure often hides massive, unoptimized cloud spend and compliance liabilities that drain engineering budgets.

Infrastructure Efficiency

• Orphaned Resources: Are you paying for massive, over-provisioned idle servers, old database snapshots, and unattached storage volumes?
• Containerization & Serverless: Can workloads be migrated to containers or serverless architectures to leverage dynamic scaling and cut cloud spend?

Data Privacy & Compliance

• Encryption at Rest & In Transit: Is customer data encrypted end-to-end, or does it transit plain-text over internal networks?
• Regulatory Alignment: Does the legacy architecture comply with current regulations (GDPR, CCPA, HIPAA, SOC2)? How easy is it to perform a hard delete of user data (Right to be Forgotten)?

Licensing Dead Ends

• Commercial Lock-in: Are you tied to expensive, proprietary legacy database or operating system licenses? Can these be migrated to open-source alternatives like PostgreSQL or Linux?

The Assessment Matrix

To help prioritize your roadmap, run every major component of the inherited system through this quick triage matrix:

The Golden Rule of Legacy Transitions

Avoid the temptation of the "Big Bang Rewrite." It is almost always a trap that burns capital, delays feature delivery, and alienates product and sales teams.

Instead, rely on the Strangler Fig Application pattern. Chip away at the legacy system by placing new features in microservices or clean, decoupled modules behind an API gateway. Over time, routing is shifted from the legacy core to the new modules, gradually letting the old, unmaintainable code wither away.

The problem is not the language. It is that references pile up in memory that PHP's garbage collector cannot detect. The process grows, and eventually the server runs out of memory and crashes.

The fix is simple: restart your workers more often.

Restart Workers with Cron

With a process manager like Supervisor in place, you can restart workers every hour and let Supervisor bring them back automatically.

Drop this into your crontab:

0 * * * * forge php /home/forge/laravel.com/artisan queue:restart

This runs queue:restart every hour. All running workers receive the signal and gracefully exit after finishing whatever job they are currently processing. Supervisor detects the exit and spawns a fresh, clean process.

Built-in Options: max-jobs and max-time

If you would rather not use a cron job, Laravel gives you two command-line options that do the same thing:

php artisan queue:work --max-jobs=1000 --max-time=3600

• --max-jobs: the worker exits after processing this many jobs, regardless of how long it took.
• --max-time: the worker exits after this many seconds, regardless of how many jobs it ran.

The check happens between jobs, not in the middle of one. So if a job is still running when the limit expires, the worker finishes it first and then exits.

The combination is useful: process up to 1,000 jobs or run for up to an hour, whichever comes first. This caps both memory growth and total runtime in a single command.

Signal the Worker from Inside a Job

Sometimes you know a specific job type is memory-heavy: maybe it processes a large file, batches thousands of database records, or loads big datasets into memory. You can tell the worker to quit right after that job finishes, from within the job's handle() method:

public function handle()
{
    // Run the job logic.

    app('queue.worker')->shouldQuit = 1;
}

This sets the shouldQuit flag that the worker checks at the end of each loop iteration. When the flag is true, the worker exits after the current job completes. This gives you fine-grained control: only restart after the jobs that actually need it, rather than on a fixed schedule.

Using Horizon

If you are using Laravel Horizon, you can configure maxJobs and maxTime directly in your supervisor configuration instead of passing CLI options:

'environments' => [
    'production' => [
        'supervisor-1' => [
            // ...
            'maxTime' => 3600,
            'maxJobs' => 1000,
        ],
    ],
],

Horizon handles the rest. It manages the underlying worker processes and restarts them according to your limits.

The Strategy

Restarting workers is not a hack. It is the intended escape hatch for a fundamental constraint: any long-running process accumulates memory over time, no matter what language it is written in. The strategy is:

1. Set a reasonable max-time or max-jobs as a safety net (default for everything).
2. Use shouldQuit inside specific jobs that you know are memory-heavy.
3. Run queue:restart on a cron as a last-resort backstop if you are not using --max-jobs or --max-time.

The three approaches are complementary. Use the combination that matches your workload. A worker processing small, predictable jobs can run for hours. One handling large file uploads or API batch operations should cycle more frequently.

Key Takeaways

• PHP workers can leak memory over time: not a language flaw, just reality for any long-running process.
• Restart often: hourly restarts with queue:restart via cron keep things clean.
• --max-jobs and --max-time let you cap worker lifespan without external tools.
• shouldQuit from inside a job gives you per-job-type control over restarts.
• Horizon has built-in maxJobs/maxTime settings so you enforce the same rules without extra scripts.
• Do not fight the restart: it is how queue workers stay healthy. Embrace the cycle.

Let us walk through a progression, from built-in array casting all the way to a clean, reusable castable value object setup.

The Problem with Plain JSON Columns

Eloquent's $casts property gives you a couple of built-in options:

protected $casts = [
    'address' => 'array',
];

This auto-serializes to and from JSON. Access it and you get an associative array back. Swap 'array' for 'object' and you get a stdClass instead. Both work, but neither gives you any type safety, autocomplete, or the ability to add behaviour directly on the data.

If your address value needs to know how to calculate a postage cost or build a map URL, you end up writing helper functions that take the raw array, which scatters that logic across your codebase instead of keeping it where it belongs.

Custom Casts: First Step

Laravel's custom casts give us a better foundation. You create a class that implements the CastsAttributes interface and define get() and set() methods:

namespace App\Casts;

use App\Values\Address as AddressValue;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

class Address implements CastsAttributes
{
    public function get($model, $key, $value, $attributes)
    {
        if (is_null($value)) {
            return;
        }

        return new AddressValue(json_decode($value, true));
    }

    public function set($model, $key, $value, $attributes)
    {
        if (is_null($value)) {
            return;
        }

        if (is_array($value)) {
            $value = new AddressValue($value);
        }

        if (! $value instanceof AddressValue) {
            throw new \InvalidArgumentException(
                'Value must be of type Address, array, or null'
            );
        }

        return json_encode($value->toArray());
    }
}

Now we cast in the model like this:

use App\Casts\Address;

protected $casts = [
    'address' => Address::class,
];

That is already a big step up: we get a typed object instead of an array. But we can do better.

Making the Value Object Castable

Instead of pointing the model at a separate caster class, Laravel lets a class implement the Castable interface and tell the world how to cast itself:

namespace App\Values;

use App\Casts\Address as AddressCast;
use Illuminate\Contracts\Database\Eloquent\Castable;

class Address implements Castable
{
    public static function castUsing(array $arguments)
    {
        return AddressCast::class;
    }
}

Now the model casts directly to the value object class:

use App\Values\Address;

protected $casts = [
    'address' => Address::class,
];

That feels cleaner. The value object owns its casting logic instead of relying on an external caster that the developer has to remember to link.

Enter Spatie's DTO Package

Spatie's Data Transfer Object package (superseded by Laravel Data, but still instructive) gives us typed, validated properties:

composer require spatie/data-transfer-object

namespace App\Values;

use App\Casts\Address as AddressCast;
use Illuminate\Contracts\Database\Eloquent\Castable;
use Spatie\DataTransferObject\DataTransferObject;

class Address extends DataTransferObject implements Castable
{
    public string $street;
    public string $suburb;
    public string $state;

    public static function castUsing(array $arguments)
    {
        return AddressCast::class;
    }
}

Now if someone tries to set $address->street to an integer, an exception is thrown. The structure is enforced, not assumed.

Making the Caster Reusable

Look at the caster from earlier. Nothing in it is specific to the Address class except the class name reference. If we have multiple value objects, we would be duplicating the same casting logic for each one. Instead, parameterise it:

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

class DataTransferObject implements CastsAttributes
{
    protected string $class;

    public function __construct(string $class)
    {
        $this->class = $class;
    }

    public function get($model, $key, $value, $attributes)
    {
        if (is_null($value)) {
            return;
        }

        return new $this->class(json_decode($value, true));
    }

    public function set($model, $key, $value, $attributes)
    {
        if (is_null($value)) {
            return;
        }

        if (is_array($value)) {
            $value = new $this->class($value);
        }

        if (! $value instanceof $this->class) {
            throw new \InvalidArgumentException(
                "Value must be of type [{$this->class}], array, or null"
            );
        }

        return json_encode($value->toArray());
    }
}

Now your value object's castUsing() becomes:

use App\Casts\DataTransferObject;

public static function castUsing(array $arguments)
{
    return new DataTransferObject(Address::class);
}

One general-purpose caster, any DTO class.

An Abstract Castable DTO

We can go one step further and create an abstract base class that any value object can extend. This eliminates the boilerplate of implementing Castable on every class:

namespace App\Values;

use App\Casts\DataTransferObject as DataTransferObjectCast;
use Illuminate\Contracts\Database\Eloquent\Castable;
use Spatie\DataTransferObject\DataTransferObject;

abstract class CastableDataTransferObject extends DataTransferObject implements Castable
{
    public static function castUsing()
    {
        return new DataTransferObjectCast(static::class);
    }

    public function toJson(): string
    {
        return json_encode($this->toArray());
    }

    public static function fromJson(string $json): static
    {
        return new static(json_decode($json, true));
    }
}

The toJson() and fromJson() methods keep serialization with the value object. And because they are on the abstract class, every extending value object gets them for free.

Now the Address class is just:

namespace App\Values;

class Address extends CastableDataTransferObject
{
    public string $street;
    public string $suburb;
    public string $state;
}

The Final Setup

You end up with three files:

app/Casts/DataTransferObject.php          # The generic caster
app/Values/CastableDataTransferObject.php # The abstract base class
app/Values/Address.php                    # Your actual value object

And the model casts are as clean as it gets:

protected $casts = [
    'address' => Address::class,
];

Querying JSON columns works natively:

$residents = User::where('address->suburb', 'Hill Valley')->get();

Creating records accepts either an array or the value object directly:

User::create([
    'name'    => 'Emmett Brown',
    'address' => [
        'street' => '1640 Riverside Drive',
        'suburb' => 'Hill Valley',
        'state'  => 'California',
    ],
]);

Once retrieved, $user->address is a full-fledged value object with the methods you define on it.

Key Takeaways

• JSON columns are great for nested or optional data, but raw arrays lack safety and expressiveness.
• Custom casts bridge the gap between the database and typed objects.
• The Castable interface lets value objects declare how they should be cast without the model knowing the details.
• A single generic caster serves every DTO in your app. No more one-off caster classes.
• An abstract base class eliminates the boilerplate so new value objects are trivial to create.

The result is a clean separation: value objects own their shape, their validation, and their behaviour. Eloquent handles persistence. And your application code talks to rich, meaningful objects instead of loose arrays.

php artisan queue:restart

It works by writing an illuminate:queue:restart key to your cache store with a timestamp. Workers check this key after finishing each job. If the timestamp is newer than when they last checked, the worker process exits gracefully, and your process manager starts a fresh one.

If you are using Laravel Forge, you can check a worker's uptime. After a successful restart, you will see something like:

worker-:worker-_00   RUNNING   pid 75, uptime 0 days, 00:00:20

That is a brand new process. If the worker's uptime is much longer than expected after you ran queue:restart, something is preventing the restart. Here are the usual culprits.

1. The Worker Is Running in Listen Mode

If you started the worker with queue:listen instead of queue:work, the listener spawns a separate child process for every job. Once the job finishes, the child process is killed and a new one is created for the next job. This means every job already runs with the latest code. The listener has no persistent state to clear, so queue:restart has zero effect on it.

The only way to restart a listener process is manually:

supervisorctl restart worker-name:*

If you are relying on queue:restart and wondering why nothing happens, check whether your workers are running in listen mode versus daemon mode.

2. The Cache Store Is Not Shared or Accessible

For queue:restart to work, every worker process needs to read from the same cache store where the restart timestamp is written. If your workers are on different machines or different cache configurations, they will not see the key.

A common variant: the queue:restart command writes the key using one cache driver, but the workers read from another. Both sides need to agree on the same CACHE_DRIVER and the same backend (same Redis database, same Memcached server, same filesystem).

File cache driver gotcha: If you are using the file cache driver, the user running queue:restart must be able to write the cache file, and the user running the worker processes must be able to read it. Permission issues here will silently break the restart:

sudo chown -R forge:forge storage/framework/cache

This ensures the cache directory is owned by the forge user. If both the deploy script and the workers run as forge, everything works.

3. The Cache Prefix Changed

If you change the cache prefix in config/cache.php (or via CACHE_PREFIX), the restart command writes the illuminate:queue:restart key under the new prefix. Existing workers still look for the key under the old prefix. They never see the updated timestamp, so they never restart.

This is a one-time problem. After you change the prefix, you need to restart the workers manually once to pick up the new prefix:

supervisorctl restart worker-name:*

After that manual restart, subsequent queue:restart calls work normally because all processes now share the same prefix.

How queue:restart Actually Works

When you run queue:restart, Laravel updates the illuminate:queue:restart timestamp in the cache to the current time.

Inside the worker daemon loop, stopIfNecessary() runs after each job and calls queueShouldRestart():

protected function stopIfNecessary(WorkerOptions $options, $lastRestart)
{
    if ($this->shouldQuit) {
        $this->kill();
    }

    if ($this->memoryExceeded($options->memory)) {
        $this->stop(12);
    } elseif ($this->queueShouldRestart($lastRestart)) {
        $this->stop();
    }
}

queueShouldRestart() compares the stored $lastRestart timestamp (captured when the worker started) against the current value of the illuminate:queue:restart cache key. If the cached value is newer, the worker knows a restart was requested and exits.

The worker will not exit in the middle of processing a job. The check only happens between jobs. Once the current job finishes, the worker sees the new timestamp and stops. Supervisor detects the stopped process and starts a replacement.

Key Takeaways

• queue:restart only works with queue:work (daemon mode), not queue:listen.
• Workers must share the same cache store as the process running queue:restart.
• File cache permissions can silently prevent restarts. Check ownership of storage/framework/cache.
• Changing the cache prefix requires one manual restart to sync workers.
• The worker exits between jobs, not in the middle of one, so no jobs are lost during a restart.

If you want to create a Laravel project in 2026, the fastest reliable path is Laravel 13 + Docker + MySQL 8. This guide gives you a clean, repeatable setup for local development and a strong foundation for production.

By the end, you will have:

• A fresh Laravel 13 app.
• A Docker-based local environment.
• MySQL 8 wired and tested.
• A baseline structure ready for real feature work.

Prerequisites

Before creating the project, install the following:

• PHP 8.3+ (CLI).
• Composer 2.x.
• Docker Desktop.
• Git.

You can verify quickly:

php -v
composer -V
docker --version
git --version

Step 1: Create the Laravel 13 project

If you have the Laravel installer, use laravel new first:

laravel new laravel-starter

If you are not using the Laravel installer, use Composer as an alternative:

composer create-project laravel/laravel laravel-starter

Move into the project:

cd laravel-starter

Confirm the framework version:

php artisan --version

Step 2: Start with Laravel Sail (Docker)

Laravel Sail gives you an official Docker workflow without manually building every container from scratch.

Install Sail dependencies and publish Docker files:

composer require laravel/sail --dev
php artisan sail:install --with=mysql,redis,mailpit

Bring containers up:

./vendor/bin/sail up -d

To simplify commands, add an alias:

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Then use:

sail artisan about

Step 3: Configure .env for MySQL 8

After Sail install, your .env is mostly ready. Confirm key values:

APP_NAME="Laravel Starter"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password

Why DB_HOST=mysql? In Docker networking, mysql is the service hostname defined by Sail.

Step 4: Generate app key and run migrations

Run initial setup commands inside Sail:

sail artisan key:generate
sail artisan migrate

If migrations succeed, your Laravel app is correctly connected to MySQL 8.

Step 5: Validate your app works end to end

Open the app:

http://localhost

Run tests:

sail test

Check queue worker quickly (optional):

sail artisan queue:work --once

At this point, you have a healthy Laravel 13 project baseline.

Step 6: Create a production-friendly folder structure

A useful early pattern is to keep business logic out of controllers.

Suggested starter layout:

app/
  Actions/
  Services/
  Repositories/
  Http/Controllers/
  Http/Requests/

Keep it lightweight at first. Add layers only when they help clarity.

Step 7: Add quality defaults early

Install tools you will almost certainly need:

sail composer require laravel/pint --dev
sail composer require pestphp/pest --dev
sail artisan pest:install

Add a basic format-and-test routine:

sail pint
sail test

Starting clean prevents style drift as the project grows.

Step 8: Add your first feature route and controller

Create a simple health endpoint so you can validate deploys later:

sail artisan make:controller HealthController

routes/web.php:

use App\Http\Controllers\HealthController;
use Illuminate\Support\Facades\Route;

Route::get('/health', HealthController::class);

app/Http/Controllers/HealthController.php:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Response;

class HealthController extends Controller
{
    public function __invoke(): Response
    {
        return response('ok', 200);
    }
}

Now http://localhost/health should return ok.

Common setup mistakes (and fast fixes)

Docker-based workflow cheatsheet

# Start containers
sail up -d

# Stop containers
sail down

# Run migrations
sail artisan migrate

# Run tests
sail test

# Run queue worker
sail artisan queue:work

# Open shell in app container
sail shell

Why this setup works in 2026

• Docker keeps developer machines consistent.
• Laravel Sail stays close to Laravel defaults.
• MySQL 8 gives predictable SQL behavior for modern apps.
• Composer-based bootstrap keeps onboarding simple for teams.

This gives you a project that is easy to run, easy to hand off, and ready for CI/CD.

FAQ

Should I use Sail or run PHP directly on my machine?

For solo experiments, either works. For team projects and predictable onboarding, Sail is usually better.

Do I need Redis on day one?

Not mandatory, but enabling it early is useful for queues, caching, and later scaling.

Can I switch from MySQL to PostgreSQL later?

Yes, but database-specific SQL and indexes may need updates. If you expect a switch, avoid engine-specific behavior early.

Is this setup production-ready?

It is production-minded, not production-complete. You still need deployment, monitoring, backups, and security hardening.

Final takeaway

If your goal is to create a Laravel project quickly without sacrificing quality, use Laravel 13 with Sail, Docker, and MySQL 8. You will move faster now and avoid painful environment mismatches later.

Next in this series: How to Run Raw SQL Queries in Laravel with DB::raw and the upcoming Laravel .env guide.

When your Laravel app works locally, deployment is the next real milestone. In this guide, you will deploy Laravel 13 with MySQL 8 using three practical options: shared hosting, VPS with Docker, and Laravel Forge.

You will also get a production checklist so you avoid common mistakes like broken permissions, leaked debug pages, and queue workers not running.

Deployment options at a glance

If you are new to Laravel setup, read Create a New Laravel 13 Project in 2026 first. For config hardening, pair this with Laravel .env Explained.

Pre-deploy production checklist

Before any deployment method, confirm these baseline settings:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com
LOG_CHANNEL=stack
QUEUE_CONNECTION=database
CACHE_STORE=redis
SESSION_DRIVER=redis

And run:

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan migrate --force

Key checks:

• .env is not in git.
• storage and bootstrap/cache are writable by the web user.
• Queue workers and scheduler are configured.
• HTTPS is enabled.

Path 1: Deploy on shared hosting

Shared hosting can run Laravel if you structure files correctly.

Typical flow:

1. Upload project files outside public_html.
2. Point web root to Laravel public/.
3. Set production .env values.
4. Run composer install via SSH (if available).
5. Run migrations and cache commands.

Recommended command set:

composer install --no-dev --optimize-autoloader
php artisan key:generate --force
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

If your host does not provide CLI access, shared hosting becomes painful quickly. In that case, move to Forge or a VPS.

Path 2: Deploy on VPS with Docker

This is ideal when you want predictable environments and full control.

1) Minimal docker-compose.yml

services:
  app:
    image: ghcr.io/your-org/laravel-app:latest
    env_file:
      - .env
    depends_on:
      - mysql
      - redis
    networks:
      - app-net

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app
    networks:
      - app-net

  mysql:
    image: mysql:8
    environment:
      MYSQL_DATABASE: laravel
      MYSQL_USER: laravel
      MYSQL_PASSWORD: secret
      MYSQL_ROOT_PASSWORD: root-secret
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - app-net

  redis:
    image: redis:7-alpine
    networks:
      - app-net

networks:
  app-net:

volumes:
  mysql-data:

2) Build and release pipeline

Use CI to build image, then pull on server.

docker compose pull
docker compose up -d --remove-orphans
docker compose exec app php artisan migrate --force
docker compose exec app php artisan config:cache

3) Queue workers and scheduler

Run queue workers using Supervisor or an extra container.

Scheduler example (cron on host):

* * * * * cd /var/www/laravel && docker compose exec -T app php artisan schedule:run >> /dev/null 2>&1

Path 3: Deploy with Laravel Forge

Forge is the fastest way to run Laravel on managed VPS infrastructure.

Core setup:

1. Provision server in Forge.
2. Create a site and connect your Git repo.
3. Add environment variables in Forge dashboard.
4. Configure deployment script.
5. Enable queue worker and scheduler.

Sample Forge deploy script:

cd /home/forge/yourdomain.com

git pull origin main
composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart

For many teams, Forge gives the best speed-to-production balance.

Zero-downtime deployment basics

Even simple apps should avoid visible downtime during deploy.

Good practices:

• Build assets before switch-over.
• Run migrations that are backward-compatible first.
• Restart workers after code deploy.
• Avoid destructive schema changes in a single release step.

If using symlink-based release directories, switch symlink only after health checks pass.

Security and reliability hardening

Minimum production hardening:

• Enable firewall (ufw) and only allow required ports.
• Disable password SSH login, use SSH keys.
• Enforce TLS certificates (LetsEncrypt).
• Back up MySQL daily and test restore.
• Use separate DB users per environment.

Monitor these metrics:

• 5xx error rate
• Queue lag
• DB CPU and slow queries
• Disk usage and backup success

Common deployment mistakes

Post-deploy verification checklist

After each deploy:

1. Open /health and main app routes.
2. Confirm migrations succeeded.
3. Confirm queue jobs process successfully.
4. Check logs for exceptions in first 10 minutes.
5. Confirm scheduler runs at least one cycle.

A quick smoke test after each release catches most production incidents early.

FAQ

Which deployment path should I pick in 2026?

If you want speed and less infrastructure overhead, pick Forge. If you need full control and portability, pick VPS + Docker. Use shared hosting only for small low-risk projects.

Do I need Docker for Laravel deployment?

No, but Docker improves consistency across environments and teams.

Should I run php artisan migrate --force on every deploy?

Usually yes, as part of your deployment script, as long as your migrations are safe and reviewed.

How do I avoid downtime during schema changes?

Use additive, backward-compatible migrations first, deploy code that supports both old and new schema, then clean up in a later release.

Final takeaway

Laravel deployment is easiest when you standardize your process. Pick one path, automate it, and verify every release with a checklist. In Laravel 13, consistent environment handling and safe migrations are what separate stable deployments from stressful ones.

Next in this series: How to Run Raw SQL Queries in Laravel with DB::raw and the upcoming Laravel Project Lifecycle pillar.

If you are building real Laravel apps, there will be moments when Eloquent alone is not enough. That is where DB::raw and raw query helpers come in. In this guide, you will learn exactly when to use Laravel db raw patterns in Laravel 13 with MySQL 8, how to keep them safe, and how to avoid performance mistakes.

This is part of a broader Laravel project lifecycle series. If you are just getting started, read the upcoming guides on creating a Laravel project, managing .env safely, and deployment patterns.

What is DB::raw in Laravel?

DB::raw lets you pass a raw SQL expression into the query builder when Laravel does not provide a clean fluent method for what you need.

Use it when you need:

• SQL expressions like CASE, COALESCE, or arithmetic operations.
• Database-specific functions in MySQL 8.
• Advanced ordering and reporting queries.

Avoid it when a regular query builder or Eloquent method can express the same query clearly.

DB::raw vs selectRaw vs whereRaw vs Eloquent

Quick rule of thumb:

In practice, prefer selectRaw, whereRaw, and friends over directly scattering DB::raw everywhere. They are easier to read and support parameter bindings in a predictable way.

Example 1: Aggregate totals with aliases

You need monthly revenue and order count for a dashboard.

use Illuminate\Support\Facades\DB;

$stats = DB::table('orders')
    ->selectRaw('DATE_FORMAT(created_at, "%Y-%m") as month')
    ->selectRaw('COUNT(*) as orders_count')
    ->selectRaw('SUM(total_amount) as revenue_total')
    ->where('status', 'paid')
    ->groupByRaw('DATE_FORMAT(created_at, "%Y-%m")')
    ->orderBy('month')
    ->get();

Why raw here? MySQL date formatting for grouped reporting is easier in SQL than in PHP post-processing.

Example 2: Computed status column with CASE

You want a label derived from multiple columns.

$users = DB::table('users')
    ->select('id', 'name', 'last_login_at')
    ->selectRaw('
        CASE
            WHEN last_login_at IS NULL THEN "never"
            WHEN last_login_at >= NOW() - INTERVAL 30 DAY THEN "active"
            ELSE "inactive"
        END as activity_status
    ')
    ->get();

This keeps business reporting logic in one query and avoids loops over large datasets.

Example 3: Custom sorting with orderByRaw

Sort by business priority first, then by recency.

$tickets = DB::table('support_tickets')
    ->select('id', 'subject', 'priority', 'created_at')
    ->orderByRaw('
        FIELD(priority, "critical", "high", "medium", "low")
    ')
    ->orderByDesc('created_at')
    ->get();

FIELD(...) is a MySQL-specific helper that is perfect for custom order rules.

Example 4: Grouped reports with havingRaw

Find product categories with meaningful sales volume.

$categories = DB::table('order_items')
    ->join('products', 'products.id', '=', 'order_items.product_id')
    ->select('products.category_id')
    ->selectRaw('COUNT(*) as line_count')
    ->selectRaw('SUM(order_items.quantity * order_items.unit_price) as gross_sales')
    ->groupBy('products.category_id')
    ->havingRaw('SUM(order_items.quantity * order_items.unit_price) > ?', [10000])
    ->orderByDesc('gross_sales')
    ->get();

Notice the binding in havingRaw. Never interpolate dynamic values into raw SQL strings.

Example 5: Safe whereRaw with bindings

Use raw conditions with placeholders, not string concatenation.

$minAge = 21;
$country = 'KE';

$customers = DB::table('customers')
    ->whereRaw('TIMESTAMPDIFF(YEAR, date_of_birth, CURDATE()) >= ?', [$minAge])
    ->whereRaw('country_code = ?', [$country])
    ->get();

This pattern protects you from SQL injection and keeps query plans reusable.

Security: how to use raw SQL safely

When people say raw SQL is dangerous in Laravel, they usually mean unsafe interpolation.

Good:

DB::table('users')->whereRaw('email = ?', [$email])->first();

Bad:

DB::table('users')->whereRaw("email = '$email'")->first();

Use this checklist whenever you write raw SQL:

• Always pass dynamic values as bindings (?, then array values).
• Keep raw fragments small and focused.
• Validate and sanitize upstream inputs as usual.
• Never allow unchecked user input to control SQL keywords (column names, ORDER BY, etc.).

For framework-level guidance, see the official Laravel query documentation: Laravel Query Builder.

Performance notes for MySQL 8

Raw SQL can be faster or slower depending on how you write it. Treat performance as a measurement problem.

1. Inspect execution plans with EXPLAIN for expensive queries.
2. Add indexes that match your filter and join patterns.
3. Avoid wrapping indexed columns in functions inside WHERE if you need index usage.
4. Aggregate in SQL when possible, but avoid over-fetching rows.

You can profile query timings quickly in local development:

DB::listen(function ($query) {
    logger()->info('sql', [
        'sql' => $query->sql,
        'bindings' => $query->bindings,
        'time_ms' => $query->time,
    ]);
});

Testing raw query logic in Laravel 13

For reporting queries, test both shape and values.

it('returns active users first in priority report', function () {
    // Arrange test records...

    $rows = DB::table('users')
        ->select('id')
        ->orderByRaw('FIELD(status, "active", "invited", "disabled")')
        ->get();

    expect($rows)->not->toBeEmpty();
    expect($rows->first()->id)->toBe(1);
});

If you have a complex query, consider wrapping it in a repository method so your tests target one boundary instead of duplicating SQL across the codebase.

Common mistakes and fixes

FAQ

Is DB::raw bad practice?

No. It is a tool. It becomes a problem only when overused or written unsafely. Use raw SQL when it improves clarity or performance, and keep standard queries in Eloquent/query builder.

Can I use bindings with raw helpers?

Yes. whereRaw, havingRaw, selectRaw, and similar helpers support bindings. Prefer them over manually injecting variables into SQL strings.

Should I use DB::raw for everything advanced?

Not always. Start with query builder or Eloquent. Use raw expressions for the parts that are truly SQL-specific.

Does DB::raw lock me into MySQL?

Sometimes. Functions like FIELD and DATE_FORMAT are MySQL-specific. If portability matters, isolate database-specific logic behind dedicated query methods.

Final takeaway

If you use Laravel db raw patterns carefully, they are an advantage, not a risk. In Laravel 13 with MySQL 8, raw expressions are especially useful for reporting, computed fields, and custom sorting, as long as you bind values and verify performance.

Next in this series: Create a New Laravel Project in 2026.

If you use Laravel 13 in real projects, your .env file becomes one of the most important files in the entire app. It controls application behavior, database access, mail credentials, queues, cache drivers, and more.

In this guide, you will learn how Laravel environment variables work, how to avoid common mistakes, and how to safely manage .env from local development to production.

What is .env in Laravel?

The .env file stores environment-specific values outside your codebase. Laravel reads these values at boot, then maps them into config files using env() calls.

Example:

APP_NAME="My Laravel App"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

This keeps secrets and environment differences out of source-controlled PHP files.

How Laravel uses environment values

Laravel does not expect you to call env() all over your app code. Best practice is:

1. Read env vars in config files only (config/*.php).
2. Access values in app code via config('...').

Example in config/database.php:

'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    'database' => env('DB_DATABASE', 'laravel'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
],

Then in your app logic:

$driver = config('database.default');

This avoids surprises when you cache config in production.

The env() helper: when to use it and when not to

The env() helper is for configuration loading, not general runtime logic.

Use it here:

• Inside files in config/*.php.
• While defining default configuration values.

Avoid it here:

• Controllers, services, jobs, commands, and listeners.
• Blade templates and domain logic.

Good pattern:

// config/services.php
'postmark' => [
    'token' => env('POSTMARK_TOKEN'),
],

// app/Services/MailerService.php
$token = config('services.postmark.token');

Why this matters: after php artisan config:cache, Laravel reads cached config values, so direct runtime env() calls can return unexpected values.

Environment detection in Laravel

Laravel primarily determines environment via APP_ENV, and you can inspect it using:

app()->environment();
app()->environment('local');

For CLI execution, Laravel also supports explicit environment overrides:

php artisan migrate --env=staging
php artisan migrate --env staging

Behavior to remember (matching framework detector tests):

• --env=local uses local.
• --env local uses local.
• --env with no value falls back to normal detection.
• Similar flags like --envelope=mail are ignored.

You can also provide custom detection logic in lower-level bootstrapping scenarios:

use Illuminate\Foundation\EnvironmentDetector;

$detector = new EnvironmentDetector;

$environment = $detector->detect(function () {
    return 'production';
}, $_SERVER['argv'] ?? []);

In most applications, APP_ENV plus standard Laravel bootstrapping is enough.

Encrypting and decrypting environment files

For teams, Laravel supports encrypted environment files so secrets are not stored in plaintext when shared.

Encrypt your current .env file:

php artisan env:encrypt

Decrypt later:

php artisan env:decrypt

Useful notes:

• Encryption generates an encrypted env artifact (for example, .env.encrypted).
• Decryption requires the correct key, usually provided via CLI option or environment variable.
• Do not commit plaintext .env; if you commit encrypted env files, protect keys in your secret manager.

This is especially useful when distributing secure defaults across multiple environments.

Writing variables to an environment file programmatically

In recent Laravel versions, you can write/update env variables using Env::writeVariables.

Example:

use Illuminate\Support\Env;

Env::writeVariables([
    'APP_VIBE' => 'chill',
    'DB_HOST' => '127:0:0:1',
    'DB_PORT' => 3306,
    'BRAND_NEW_PREFIX' => 'fresh value',
], base_path('.env'));

Overwrite existing keys explicitly:

Env::writeVariables([
    'DB_CONNECTION' => 'sqlite',
    'DB_HOST' => '127:0:0:1',
], base_path('.env'), true);

Practical guidance:

• Use this in setup/install flows, not normal request handling.
• Keep backups when mutating env files in automation.
• Validate generated env content in CI to avoid broken deploys.

Recommended .env baseline for Laravel 13 + MySQL 8

APP_NAME=Laravel
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

APP_LOCALE=en
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=en_US

APP_MAINTENANCE_DRIVER=file
# APP_MAINTENANCE_STORE=database

# PHP_CLI_SERVER_WORKERS=4

BCRYPT_ROUNDS=12

LOG_CHANNEL=stack
LOG_STACK=single
LOG_DEPRECATIONS_CHANNEL=null
LOG_LEVEL=debug

DB_CONNECTION=sqlite
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=laravel
# DB_USERNAME=root
# DB_PASSWORD=

SESSION_DRIVER=database
SESSION_LIFETIME=120
SESSION_ENCRYPT=false
SESSION_PATH=/
SESSION_DOMAIN=null

BROADCAST_CONNECTION=log
FILESYSTEM_DISK=local
QUEUE_CONNECTION=database

CACHE_STORE=database
# CACHE_PREFIX=

MEMCACHED_HOST=127.0.0.1

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_MAILER=log
MAIL_SCHEME=null
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=
AWS_USE_PATH_STYLE_ENDPOINT=false

VITE_APP_NAME="${APP_NAME}"

For Docker/Sail setups, DB_HOST=mysql is correct because mysql is the container service name.

.env vs .env.example (and why both matter)

• .env is your real, local or server-specific config file.
• .env.example is the template committed to git for teammates and CI.

Every key in .env that others need should exist in .env.example with a safe placeholder.

Example:

APP_NAME="Laravel Starter"
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=

Critical security rules for .env

Treat your .env like credentials, because it often contains credentials.

• Never commit .env to git.
• Never paste secrets in screenshots, PR descriptions, or logs.
• Rotate keys immediately if exposure happens.
• Use separate credentials per environment (local, staging, production).
• Keep production secrets in a secret manager or platform env settings.

Quick check:

git check-ignore -v .env

If .env is not ignored, fix .gitignore before doing anything else.

Why APP_DEBUG must be false in production

APP_DEBUG=true can leak sensitive internals (queries, stack traces, server paths).

Production minimum:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

That one setting alone prevents a lot of accidental data exposure.

Config cache and env gotchas

When you run:

php artisan config:cache

Laravel compiles configuration into a cached file. If you update .env, changes may not be reflected until you clear/rebuild cache.

Useful commands:

php artisan config:clear
php artisan cache:clear
php artisan config:cache

If your app seems to ignore .env updates, cached config is usually the reason.

Local, staging, and production strategy

A practical approach for 2026:

• Local: .env file on your machine, Docker/Sail defaults.
• Staging: environment vars set in hosting platform or deploy pipeline.
• Production: environment vars set in secure secret storage, never in repo.

This makes environment promotion predictable and auditable.

Common .env mistakes and fixes

Quick sanity checklist before deploy

1. APP_ENV=production and APP_DEBUG=false.
2. Production DB credentials are not shared with staging/local.
3. .env is not tracked by git.
4. Config cache is rebuilt after env changes.
5. Queue workers are restarted after deployment.

FAQ

Should .env ever be committed?

No. Commit .env.example only.

Is it okay to call env() in controllers or services?

Avoid it. Use config() in application code so behavior remains stable with cached config.

Where should production secrets live?

In your platform secret manager or runtime environment configuration, not in files inside the repository.

Do I need different .env values per environment?

Yes. Local, staging, and production should each use separate values and credentials.

Final takeaway

If you get .env management right early, you avoid painful deployment bugs and major security risks later. In Laravel 13, keep env values in config files, keep secrets out of git, and treat production settings as sensitive infrastructure data.

Next in this series: Create a New Laravel 13 Project in 2026, DB::raw guide, and the upcoming Laravel deployment guide.

Let us walk through how that happens and how to pull it back.

The Slow Descent

You start with the happy path:

public function store()
{
    $user = new User(Input::all());
    $user->save();

    return View::make('account-created');
}

Straightforward, but fragile. So you add error handling:

public function store()
{
    $user = new User(Input::all());

    if (! $user->save()) {
        return Redirect::to('/users/create')
            ->with('message', 'Something went wrong!');
    }

    return View::make('account-created');
}

Then someone submits without a password. So validation gets tacked on:

public function store()
{
    $input = Input::all();

    $rules = [
        'email'        => ['required', 'email', 'unique:users'],
        'password'     => ['required', 'confirmed', 'min:6'],
        'first_name'   => ['required'],
        'last_name'    => ['required'],
        'date_of_birth'=> ['required', 'date'],
    ];

    $validation = Validator::make($input, $rules);

    if ($validation->fails()) {
        return Redirect::to('/users/create')
            ->withErrors($validation)
            ->withInput();
    }

    $user = new User($input);

    if (! $user->save()) {
        return Redirect::to('/users/create')
            ->with('message', 'Something went wrong!');
    }

    return View::make('account-created');
}

Now the controller is stuffed with logic that has nothing to do with handling HTTP. It is defining form rules, running validations, managing redirects for multiple failure modes, and persisting records. None of that belongs here.

The Core Mistake

The trap is thinking of "model" as only "a class that maps to a database table." That thinking forces every piece of business logic into either a controller (wrong) or an Eloquent model (often wrong too, since your model should not care about form validation rules or redirect URLs).

You are allowed to make classes that do not correspond to tables. In fact, that is where most of your application's real code should live.

Extract a Form Class

Look at that controller again. The validation section is the biggest chunk of noise:

$input = Input::all();

$rules = array (...);

$validation = Validator::make($input, $rules);

if ($validation->fails()) {
    return Redirect::to('/users/create')
        ->withErrors($validation)
        ->withInput();
}

All of that is about the form: what input it expects and whether that input is valid. So why is there not a UserRegistrationForm class?

class UserRegistrationForm
{
    private $rules = [
        'email'        => ['required', 'email', 'unique:users'],
        'password'     => ['required', 'confirmed', 'min:6'],
        'first_name'   => ['required'],
        'last_name'    => ['required'],
        'date_of_birth'=> ['required', 'date'],
    ];

    private $attributes;
    private $validation;

    public function __construct(array $attributes)
    {
        $this->attributes = $attributes;
    }

    public function isInvalid()
    {
        return ! $this->isValid();
    }

    public function isValid()
    {
        $this->validation = Validator::make(
            $this->attributes,
            $this->rules
        );

        return $this->validation->passes();
    }

    public function getValidation()
    {
        return $this->validation;
    }
}

Now the controller looks like this:

public function store()
{
    $form = new UserRegistrationForm(Input::all());

    if ($form->isInvalid()) {
        return Redirect::to('/users/create')
            ->withErrors($form->getValidation())
            ->withInput();
    }

    $user = new User(Input::all());

    if (! $user->save()) {
        return Redirect::to('/users/create')
            ->with('message', 'Something went wrong!');
    }

    return View::make('account-created');
}

Already a big improvement. The validation rules live with the form, not the controller. The controller just asks "is this valid?" and acts on the answer.

Going Further: Give the Form the Save Behaviour

Since the form already knows what valid input looks like, it might as well know how to turn that input into a user. Pull the save logic in too:

class UserRegistrationForm
{
    // ...

    public function save()
    {
        if ($this->isInvalid()) {
            return false;
        }

        $user = new User($this->attributes);

        return $user->save();
    }
}

And now the controller becomes genuinely thin:

public function store()
{
    $form = new UserRegistrationForm(Input::all());

    if (! $form->save()) {
        return Redirect::to('/users/create')
            ->withErrors($form->getValidation())
            ->withInput();
    }

    return View::make('account-created');
}

That is it. The controller handles HTTP input, decides what to do next, and returns a response. The form object handles validation and persistence. If the business rules change, you change the form object, not the controller.

What We Actually Did

This refactoring is just moving code to the right bucket. The form object is a plain PHP class with no framework inheritance. It does not extend Eloquent, it does not extend Controller. It represents the concept of "a user registration form" and knows what to do with the data it receives.

This is the foundation of patterns you will see everywhere in mature Laravel applications:

• Form requests: Laravel's own evolution of this idea, shipping validated input straight to your controller.
• Command objects: classes that encapsulate a single operation (register a user, place an order, cancel a subscription).
• Action classes: the same concept under a different name, popularised by Laravel 11's make:action.

All of these patterns solve the same core problem: controllers should orchestrate, not implement. Push the logic downstream to plain PHP classes that are testable, reusable, and have one job.

Key Takeaways

• Do not equate "model" with "table." Your application is encouraged to have classes that do not map to database rows.
• Controllers should be thin. If your controller action has validation rules, error handling, user creation, and email sending, you have put everything in the wrong place.
• Form objects or command objects encapsulate a single operation and keep your controllers readable.
• When a controller action feels crowded, extract the domain logic into its own class first. The right name will make the code obvious.

A Quick Example

From the official docs:

$batch = Bus::batch([
    new ProcessPodcast(Podcast::find(1)),
    new ProcessPodcast(Podcast::find(2)),
    new ProcessPodcast(Podcast::find(3)),
    new ProcessPodcast(Podcast::find(4)),
    new ProcessPodcast(Podcast::find(5)),
])->then(function (Batch $batch) {
    // All jobs completed successfully...
})->catch(function (Batch $batch, Throwable $e) {
    // First batch job failure detected...
})->finally(function (Batch $batch) {
    // The batch has finished executing...
})->name('Process Podcasts')
  ->allowFailures(false)
  ->onConnection('redis')
  ->onQueue('podcasts')
  ->dispatch();

Storing the Batch

When you call dispatch(), the batch information is written to the database first. The store() method in Illuminate\Bus\DatabaseBatchRepository inserts a row:

$this->connection->table($this->table)->insert([
    'id'            => $id,
    'name'          => $batch->name,
    'total_jobs'    => 0,
    'pending_jobs'  => 0,
    'failed_jobs'   => 0,
    'failed_job_ids'=> '[]',
    'options'       => serialize($batch->options),
    'created_at'    => time(),
    'cancelled_at'  => null,
    'finished_at'   => null,
]);

Each batch gets a UUID and an optional name. The options array holds everything else: the closures passed to then(), catch(), and finally(), plus allowFailures, onConnection, and onQueue settings. Closures are serialized using Opis\Closure\SerializableClosure so they survive the database round trip.

Dispatching the Jobs

Once the batch record exists, Laravel attaches the batch ID to every job and dispatches them all at once using the queue's bulk() method:

$jobs->each->withBatchId($this->id);

$this->repository->incrementTotalJobs($this->id, count($jobs));

$this->queue
    ->connection($this->options['connection'] ?? null)
    ->bulk($jobs->all(), $data = '', $this->options['queue'] ?? null);

The total job count is incremented in the database so Laravel can later determine when the batch is done. Using bulk() means all jobs are sent to the queue store in a single transaction, rather than dispatching them one by one.

Monitoring the Batch

On Success

After each successful job execution, recordSuccessfulJob() is called. It decrements the pending count and checks whether callbacks should fire:

$counts = $this->decrementPendingJobs($jobId);

if ($counts->pendingJobs === 0) {
    $this->repository->markAsFinished($this->id);
}

if ($counts->pendingJobs === 0 && $this->hasThenCallbacks()) {
    collect($this->options['then'])->each(/* Invoke */);
}

if ($counts->allJobsHaveRanExactlyOnce() && $this->hasFinallyCallbacks()) {
    collect($this->options['finally'])->each(/* Invoke */);
}

When there are no more pending jobs, Laravel marks the batch as finished by writing to the finished_at timestamp. Any then callbacks are triggered if everything ran successfully, and any finally callbacks fire once every job has been attempted at least once.

On Failure

When a job exhausts all its attempts, recordFailedJob() is called:

$counts = $this->incrementFailedJobs($jobId);

if ($counts->failedJobs === 1 && ! $this->allowsFailures()) {
    $this->cancel();
}

if ($counts->failedJobs === 1 && $this->hasCatchCallbacks()) {
    $batch = $this->fresh();
    collect($this->options['catch'])->each(/* Invoke */);
}

if ($counts->allJobsHaveRanExactlyOnce() && $this->hasFinallyCallbacks()) {
    $batch = $this->fresh();
    collect($this->options['finally'])->each(/* Invoke */);
}

If the batch does not allow failures, the first failure cancels the entire batch, and the cancelled_at field gets set to the current timestamp. The catch callback fires only on the first failure, and finally fires once all jobs have had at least one attempt.

Both recordSuccessfulJob() and recordFailedJob() are called from within Illuminate\Queue\CallQueuedHandler.

Exploring Further

If you want to dig deeper into the batch system, the key classes are:

• Illuminate\Bus\Dispatcher::batch(): entry point for creating batches.
• Illuminate\Bus\PendingBatch: the fluent builder you chain methods on.
• Illuminate\Bus\DatabaseBatchRepository: handles database storage and tracking.
• Illuminate\Bus\Batch: the in-memory representation of a running batch.

queue:work vs queue:listen

There are two commands for running workers, and the difference matters.

• php artisan queue:work boots your Laravel application once and keeps the same instance alive indefinitely to process jobs. This is efficient, since you are not rebuilding the framework on every job, but it also means you need to restart the worker manually after any code change for the change to take effect.
• php artisan queue:work --once boots the app, processes a single job, and dies.
• php artisan queue:listen runs queue:work --once inside an infinite loop. Every job gets a fresh application instance. Code changes are picked up automatically because each iteration is a new process, but you pay the price of booting the framework on every single job.

Inside queue:work

The handle() method of Queue\Console\WorkCommand is where it starts.

Maintenance Mode

If the app is in maintenance mode and --once is set, the worker just sleeps for the configured duration and dies gracefully:

if ($this->downForMaintenance() && $this->option('once')) {
    return $this->worker->sleep($this->option('sleep'));
}

Without that sleep, a supervising process (like Supervisor) would restart the worker instantly on every loop iteration, creating a tight restart cycle that burns CPU for nothing.

Event Listeners

The command registers listeners for three events right before the main loop starts:

$this->laravel['events']->listen(JobProcessing::class, function ($event) {
    $this->writeOutput($event->job, 'starting');
});

$this->laravel['events']->listen(JobProcessed::class, function ($event) {
    $this->writeOutput($event->job, 'success');
});

$this->laravel['events']->listen(JobFailed::class, function ($event) {
    $this->writeOutput($event->job, 'failed');
    $this->logFailedJob($event);
});

Failed jobs are logged via the queue.failer service, which by default stores the failure info (connection name, queue name, raw payload, and exception) in a failed_jobs database table.

Running the Worker

The runWorker() method collects the connection and queue options, sets a cache driver, then decides between two code paths:

• runNextJob(): used in --once mode, runs one job and exits.
• daemon(): used in persistent mode, keeps running.

The Daemon Loop

The Worker::daemon() method is where persistent workers live.

Signal Handling

If PHP 7.1+ with the pcntl extension is available, the worker registers async signal handlers:

pcntl_signal(SIGTERM, function () {
    $this->shouldQuit = true;
});

pcntl_signal(SIGUSR2, function () {
    $this->paused = true;
});

pcntl_signal(SIGCONT, function () {
    $this->paused = false;
});

• SIGTERM tells the worker to shut down (sent by Supervisor when you restart).
• SIGUSR2 pauses the worker.
• SIGCONT resumes a paused worker.

The Main Loop

The loop does this every iteration:

1. Check if the worker should run (not in maintenance mode, not paused, no listeners returning false).
2. If it should not run, sleep and check again.
3. Pull the next available job from the queue storage.
4. Register a timeout alarm so the process gets killed if the job takes too long.
5. Run the job.
6. Check if the worker needs to stop (SIGTERM received, memory limit hit, restart requested).

while (true) {
    if (! $this->daemonShouldRun($options, $connectionName, $queue)) {
        $this->pauseWorker($options, $lastRestart);
        continue;
    }

    $job = $this->getNextJob(
        $this->manager->connection($connectionName), $queue
    );

    $this->registerTimeoutHandler($job, $options);

    if ($job) {
        $this->runJob($job, $connectionName, $options);
    } else {
        $this->sleep($options->sleep);
    }

    $this->stopIfNecessary($options, $lastRestart);
}

Checking if the Worker Should Run

daemonShouldRun() checks:

• Application is not in maintenance mode (unless --force was passed).
• Worker is not paused.
• No event listener returned false from the Looping event.

That last check is useful: you can register a Looping listener that returns false to temporarily pause processing under certain conditions, like during a deployment window.

Fetching the Next Job

getNextJob() loops through the queues (you can specify multiple comma-separated queues) and asks the queue connection to pop a job:

foreach (explode(',', $queue) as $queue) {
    if (! is_null($job = $connection->pop($queue))) {
        return $job;
    }
}

The actual query looks for the oldest job that belongs to the target queue, is not already reserved, is available to run (not delayed), or has been reserved so long it may have frozen (retry timeout). Once found, the job is marked as reserved and its attempt count is incremented.

Monitoring Timeouts

If async signals are supported, the worker uses pcntl_alarm() to send a SIGALRM after the timeout period. If the job finishes in time, the next loop iteration resets the alarm. If the job hangs, the alarm fires and kills the process, and Supervisor starts a fresh one.

$timeout = $this->timeoutForJob($job, $options);
pcntl_alarm($timeout > 0 ? $timeout : 0);

Only one alarm can be active per process, so the next job's alarm replaces the previous one.

Processing a Job

process() fires the JobProcessing event, checks whether the job has already exceeded max attempts (and marks it failed if so), then calls $job->fire():

$this->raiseBeforeJobEvent($connectionName, $job);
$this->markJobAsFailedIfAlreadyExceedsMaxAttempts($connectionName, $job, (int) $options->maxTries);
$job->fire();
$this->raiseAfterJobEvent($connectionName, $job);

The $job object returned by getNextJob() is an implementation of Contracts\Queue\Job, for example, Queue\Jobs\DatabaseJob when using the database queue driver.

End-of-Loop Checks

After every job, stopIfNecessary() checks three things:

1. $this->shouldQuit: set by a SIGTERM signal or a lost database connection.
2. Memory exceeded: if the worker's memory usage passes the --memory limit, it stops. Memory leaks in long-running processes are real; this is the safety valve.
3. Queue restart requested: compares the stored restart timestamp against the current value. If they differ, someone ran php artisan queue:restart. The worker stops so it will be restarted with fresh code.

Key Takeaways

• queue:work boots the app once and stays alive: efficient but needs manual restarting after code changes.
• queue:listen boots the app on every job: picks up code changes automatically but costs more resources.
• Signal handling (SIGTERM, SIGUSR2, SIGCONT) lets Supervisor orchestrate the worker lifecycle.
• Timeouts use pcntl_alarm to kill hung jobs, on PHP 7.1+ only.
• Memory limits and restart signals keep long-running workers from degrading over time.
• The Looping event gives you a hook to pause processing during specific conditions.

Then I gave it this:

"nataka kuuza magunia 20 ya viazi gikomba"

"I want to sell 20 bags of potatoes at Gikomba."

It predicted:

pledge

Confidence:

99%.

The correct intent was:

sale_listing

That was the moment the project became interesting.

I am relatively new to machine learning. I built this classifier with AI coding agents doing most of the implementation. They wrote much of the training pipeline, synthetic data generators, serving stack, cloud training configuration, and parts of the analysis tooling.

Code arrived much faster than understanding.

That changed what I spent my time doing.

Instead of spending most of my time asking:

How do I implement this?

I increasingly found myself asking:

What would convince me that this is actually working?

That question uncovered a broken quantized model, a dataset shortcut, a leaky evaluation split, a taxonomy mismatch between the model and the application, and thousands of supposedly "real" messages that turned out to be load-test traffic.

The classifier is the thing I built.

Verification is the story.

I didn't need a better model

The system I was working on has a WhatsApp assistant that talks to food traders.

When a trader sends a free-form message, the application currently sends that message to Gemini 2.5 Flash. Gemini determines what the trader is trying to do and extracts the relevant information.

It works.

The problem was architectural rather than functional.

Every message that needed intent routing depended on a relatively large general-purpose model. That introduces latency and another dependency into a path where the answer is usually one of a finite set of intents.

So I started exploring a smaller encoder model that could run locally on CPU.

The idea was simple:

Use a small classifier for the common case. Fall back to Gemini when it isn't confident enough.

This wasn't primarily a cost optimization. The attraction was latency and resilience.

If the classifier could answer in single-digit milliseconds, we could potentially avoid paying the latency of a general-purpose model for every message while retaining Gemini as the fallback.

That sounds straightforward.

It wasn't.

First, I tried not training anything

Before generating a dataset, I tried zero-shot classification.

The idea was to give an NLI model the trader's message and a list of possible intent descriptions, then ask it to choose the most likely one.

It was useful as a baseline.

It was also clearly not good enough.

Some predictions were reasonable. Others were not. On a small benchmark, several messages landed on the wrong intent.

Then I tried something more interesting.

I tested a quantized model from a model hub.

It returned valid JSON.

It looked like a working classifier.

It wasn't.

Its predictions were effectively neutral: the same class kept winning with almost no meaningful separation between the logits.

This was a useful lesson because nothing about the output looked obviously broken.

The API worked.

The JSON was valid.

The model loaded.

The prediction looked plausible.

The model was wrong.

So I started putting acceptance tests around the model rather than trusting the existence of an output.

For model exports, I wanted to check things like:

• Does the exported model produce the same predictions?
• How different are the logits?
• Does accuracy remain intact?
• What happens to latency?
• Does quantization actually preserve the behavior I care about?

My own int8 export improved substantially through several attempts:

72% → 79% → 82% → 94.4% → 95.6% agreement

But my acceptance bar was 98%.

So I didn't ship it.

The fp32 ONNX model matched the PyTorch reference and ran at roughly 7 ms on CPU.

That was good enough.

The lesson wasn't "ONNX is great."

It was:

An optimization isn't an optimization until you measure what it preserved.

Then I had to create a dataset

The next problem was data.

I didn't have a clean labelled dataset of trader conversations ready to train on.

So I generated one.

Using Gemini.

Which meant I was asking the same general family of model I was trying to reduce dependency on to invent examples for the smaller model.

There is something slightly uncomfortable about that.

The first dataset had 1,386 examples across 33 intents and seven language/register categories.

The first model was mediocre.

Then I changed the dataset.

Instead of asking the generator to produce arbitrary examples for each class, I started giving it things that should make classification harder:

• similar intents,
• the same products,
• the same quantities,
• realistic vocabulary,
• previous bot messages,
• deliberately damaged WhatsApp-style text,
• and examples from languages and registers used by the application.

The second dataset grew to 9,751 examples.

The held-out score improved from roughly 0.70 to 0.86, and then to about 0.916 in the later 33-label experiment.

That looked like progress.

But there was a problem hiding inside the improvement.

Synthetic data doesn't just create examples

Consider the potato message.

The generator understands that potatoes can appear in many contexts.

A trader might be buying them.

Selling them.

Pledging them.

Asking about their price.

Asking about availability.

Asking about a market.

The model needs to learn the difference.

So I deliberately introduced contrastive examples.

If the target intent was sale_listing, I asked the generator to produce examples for that intent alongside examples for several confusable intents.

Same product.

Similar quantity.

Similar language.

Different meaning.

That helped.

But it also exposed something deeper.

When you generate your training data, you aren't simply producing more observations.

You're defining the world the model gets to see.

The model isn't learning "how traders talk."

It's learning patterns in the examples I gave it.

And those examples came from another model.

So synthetic data does not only give you more examples.

It gives you more examples of the generator's worldview.

The 99% prediction

That brings me back to the potatoes.

After improving the dataset, I tested a message equivalent to:

"I want to sell 20 bags of potatoes at Gikomba."

The classifier predicted:

pledge

with probability:

0.99

This was particularly interesting because the previous version had actually classified the message differently.

After the dataset changes, the model became more confident.

It also became more wrong.

The correct sale_listing prediction had been around 0.50 in the comparison I was running.

This is the kind of result that makes a model dangerous to trust casually.

A prediction of 51% gives you a reason to hesitate.

A prediction of 99% feels authoritative.

But the number doesn't mean what you instinctively want it to mean.

A softmax probability isn't a guarantee that the model is correct.

And in this case, the model had found a shortcut.

It wasn't confused.

The dataset had taught it the wrong shortcut.

That distinction matters.

If I had only looked at aggregate accuracy, I might have concluded that the new dataset was better.

The model had improved on the benchmark.

The benchmark was telling me something real.

It just wasn't telling me everything I needed to know.

Then I found another shortcut

The classifier doesn't always have enough information in the trader's message alone.

Consider:

"yes"

Or:

"20 bags"

Those messages are nearly impossible to classify without knowing what the bot asked immediately before them.

So I changed the input from:

trader message

to:

previous bot message + trader message

The model now receives a sentence pair.

For example:

Bot: "Do you want to sell potatoes?"

Trader: "Yes."

The word "yes" isn't the intent.

The conversation is.

This made the architecture more useful.

It also created a new data problem.

One of the intents, follow_up, was disproportionately associated with a particular kind of previous message.

About 94% of its examples had question-shaped previous turns.

Other intents had that pattern much less consistently.

The model could therefore learn an extremely cheap rule:

If the previous message looks like a question, this is probably follow_up.

It didn't need to understand the conversation.

It just needed to recognize the shape of the previous turn.

So I changed the generation rules in the next dataset version.

The fix wasn't "train harder."

It was:

change what the model is allowed to learn from.

That is a recurring theme in this project.

Then I discovered the classifier wasn't connected to most of the application

This was probably my favorite failure.

At some point I stopped looking at the model and started reading the application code.

The original intent enum had grown from 33 labels to 35.

I audited the actual routing code.

There were roughly 45 destinations or branches that the existing intent taxonomy couldn't cleanly represent.

Worse, around 11 of the 35 intent kinds weren't handled by the main switch that consumed the classifier output.

There was also a followUpNeeded value that was being produced but not actually consumed in the relevant routing path.

And there was another three-tier detector sitting in the codebase that, as far as the current application was concerned, had no importers.

The model was getting better.

The application didn't necessarily have anywhere useful to send the result.

So the taxonomy eventually grew to 74 labels.

This changed how I thought about the project.

I had originally thought I was building a classifier.

I was actually changing a piece of a larger decision system.

The model's output only matters if:

1. the taxonomy represents the application's real decisions,
2. the application actually consumes those decisions,
3. the routing is correct,
4. and the model can distinguish the decisions reliably.

A model can be technically excellent and operationally irrelevant.

The dataset had another problem

There was another number I initially liked:

0.916

It looked good.

The later evaluation used 8,307 training examples and 1,444 evaluation examples.

Across epochs, the score climbed roughly:

0.787 → 0.876 → 0.904 → 0.917 → 0.916

That looks like a healthy training curve.

But I eventually inspected the split itself.

A substantial number of evaluation examples had near-duplicates in the training set.

In one audit, 435 of the 1,444 evaluation rows had a near-duplicate on the training side.

About 30%.

That makes the headline score much less interesting.

If the evaluation set contains variations of things the model has effectively already seen, the benchmark is answering a weaker question than I thought.

So I changed the process.

The correct order is closer to:

split first → augment only the training side → evaluate on untouched examples

rather than:

generate → augment → split

That sounds like a small implementation detail.

It isn't.

The order in which you construct an experiment can determine whether the experiment means anything.

There were 25,327 "real" messages

At one point I found a local chat_messages table containing:

25,327 rows.

That sounded promising.

I thought I might have a real corpus.

I investigated it.

There were only 123 distinct idle-stage messages, spread across about 720 sessions from a load-test day.

The messages came from scripted personas.

They weren't a representative sample of actual trader conversations.

So:

25,327 rows of data

became:

no real trader messages used for training or evaluation.

This was another case where the first number was technically true and practically misleading.

And it reinforced something I was beginning to understand:

Data provenance matters more than data volume.

A million synthetic examples are not automatically more valuable than a thousand carefully labelled production examples.

Training was the easy part

My laptop is a MacBook with 16 GB of memory.

The model I used, AfroXLMR, is around 270 million parameters.

Training locally was possible up to a point.

Then memory became the bottleneck.

I reduced the batch size and used gradient accumulation.

It initially worked.

Then the machine started thrashing.

A training step that had taken around 1.2 seconds eventually approached 10 seconds.

So I stopped trying to make the laptop do a job it wasn't suited for.

I moved training to Vertex AI.

That introduced an entirely different class of problems.

The first cloud training attempt failed because the selected PyTorch image wasn't compatible with the Transformers version I was using.

Some gcloud flags I assumed existed didn't exist in the form I expected.

One duplicated training script couldn't import the project correctly.

At one point a hardcoded label list in the cloud job drifted from the actual taxonomy.

These weren't sophisticated machine-learning problems.

They were engineering problems.

And AI coding agents were involved in several of them.

That's worth emphasizing because AI-assisted development can create a strange illusion of progress.

You can have a repository full of code very quickly.

You can have Docker files.

Training scripts.

Cloud configuration.

FastAPI endpoints.

Export scripts.

Benchmarking tools.

Documentation.

Everything can look finished.

And still be wrong.

AI can write the cloud plumbing. It cannot remove the need to read the error message.

The final training run completed in about 259 seconds on an L4 GPU.

The infrastructure worked.

But getting there required reading failures rather than asking the agent to simply try again.

What the AI actually did

The AI coding agents were extremely useful.

They accelerated almost every mechanical part of the project.

They helped scaffold:

• the training pipeline,
• dataset generators,
• cloud training jobs,
• model export,
• FastAPI serving,
• benchmarking,
• documentation,
• and parts of the application routing audit.

They also made mistakes.

Among them:

• incompatible cloud images,
• nonexistent CLI flags,
• stale hardcoded labels,
• shell quoting bugs,
• an incorrect Python environment,
• and a generator that hung without a timeout and lost thousands of generated rows held only in memory.

None of that makes the agents "bad."

It changes what I expect from them.

I don't think the valuable distinction is:

AI writes code vs. humans write code.

The more useful distinction is:

Who is responsible for deciding whether the code is correct?

The agent can generate ten implementations.

It can explain why each one should work.

It can confidently tell you that the cloud configuration is valid.

That doesn't make any of those things true.

The human's role moves upward.

Less typing.

More auditing.

Less implementation trivia.

More experimental design.

Less:

"How do I build this?"

More:

"What evidence would make me change my mind?"

So is the model good?

I don't know yet.

And that's the honest answer.

The 0.916 held-out accuracy is a useful measurement.

It is not a production accuracy claim.

The current evaluation has several limitations.

The training data is synthetic.

The evaluation set had leakage problems that I had to fix in the data-generation pipeline.

There is no permanently untouched real-world test set.

The classes are imbalanced. One label had 573 generated examples while another had 170.

The weakest per-label recall was around 0.69.

The softmax confidence has not been properly calibrated on real labelled traffic.

And the application recognizes language and register patterns, including Kikuyu and Sheng, that aren't fully represented in the generated training data.

I also need better evaluation metrics than a single accuracy number.

Macro-F1.

Per-intent precision and recall.

Confusion matrices.

Calibration.

Performance on real production messages.

Most importantly, I need to know what happens when the model sees language it wasn't trained to imitate.

That is the experiment that matters.

What I would do next

The next version of this project is much less glamorous.

I want to export a representative sample of production messages.

Then I want humans to label them.

Not thousands at first.

A few hundred carefully selected examples would already tell me far more than another 10,000 synthetic messages.

I'd want people who actually understand the language and conversational patterns involved, particularly for Swahili and Hausa.

I'd keep a real test set permanently outside training.

Then:

1. Fix the split and augmentation pipeline.
2. Train without contaminating evaluation data.
3. Measure macro-F1 and per-intent confusion.
4. Test on real trader messages.
5. Calibrate the confidence threshold.
6. Finish routing the expanded 74-label taxonomy.
7. Run the classifier beside Gemini in shadow mode.
8. Compare predictions before allowing the classifier to make production decisions.

Only then would I decide whether the cascade is actually useful.

And I wouldn't be surprised if the answer is no.

That would still make the project successful.

The thing I was actually learning

When I started this, I thought I was learning machine learning.

I was.

But that wasn't the most important thing.

I learned what supervised classification is.

I learned about transfer learning, embeddings, sentence-pair classification, stratified splits, class imbalance, quantization, inference, calibration, and model serving.

Those things matter.

But the more important lesson was about engineering judgment.

When implementation becomes cheap, verification becomes scarce.

AI made it possible for me to go from:

"I want to build a classifier"

to:

"Here is a trained model, an evaluation script, a cloud job, an ONNX export, and a FastAPI endpoint"

very quickly.

That was useful.

It was also dangerous.

Because every stage produced artifacts that looked like progress.

The model had a score.

The API returned JSON.

The cloud job completed.

The ONNX model ran in seven milliseconds.

The dataset had thousands of rows.

The repository had documentation.

And yet:

• the quantized model was broken,
• the model learned a shortcut,
• the evaluation split leaked,
• the taxonomy didn't match the application,
• and the "real" dataset wasn't real.

None of those failures were caused by a lack of code.

They were caused by asking the wrong questions, or asking them too late.

The most valuable skill I practiced wasn't training a model.

It was learning to ask:

What would I expect to see if this were actually working?

Then checking.

The classifier may eventually replace some of the Gemini calls.

It may not.

I still don't know whether a model trained entirely on synthetic trader language will hold up when real traders start using it.

That's the next experiment.

And this time, I know what I need to measure.

Are you a Laravel developer looking to boost your productivity and streamline your PHP development workflow? Tinkerwell is your go-to PHP playground. This comprehensive Tinkerwell cheatsheet covers all the essential keyboard shortcuts, smart features, and hidden tools to help you write, test, and debug code faster than ever.

🔑 Tinkerwell Keyboard Shortcuts (macOS & Windows/Linux)

Use this quick reference table to save time and work smarter inside the Tinkerwell editor:

⚙️ Essential Tinkerwell Shortcuts for Daily Productivity

✅ Code Execution

Run Code: Instantly execute the full code in the editor (Cmd+R / Ctrl+R)

Run Selected Code: Only run the highlighted portion of your script (Cmd+Shift+R / Ctrl+Shift+R)

Auto Evaluate: Let Tinkerwell auto-run your code as you type (Cmd+Shift+A / Ctrl+Shift+A)

🔍 Navigation & Interface Control

Open Anything: Use the command palette to jump to files, functions, or features (Cmd+Shift+P / Ctrl+Shift+P)

Toggle AI Modal: Interact with Tinkerwell's built-in AI assistant for code suggestions (Cmd+Shift+L / Ctrl+Shift+L)

Toggle Snippets: Quickly access and insert your saved snippets (Cmd+B / Ctrl+B)

View History: Go back in time and revisit past inputs and outputs (Cmd+Y / Ctrl+I)

🧹 Code Management Tools

Prettify Code: Format your PHP code for clarity and consistency (Cmd+P / Ctrl+P)

Clear Output: Clean your output panel for a fresh view (Ctrl+L)

Duplicate Tab: Clone your current session to test variations without losing progress (Cmd+Shift+D / Ctrl+Shift+D)

💡 Pro Tip for Power Users

Switch Editor Layout: Use Ctrl+. to toggle between split and single views – perfect for multitasking or comparing code blocks side-by-side.

🚀 Supercharge Your Laravel Workflow with Tinkerwell

Whether you're debugging complex logic, experimenting with Eloquent queries, or just tinkering with ideas, Tinkerwell helps you stay in flow.

Save this guide, bookmark it, and share it with fellow developers.

Happy tinkering! 🎯

As a developer working on macOS, the right set of tools can make all the difference between a productive day and a frustrating one. Over the years, I’ve curated a toolkit that not only streamlines my workflow but also makes my daily routine genuinely enjoyable. Here’s a look at the essential apps and utilities that power my day.

My Essential Tools

• PHPStorm – My primary editor. It’s where most of my work happens, from writing code to debugging and everything in between.
• CleanShot – For capturing and annotating screenshots with ease.
• Chrome & Arc – My browsers of choice for development and research.
• Dolphin {anty} – Multiple browsers. (Could be logged in the same app with different users. Handy when I am debugging.).
• Raycast – The real game-changer. More on this below.
• Warp – My terminal of choice, especially when I need a modern, fast CLI experience.
• Screen Studio & Presentify – My secret weapon for making quick explainer videos or PR walkthroughs.
• OBS – For more advanced screen recording needs.
• TablePlus – My go-to for browsing and managing MySQL and ClickHouse databases.
• Tinkerwell – For running PHP code snippets and experimenting quickly.
• RunJS – A JavaScript playground for quick tests.
• Raycast Focus – Helps me stay in the zone.
• Cursor & Claude Code – For AI-powered coding assistance.
• Docker – Ensures my local environment matches production as closely as possible.
• Raycast Notes – For jotting down quick ideas.
• Git Tower – Great for visualizing git history, but I still love the command line for most git operations.
• Spotify (Instrumentals) – My soundtrack for focus and flow.

Why I Love Raycast

Raycast has completely changed the way I interact with my Mac. With extensions for virtually all my apps and AI available at the press of a button, it’s become the central hub for my workflow. Whether I’m launching apps, searching files, or running custom scripts, Raycast makes everything faster and more intuitive.

Hidden Gem: Presentify

If you ever need to make quick videos for PRs or explainers, Presentify is a gem. It lets me annotate my screen in real-time, making my recordings much clearer and more engaging. It’s one of those tools I wish I’d discovered sooner.

Recent Discoveries I Can’t Live Without

Raycast is the standout here. Since I started using it, my productivity has noticeably improved. It’s not just an app launcher. It’s a workflow enhancer.

GUI vs. Command Line

I use TablePlus for browsing and managing databases, primarily MySQL and ClickHouse. For git, I prefer the command line (like a true cave man), but Git Tower is great for visualizing complex histories. Warp is especially helpful when I get stuck or need a more modern CLI experience.

Raycast Extensions & Custom Scripts

One of my favorite things about Raycast is the ability to create custom scripts. I have a script that prepares my code environment: it checks out the correct branch and does some plumbing based on my JIRA ticket. This automation saves me time and mental energy every day.

Staying Focused

To stay in the zone, I rely on Raycast Focus and instrumental playlists on Spotify. This combo helps me block out distractions and maintain deep focus during coding sessions.

If I Could Only Keep Three Tools

If I had to choose just three tools from my list, they would be:

1. PHPStorm – It’s my primary editor and the heart of my workflow.
2. Raycast Focus – It fundamentally improves the way I interact with my Mac and helps me stay productive.
3. Docker – It ensures my development environment is as close to production as possible, reducing surprises during deployment.

Final Thoughts

The right tools don’t just make you more productive. They make your work more enjoyable. These are the apps and utilities that power my day as a developer on macOS. If you’re looking to optimize your own workflow, I highly recommend giving some of these a try. Who knows, you might discover a new favorite!