Shout Laravel Package

Technical Evaluation

Architecture fit

• Shout is a pure presentational Filament schema component (Awcodes\Shout\Components\Shout), not a persistent field. It is dropped into the schema() array of forms and infolists alongside TextInput or Section. No domain model change, no migrations, no routes, no service container bindings, no queue or event surface. Server-side footprint is one Blade view plus a thin PHP class — the lowest-blast-radius category of dependency we can take on.
• It fits cleanly if we are already Filament-first for admin. It offers nothing outside Filament: no public-page, email, or API rendering.
• Composition is richer than "a placeholder": heading(), content(), color() (Filament Color object or hex), icon()/iconSize()/icon(false), and actions() accepting real Filament Action objects. That last one matters — the notice can carry a CTA, which means it can host deprecation warnings with an "upgrade" link, compliance copy next to a destructive action, or onboarding hints that deep-link into the relevant resource. That is the actual product value: consistent, actionable in-context messaging inside the admin surface rather than a bare colored box.
• There is no native Filament equivalent that is both colored and action-bearing in a form schema (Placeholder is close but plainer). So the package fills a real gap, if a small one.

Integration feasibility

• composer require awcodes/shout, then use it. Usage is one line in a schema array.
• The one real prerequisite: a custom Filament theme. If we use Filament Panels without a custom theme already compiled, we must set one up first, then register the vendor view path with a Tailwind @source glob (@source '../../../../vendor/awcodes/shout/resources/**/*.blade.php'). If we use the standalone packages, the same directive goes in our app CSS.
• If we already ship a custom theme, integration is roughly a 15-minute change plus a design review. If we do not, this package is quietly asking us to adopt a theme build pipeline — that is the actual cost, not the dependency.

Technical risk

• Low blast radius, a few sharp edges. Failure of this package degrades a notice to an unstyled or missing block; it cannot corrupt data or break a request.
• CSS purge is the highest-likelihood failure. Omit or misconfigure the @source glob and the component renders structurally but unstyled — a silent failure that only shows up visually, i.e. the kind QA catches late.
• Dark mode changed in 4.1.1 (tinted dark palette, translucent borders, light text). Any screenshots, design specs, or stakeholder expectations built on ≤4.1.0 will differ. Pin floor at ^4.1.1, which also fixes icon aliases (shout::icon.info, etc.) that never resolved before, plus an empty-<h2> bug and the icon(false) indent bug.
• Version coupling to Filament majors is hard: 1.x→F2, 2.x→F3, 3.x→F4, 4.x→F4 & F5. Shout is a rider on our Filament version; every Filament major upgrade becomes a coordinated two-package move.
• Bus factor of one. 72 stars, 0 dependents, single maintainer, no commercial support. Low external validation means we are an early-ish adopter, not a follower. Mitigation is easy: the component is trivially replaceable by an in-house Blade view if it is ever abandoned.
• Dependency tree check needed: PR #61 added Require awcodes/focus ^1.0. Confirm it is a dev/build-time dependency for docs screenshots and not a runtime requirement we inherit.

Key questions

1. Do we already have a Filament custom theme build, and who owns the Tailwind @source list? This gates the whole decision.
2. Is awcodes/focus dev-only? What else lands in composer.lock transitively?
3. Which Filament major are we standardizing on for the next 12 months — 4.x or 5.x? That dictates branch and pin.
4. Is content()/heading() safe with dynamic or user-influenced strings, and are we prepared to treat HtmlString headings as a trusted-input-only path?
5. Does the org want a governed notice vocabulary (severity → color/icon → allowed actions), or do we let each team call Shout::make() ad hoc?

Integration Approach

Stack fit

• Laravel + Filament 4.x or 5.x, PHP 8.x, Tailwind 4 (implied by the @source directive). Use v4.1.1+ for dual Filament 4/5 support; stay on 3.x only if we are pinned to Filament 4 and want a narrower branch.
• It is a style-layer dependency, not an infrastructure one. Treat it accordingly: no architecture review, but do put it under the same pinning and upgrade-ticket discipline as our theme.

Migration path

• Nothing to migrate. It is purely additive — no schema changes, no data backfill, no route changes.
• The meaningful "migration" is from ad-hoc messaging to a governed pattern. Today teams likely improvise with Placeholder, raw TextEntry, or helper text strings. Moving to Shout is an opportunity to standardize severity, copy tone, and which notices are allowed to carry actions.
• Build a thin internal wrapper rather than calling the vendor class directly everywhere — e.g. App\Support\Notices::deprecation(), ::compliance(), ::onboarding(). This gives consistent colors/icons, one place to change copy, and a one-file swap if the package is ever abandoned. It also keeps vendor API surface out of hundreds of schema files.
• Removal path is trivial: delete the wrapper and inline equivalent Blade. That keeps the exit cost near zero and is worth stating to stakeholders up front.

Compatibility

• Hard constraint: Shout major must match Filament major. Record this in our dependency policy so nobody bumps Filament without co-bumping Shout.
• Pin ^4.1.1 as the floor for the icon-alias and dark-mode fixes; do not let transitive resolution land on 4.0.x/4.1.0.
• Verify PHP and Tailwind versions against our build image before the pilot; the @source directive will not work on a Tailwind 3 pipeline.

Sequencing

1. Confirm the theme pipeline — does a custom Filament theme exist, is it compiled in CI, and who adds the @source line? Blocking.
2. Dependency audit — composer why awcodes/focus, confirm dev-only, confirm lockfile delta is acceptable.
3. Pilot in one low-traffic resource — a single form and a single infolist, one light-mode and one dark-mode check, one action-bearing notice.
4. Define the severity vocabulary and wrapper before broad rollout; publish two or three approved presets with copy guidelines.
5. Roll out to high-value slots — deprecation banners with upgrade CTAs, compliance/disclaimer copy near destructive actions, empty-state guidance in infolists. Avoid it for anything that is really validation feedback (Filament's own validation should own that) or anything that must survive export/print.
6. Document the removal path in the internal dependency register so a future TPM does not treat this as load-bearing.

Operational Impact

Maintenance

• Zero runtime maintenance: no cron, no storage, no config to tune, no migrations to re-run.
• The recurring cost is the upgrade treadmill. Each Filament major will require a matching Shout major, and our theme's @source glob plus dark-mode palette will need a visual pass. Budget it as a line item in every Filament upgrade epic — small, but non-zero and easy to forget.
• Realistically 1–2 hours per Filament major, plus a design review for visual deltas. Cheap enough that abandonment is a credible fallback.

Support

• Community OSS, MIT, one maintainer, no SLA. Documentation is genuinely good for the size (docs hub, screenshots, per-feature examples) and changelogs are detailed — a positive signal for a solo project.
• We must name an internal owner (likely the team that owns the admin theme) for the @source wiring and the internal presets. Without that, the first Tailwind refactor silently breaks every notice.
• Escalation path if upstream goes quiet: fork the Blade view into our theme and drop the dependency. Cost is a few hours.

Scaling

• Effectively free at runtime. Blade render only, no queries, no N+1 exposure, no client-side JS beyond Filament's own action machinery.
• The only scaling dimension is CSS payload from the @source glob — negligible, but it does mean the vendor path must remain stable across our theme builds.
• No concurrency, caching, or data-volume concerns whatsoever.

Failure modes

Note the pattern: every credible failure is visual and silent. That argues for one automated screenshot check on a pilot page rather than heavy test investment.

Ramp-up

• For a Filament-fluent developer: minutes. The API is four methods and mirrors Filament conventions they already know.
• The actual learning curve is organizational, not technical: getting the theme build right once, and getting teams to use the wrapper presets instead of hand-rolling colors and icons.
• Onboarding artifact needed: one short internal page covering the presets, the "when to use / when not to use" rule (in-context guidance yes; validation errors no), and the @source line with a note on why it exists.

TPM judgment Low cost, low risk, modest but genuine UX payoff — worth adopting if we already run a custom Filament theme, in which case it is close to free. If we do not, the theme pipeline is the real project and Shout is a two-line rider on it. The opportunity score (~47.6) and zero dependents suggest this is a convenience, not a platform bet: adopt with a pinned floor and an internal wrapper, and explicitly record that removal is a few hours of work.