Foggy Laravel Laravel Package

Getting Started

• Install with composer require worksome/foggy-laravel, then publish the package config (vendor:publish) and review the disk, dump, and retention options before wiring anything into a scheduler. The published config file is the best first read — it documents the supported drivers and defaults far better than the README's quickstart.
• Skim the service provider and the console commands next. Because this is a 0.x package, the source is the contract; there is no stable public API guarantee yet.
• First real use case: a scheduled nightly dump of your primary database to a dedicated S3 disk. Configure a non-default s3 disk (separate bucket/prefix, scoped IAM user), point the package at it, and run the dump command manually once with verbose output before putting it on a schedule.
• On v0.8.1 specifically: streaming a dump whose size is not known up front now works. If you were holding back on piping mysqldump/pg_dump output straight through, or you were buffering to a temp file just to satisfy the old size requirement, you can drop that workaround.

Implementation Patterns

• Scheduler entry, not a queue job, for the dump itself. Database dumps are long-running and stateful; run them via the console scheduler with withoutOverlapping() and a generous runInBackground() if your dump exceeds the scheduler's tick window. Dispatch a separate job only for post-processing (notifications, retention pruning).
• One disk per environment, configured via env. Keep bucket, prefix, and credentials in config/filesystems.php, and have the package config reference the disk name rather than embedding credentials. This makes staging/production dumps land in separate buckets without code changes.
• Per-environment naming. Include the app env and a timestamp in the object key (e.g. dumps/{env}/{date}.sql.gz). It makes lifecycle rules and restore lookups trivial, and prevents a staging dump from overwriting a production one.
• Compress before upload. Stream through gzip where possible; the v0.8.1 unknown-size streaming fix is what makes this practical, since compressed output has no predictable length.
• Prefer streaming over temp files. For anything above a few hundred MB, pipe the dumper's stdout directly to the uploader. Set the package's dump binary path explicitly if the default mysqldump/pg_dump isn't on the web user's PATH.
• Test with Storage::fake(). Assert that the expected object key exists and is non-empty in a feature test, and assert the command exit code. Don't assert on dump contents — that couples tests to the DB driver.
• Restore is a separate, deliberate workflow. Treat the package as write-only in day-to-day use; keep a documented aws s3 cp + mysql < (or equivalent) restore runbook rather than expecting the package to do it.
• Retention via S3 lifecycle rules, not application code. Let the bucket expire old objects. Application-level pruning tends to silently fail and is harder to audit.

Gotchas and Tips

• 0.x semver. Pin the exact version in composer.json and read every changelog between minor bumps. A fix: in 0.8.1 is safe, but 0.9.0 could rename config keys or commands without a deprecation cycle.
• The v0.8.1 fix changes failure modes. On ≤0.8.0, a dump stream with an unknown size either errored or was fully buffered in memory before upload. If you're upgrading, re-run your largest dump and watch memory; you should now see flat memory usage and a multipart upload. If you still see the old behaviour, you're likely pinning an older version transitively.
• S3 multipart minimum part size is 5 MiB. Unknown-size streams are uploaded via multipart, so tiny dumps may show as a single part while large ones chunk. If you see EntityTooSmall errors, the stream is being flushed in sub-5 MiB chunks — check the uploader's part-size config.
• Timeouts, not memory, are the usual failure. Long dumps get killed by PHP max_execution_time, the queue worker timeout, or the S3 HTTP client timeout. Set all three explicitly and log the duration.
• Credentials hygiene. Use a dedicated IAM user with s3:PutObject only on the dump prefix. Dumps contain PII; enable SSE and block public access at the bucket level rather than relying on ACLs.
• Watch for partial uploads. If a dump fails mid-stream, multipart uploads can leave orphaned parts that still incur storage cost. Add a bucket lifecycle rule to abort incomplete multipart uploads after a day.
• Debugging: run the command interactively with -v, and temporarily point the disk at local to confirm the dump itself is valid before suspecting S3. Most "upload failed" reports are actually a dumper exiting non-zero.
• Extension points: the dumper binary/arguments and the target disk are the two things you'll realistically customise. Wrap any customisation in your own config layer so a package upgrade doesn't overwrite it.
• Don't commit dumps or credentials. Add the local dump path to .gitignore and keep AWS keys in env/secret manager, not in the published config.