Laravel Jev Moderation Laravel Package

Product Decisions This Supports

• Build vs. buy for trust & safety. This package lets you buy the classifier (Jev) while owning the workflow. That removes the biggest in-house risk — standing up and tuning a moderation model — without handing over the product surface: statuses, review queues, user-facing behaviour and audit data all stay in your database. A realistic build-vs-buy framing becomes "buy classification, own policy and process," which is a materially cheaper first year than a dedicated T&S platform contract.
• Shipping any UGC feature. Comments, profiles, listings, reviews, DMs, avatars descriptions, support tickets — anything where a user writes text that another user can see. The Moderatable trait plus #[Moderate] attribute means moderation is an annotation on existing models, not a re-architecture. Scope this as an enabler for the whole UGC roadmap rather than a line item under one feature.
• Launch risk gates and go/no-go criteria. post vs pre mode is a product decision, not an engineering one: pre-moderation trades time-to-publish and user trust for safety and support load; post-moderation trades safety for activation and engagement. Being able to flip modes per environment (JEV_MODERATION_MODE) means you can run a staged rollout — start strict in a beta cohort, loosen on evidence — and measure the cost of each.
• Fail-open vs. fail-closed as a declared policy. JEV_MODERATION_FAIL forces the organisation to say out loud what happens when the vendor is down. For a kids' platform or a marketplace with regulatory exposure, the answer differs from a hobby forum. Getting this onto a decision log before launch, rather than after an incident, is a governance win.
• Moderator headcount and operations planning. jev-moderation:stats returns flags and blocks per category and, crucially, how often moderators upheld automatic decisions. That is the input to "do we need one moderator or three?", "is our community policy over-flagging?", and "which categories are eating reviewer time?" It converts a staffing question into a measurable one.
• Policy tuning as a product cadence, not a code change. Presets (community, chat, strict), per-category review_above/block_above thresholds, and an uncertain_below confidence floor are configuration. Product can own tone and strictness per surface — a chat product and a marketplace need different tolerances — and jev-moderation:rescan lets you re-evaluate history after a threshold change, with a billing warning built in. That is an unusually mature loop for a v0.1.
• Audit, appeals and regulatory readiness. Append-only decisions (enforced by DecisionsAreAppendOnly), policy version hashes, answering model version, request ids and optional content hashes give you a defensible record of why a piece of content was hidden and who saw what. This is what turns "the AI blocked it" from an unanswerable support ticket and a legal liability into a reviewable decision. It supports appeals workflows, DSA-style transparency obligations, and enterprise/customer trust questionnaires.
• Cost modelling and unit economics. Every check is billed, and the package surfaces that honestly: sync mode exists but is explicitly retry-less, store_content defaults off to limit data retention, and rescan asks before spending money. That makes moderation cost a per-post variable you can model against ARPU and abuse rates before committing to a launch volume.
• Scale decisions deferred, not blocked. The optional moderation_status column (jev-moderation:add-column) backfills from decision history and switches visibility scopes from joins to an indexed column. This is a deliberate "cheap now, fast later" path — you can launch on the simple schema and take the performance migration when volume justifies it, without a rewrite.
• Vendor leverage and exit optionality. The ModerationDriver contract, JevModeration::extend(), and JevModeration::fake() mean Jev is a swappable component, not a foundation. That materially weakens the "what if the vendor raises prices / pivots / is acquired" objection, and lets you A/B a second provider on the same decision schema later.
• Roadmap sequencing for review tooling. flagForReview(), approve(), reject(), moderateNow(), the ContentReported/ReviewResolved events and the query scopes are the backend for a moderator console. Product can plan the console as a thin UI over an already-specified API, and prioritise it against automated-only moderation with clear evidence of where automation falls short.

When to Consider This Package

Adopt when:

• You are on Laravel and PHP with moderated content in Eloquent models. There is no meaningful portability argument here; the value is the trait, the job pipeline and the migration, all of which are Laravel-native.
• You are shipping or already running user-generated text and currently have no systematic moderation, or have ad-hoc keyword filters that generate either too much noise or too little coverage.
• You need an audit trail and reviewer actions, not just a block/pass boolean — appeals, user reports, moderator overrides and "who hid this and why" are first-class here.
• You want policy and thresholds owned by product, with the ability to retune per surface and re-scan history after a change.
• You can tolerate a young, pre-1.0 dependency and are willing to pin a version, read the changelog on upgrades, and keep the moderation path behind an interface you control. The append-only decision schema makes the data durable even if the package is later forked.
• Your team has no ML/T&S specialist but does have Laravel engineers and a moderator or community manager. This is the profile the package is shaped for.
• You want test coverage of moderation behaviour. The FakeDriver with classification assertions makes "content gets blocked" a testable requirement rather than a manual QA step, which matters if moderation is a launch gate.

Look elsewhere, or defer, when:

• You are not on Laravel. Reimplementing the decision model and job pipeline elsewhere is straightforward in concept but is exactly the work this package removes; the value does not survive translation.
• You need more than text. The release notes describe text classification against a policy. Images, video, audio and file uploads are out of scope; a platform whose abuse risk is primarily visual needs a different or additional tool.
• You need a moderator UI, queues with SLAs, escalation, and reviewer management. This is the backend and the events. If the requirement is "a working review console by next month," you are buying a platform (or building the UI on top of these events) — budget for that explicitly.
• Regulated or enterprise contexts that require a certified vendor relationship. If procurement needs SOC 2, a DPA, contractual SLAs, content-residency guarantees and named support, a v0.1.0 open-source package plus a startup API is a harder sell than an established moderation vendor. The package can still be the integration layer, but the commercial risk sits with Jev, not here.
• You need multi-provider consensus or ensemble classification out of the box. The driver contract allows it; nothing ships it.
• Volume is high enough that per-check pricing dominates. The package makes cost visible, but it does not make it small. At very large scale, a self-hosted or flat-rate classifier may be the better economic answer, and the driver contract is the migration path.
• You need zero-downtime, fully supported dependencies. v0.1.0 with a single maintainer implies a bus factor and a semver-minor-can-break risk. That is acceptable for an MVP or an internal tool; it is a harder argument for a revenue-critical system without internal capacity to fork and maintain.
• You require deep customisation of the decision schema itself. Append-only is a deliberate constraint and a good one, but if your compliance model needs mutable or corrected records, you will be working against the design.

How to Pitch It (Stakeholders)

For executives — one paragraph. We can add AI content moderation to the product as a configuration exercise rather than a platform build. This package gives us the three things that are normally expensive: an automatic check on user content, a recorded, tamper-proof decision history we can show a regulator, customer or auditor, and a moderator workflow with reports, approvals and rejections. Estimated effort is days of integration, not a quarter of engineering, and the classifier is a metered vendor API we can swap out — so we are not locked in on price or roadmap. The two decisions we need from leadership are policy, not technology: how strict we are per surface, and what happens when the vendor is unavailable.

For engineering — the short version. A Moderatable trait plus a #[Moderate] attribute hooks every save path — HTTP, jobs, Livewire, seeders — and appends a pending decision; unchanged content and unrelated column updates are skipped, so it does not fire on noise. A queued job classifies after commit, with retry classification that distinguishes 429/529/5xx/timeouts from permanent failures, and records a failed decision when it gives up rather than throwing into the request path. Visibility is enforced by a global scope driven by config (mode, fail), with escape hatches (withoutModeration(), onlyFlagged()) and a per-model moderation_status column option to drop the join at scale. Decisions are append-only by exception — DecisionsAreAppendOnly — which is the right call and means corrections are new rows, not updates. Everything external is behind a ModerationDriver contract, and JevModeration::fake() plus assertClassified() means the moderation path is unit-testable with no network. jev-moderation:install, :ping, :rescan and :stats cover setup, credentials diagnosis, re-evaluation and reporting.

For the trust & safety / community lead. You get thresholds you can change without a deploy, three policy presets as starting points, per-category tuning, a confidence floor for "flag it, do not decide it," and a stats view that tells you how often your team overrode the machine. rescan lets us re-run history after a policy change, with a cost prompt. flagForReview, approve and reject are the primitives for a review console; reports on already-blocked content are recorded without resurrecting it.

For finance and legal. Per-check API cost is a per-post variable; store_content defaults off so we retain hashes, not user text, unless we choose otherwise. Decisions carry a hash of the policy and the model version that produced them, which is the artefact appeals, audits and enterprise security reviews will ask for.

The caveats to state plainly. This is a v0.1.0 release; it is text-only; it provides no moderator UI; and it depends on a single external classifier whose commercial terms and reliability are outside our control. We should pin the version, keep the driver interface as our boundary, and treat "vendor is down" as a rehearsed scenario rather than an assumption. Subject to those, it is a low-cost, high-leverage way to make moderation a product feature instead of a future blocker.