Hydro Laravel Package

Getting Started

Verify what you're actually installing before anything else. The package's own description claims it adds image watermarks with a fluent API; the actual tool is a CLI that scaffolds Filament plugins locally instead of cloning Filament's GitHub Plugin Skeleton. Confirm the behavior against the source before wiring it into any documented workflow — the self-documentation mismatch is a genuine onboarding hazard.

Minimal setup:

1. Install globally, never in a project's composer.json: composer global require awcodes/hydro Ensure ~/.composer/vendor/bin (or ~/.config/composer/vendor/bin) is on PATH.
2. Confirm the binary and its commands: composer global show awcodes/hydro to see the exposed bin, then run the tool's help output before invoking scaffolding.
3. Run one scaffold against a throwaway directory — not a real package — and read every generated file: composer.json, service provider, namespaces, test harness, README.

First use case: you have a Filament plugin to build inside an existing app's packages/ directory. Scaffold it, wire it into the host app via a Composer path repository, then let your existing Pint/PHPStan/Pest/CI pipeline run over the output. That single loop tells you more about fit than any README.

Time-box this to an afternoon. The decision is not "is this nice," it's "does the emitted scaffold match our current Filament/PHP conventions well enough to beat cloning the skeleton."

Implementation Patterns

Treat it as a scaffold generator, not a dependency. The realistic lifecycle is: generate once, commit the output, and never need Hydro again for that plugin. Nothing it produces should reference the tool at runtime.

Local package-development loop. The pattern that actually pays off is generating inside a host app:

• Scaffold into packages/vendor-name/plugin-name.
• Add a path repository to the host app's composer.json and composer require the plugin with a @dev constraint.
• Work the generate → require → build → test loop in one repo, avoiding a publish/install cycle per iteration.

Normalize the output immediately. Generated stubs encode the author's conventions, not yours. After the first scaffold, diff the result against your internal standards and either patch them consistently or — better — fork once, edit the stubs, and use your fork thereafter. The package is a template, and templates should be owned.

Put the scaffold under CI. A cheap, high-value job: scaffold a throwaway plugin, then run Pint, PHPStan, and a smoke test against it. This catches stub drift, broken Composer constraints, and incompatible generated code before an engineer hits it mid-task. It also gives you an early warning when a Filament release invalidates the stubs.

Wrap it. A small shell alias or a bin/new-plugin script that invokes the tool, applies your namespace conventions, and strips/renames anything non-standard keeps everyone producing identical structure. This is where the day-to-day value actually lives — not in the raw command.

Pin the version. If teammates rely on it, pin it (global Composer constraint or an internal mirror) so one engineer's composer global update doesn't silently change what everyone generates.

Document the fallback in the same breath. Wherever you write "run hydro," add "or clone Filament's Plugin Skeleton and rename" as the supported alternative. The tool must never be the only known path to starting a plugin.

Gotchas and Tips

Assume the stubs are stale. Last release was March 2023, which predates Filament v3 plugin conventions. Verify the generated composer.json constraints, service provider shape, and test harness against your actual Filament/Laravel/PHP matrix before trusting output. Never let a generated package reach CI unexamined.

Verify whether Filament now ships native scaffolding for your version. If it does, Hydro is redundant — check first, and skip the adoption entirely.

Abandonment is the base case. Thirteen stars, zero dependents, one maintainer, no release since March 2023, no vendor support, and documentation describing the wrong tool. Plan for a fork, not for upstream fixes. Budget a small slice of engineering time per Filament major release to re-validate or patch stubs.

Check the license before forking — vendoring and editing the stubs is the expected operating model, so license compatibility is a hard gate, not a formality.

It is a global CLI; keep it that way. Adding it to any deployed app's composer.json gives you nothing and adds supply-chain surface to a tool with no runtime role. Keep it in the global layer or, at most, require-dev of a plugin-development repo.

Watch for network or GitHub-token assumptions. The tool exists partly to remove a GitHub clone step, so confirm whether a scaffold run is fully offline. If it still calls out for anything, that defeats a chunk of the stated value and matters for air-gapped or rate-limited environments.

Debug by diffing, not by guessing. When a scaffold looks wrong, generate into an empty directory and diff against both your last accepted scaffold and a skeleton-based baseline. The failure modes here — stale conventions, broken prompts, incompatible constraints — all show up as structural differences, not error messages.

Don't make it tribal knowledge. With one maintainer and inconsistent docs, a new hire who hits a broken command has no escalation path. A named internal owner, a pinned version, and a documented fallback are the minimum conditions for putting this in anyone's onboarding.

Re-evaluate at every Filament major. That's the natural expiry date for any scaffold's assumptions — and the point at which "we own this fork" becomes real work.