8 · Dev tooling

TL;DR

Objective — adopt local-development power-ups only where they fill a real gap: Atlas schema management, a database GUI (Bytebase), Redis caching via Herd Pro, and a right-sized debug-tools stack. None block launch; each has a free fallback.

Steps at a glance:

1. Atlas — schema management — Atlas gives clean schema exports and cross-environment diffs (it’s the preferred exporter on page 5).
2. Bytebase — database GUI & review workflow — Bytebase adds a web UI for schema management, SQL review, and approval workflows across staging/production.
3. Redis cache via Herd Pro — Redis replaces file-based cache/sessions/queues — 2–3× faster page loads, instant sessions. Not required for launch, and easy to add post-deploy.
4. Debug tools — install only what fills a gap — Shipping without a request/query inspector is guesswork — but many CodeCanyon apps already ship barryvdh/laravel-debugbar.

User part + done-when

👤 User part — only for the tools you actually adopt: log in to Atlas Cloud, create a Bytebase workspace and whitelist its egress IP, or start the Herd Redis service in the GUI. Everything else is terminal-runnable, and any unadopted tool gets its free fallback noted.

Done when each tool is either installed where it adds value or marked N/A with evidence and the free fallback noted; if Redis is added, redis-cli ping returns PONG and tinker returns "Redis works!"; debug tools have no duplicate request inspectors; and Phase 3 is complete.  ·  ⏱ ~varies  ·  🔀 mixed (mostly 🤖; 👤 for cloud sign-ins / GUI service start).

Background

After Shared-hosting readiness is clean, decide which dev tools earn a place in this project. Adopt what you need, and prefer the free fallback when a paid service does not clearly help.

Steps

1. Atlas — schema management

Atlas gives clean schema exports and cross-environment diffs (it’s the preferred exporter on page 5). The CLI is free; Atlas Cloud’s visual diffs and CI checks need a license.

1. Install the CLI and sign in. The CLI install is terminal-runnable; the atlas login browser sign-in is a 👤 step if you want Cloud features.

   atlas version 2>/dev/null || brew install ariga/tap/atlas
   atlas login && atlas whoami
   # Expected: a version, then your Atlas identity after the browser login

   • ✅ The Atlas CLI is installed (and signed in if you use Cloud).

2. Point it at the local DB via an env var — keep secrets out of atlas.hcl — and gitignore the env files.

   echo 'ATLAS_LOCAL_URL="mysql://root:@127.0.0.1:3306/[PROJECT_NAME]_local"' > .env.atlas
   grep -q '^\.env\.atlas$' .gitignore || printf '.env.atlas\n' >> .gitignore
   grep -q '^\.envrc$' .gitignore || printf '.envrc\n' >> .gitignore
   # Expected: .env.atlas written and both env files added to .gitignore

   • ✅ Atlas reads the DB URL from a gitignored env file.

Free fallback

You don’t need Atlas at all: mysqldump --no-data for snapshots (page 5), diff for comparison, and TablePlus (free tier) or DBeaver (open source) for visual inspection. Skip the Cloud push entirely if your plan is expired.

2. Bytebase — database GUI & review workflow

Bytebase adds a web UI for schema management, SQL review, and approval workflows across staging/production. It’s a heavier setup (~60–90 min) and only worth it for teams running frequent reviewed schema changes.

Who does this

🔀 User + Agent — 👤 the user owns signup, account authorization, and any IP allowlist/security approval. 🤖 With an authorized browser session, the agent can drive the non-secret workspace setup, connect instances from Zaj-PROJECT.md, and verify the connection evidence.

1. Stand up the workspace and connect your instances.

   • Create a free workspace at hub.bytebase.com.

   • Add your staging and production instances (whitelist Bytebase’s egress IP in Remote MySQL first).

   • Create a project, transfer the databases in, sync schemas, and attach an SQL-review policy.

   • ✅ Bytebase is connected to your instances with a review policy attached.

Free fallback

TablePlus, DBeaver, panel phpMyAdmin, plus php artisan migrate:status and mysqldump --no-data cover the same ground for a solo developer.

3. Redis cache via Herd Pro

Redis replaces file-based cache/sessions/queues — 2–3× faster page loads, instant sessions. Not required for launch, and easy to add post-deploy. Local dev uses Herd Pro’s built-in Redis; staging/production use Upstash (configured in Phase 4/5).

Who does this

👤 User starts (or adds) the Local_Redis service in Herd → Services → Cache & Queue when it is not already running. The Predis install, .env wiring, and verification below are terminal-runnable and agent-verifiable.

1. Start the Herd Redis service, then confirm it answers.

   redis-cli ping   # expect PONG
   # Expected: PONG

   • ✅ redis-cli ping returns PONG.

2. Require Predis, or record a named carry-forward — install only after the Phase 3 PHP-drift check is clean. If PHP drift is unresolved, do not mutate composer.lock here; record the package decision for Phase 5 after Phase 4 confirms the deploy PHP, then skip the Redis wiring below for now.

   INSTALL_PREDIS="${INSTALL_PREDIS:-1}" # set to 0 when PHP drift is unresolved
   
   if [ "$INSTALL_PREDIS" = "1" ]; then
     composer require predis/predis
   else
     grep -q '| redis-predis-package |' Zaj-BACKLOG.md 2>/dev/null || printf '%s\n' \
       "| $(date +%Y-%m-%d) | redis-predis-package | 🟢 carry-forward non-blocker | Predis install waits for confirmed deploy PHP + Phase 5 Composer pin | Phase 5 page 1 | Predis resolves under the deploy PHP and Redis checks pass |" \
       >> Zaj-BACKLOG.md
     echo "Predis carry-forward recorded in Zaj-BACKLOG.md"
   fi
   # Expected: Predis resolves and installs without changing the PHP platform decision,
   #           or a named Phase 5 carry-forward is already recorded.

   • ✅ Predis is installed, or Zaj-BACKLOG.md names a Phase 5 carry-forward to install it after Phase 4 confirms the deploy PHP and before the first live deploy.

3. Wire local .env to the Herd Redis (no password, localhost). Skip this Step when Predis was carried forward instead of installed.

   CACHE_DRIVER=redis
   SESSION_DRIVER=redis
   QUEUE_CONNECTION=redis
   REDIS_CLIENT=predis
   REDIS_HOST=127.0.0.1
   REDIS_PASSWORD=null   # leave unquoted — null is a literal token; "null" breaks auth (exception to the double-quote-secrets rule)
   REDIS_PORT=6379
   REDIS_PREFIX=[PROJECT_NAME]_local_

   • ✅ .env points cache/session/queue at the local Redis.

4. Verify through tinker, then commit the lock-file change. Skip this Step when Predis was carried forward instead of installed.

   php artisan config:clear && php artisan cache:clear
   php artisan tinker --execute="Cache::put('t','Redis works!',60); echo Cache::get('t');"
   git add composer.json composer.lock && git commit -m "Add Redis cache support via Predis"
   # Expected: "Redis works!" prints, then the lock-file commit is created

   • ✅ Tinker returns Redis works! and the lock change is committed.

Prepare (don’t populate) the Upstash placeholders in your .env.staging / .env.production templates for the deploy phase. If Predis was carried forward, leave local cache/session/queue on file/sync drivers and record the reopen trigger in Zaj-BACKLOG.md.

Do not pin PHP from Phase 3 tooling

If Redis or another tool install exposes PHP drift, stop and carry the package decision into Phase 4/5. Phase 4 confirms the domain’s actual deploy PHP; Phase 5 commits the Composer platform pin before the first live deploy.

If you’re not on Herd Pro, any of these gives you the same local Redis:

No Herd Pro?

brew install redis && brew services start redis, docker run -d -p 6379:6379 redis:alpine, or DBngin — or simply keep CACHE_DRIVER=file locally and only use Redis (Upstash) on the server.

4. Debug tools — install only what fills a gap

Shipping without a request/query inspector is guesswork — but many CodeCanyon apps already ship barryvdh/laravel-debugbar. Installing Telescope on top creates competing toolbars and double-captures queries. Check first.

1. Check what’s already present.

   grep -c '"name": "barryvdh/laravel-debugbar"' composer.lock
   grep -c '"name": "laravel/telescope"' composer.lock
   # Expected: a 0/1 count for each — tells you what's already installed

   • ✅ The inspectors already in composer.lock are known.

2. Add at most one, based on what’s present.

   Already present	Action
   debugbar only	Keep it — you have request/query visibility. Don’t add Telescope.
   Telescope only	Keep it.
   Neither	Add one — debugbar for a quick bottom-bar, Telescope for a richer dashboard.

   • ✅ Exactly one request/query inspector is active — no duplicates.

Sentry and Ray are conditional

A Sentry SDK without a real DSN is dead code locally — install the SDK + publish config here only if you’ll wire it up, and do the actual DSN + test event in Phase 4 (don’t create a Sentry project now). If the SDK install exposes PHP drift, record the carry-forward instead: Phase 4 confirms the deploy PHP, then Phase 5 commits the Composer platform pin and resolves the package decision before the first live deploy. Spatie Ray only helps if you own the paid Ray desktop app; if not, mark Ray N/A in Zaj-PROGRESS.md with the active free fallback (debugbar or Telescope) instead of silently skipping it.

Checklist

Do not mark this step done until every box below is checked.

• 🔀 Per-tool decision made — installed where it adds value, or marked N/A with evidence and the free fallback noted.
• 🔀 Redis (if added) — redis-cli ping → PONG and tinker returns "Redis works!".
• 🤖 No duplicate inspectors — not both debugbar and Telescope.
• 🤖 Phase 3 complete — local environment installed, verified, committed, and secured.

→Next step

Phase 4 · Deploy pipeline