Sulu Spam Protection Bundle Laravel Package

Getting Started

This release (v1.0.3) adds a translate field plus additional translations, so the first move is to confirm what actually changed in the package internals before wiring it into an app.

• Read the diff, not just the notes. The release note is one line. Run composer update <vendor>/<package> and inspect git diff v1.0.2..v1.0.3 in vendor/. You are looking for: a new migration or column definition (the "translate field"), new translation keys/JSON files (the "extra translations"), and any signature changes on the trait, contract, or facade.
• Check published assets are stale. If you previously ran php artisan vendor:publish, your copies of config and language files will not contain the new translations. Re-publish with --force into a scratch dir and diff against your app copies, merging by hand rather than overwriting.
• Run the migrations in a throwaway environment first if the translate field ships as a schema change. Verify whether it is additive (a new nullable column) or a rename/backfill, which changes your rollout plan.
• First use case: add the translate field to one low-risk model, render the form, save, and confirm the value round-trips per locale before touching anything user-facing.

If the repository has a CHANGELOG.md or upgrade guide, read that next — one-line release notes for a package that touches persisted schema are a signal to verify rather than assume.

Implementation Patterns

Attach translation to models deliberately. The core day-to-day pattern is a model declaring which attributes are translatable and the package resolving them per locale. Keep that declaration in the model (a $translatable-style property or trait method), not scattered in controllers, so the set of translatable fields is greppable in one place.

Per-locale form handling. The usual workflow is a form request that validates locale-keyed input (title.en, title.fr) or a nested array (title => ['en' => ..., 'fr' => ...]), then a single save. Validate each configured locale with the same rule set generated from config('app.locales') so adding a locale does not silently skip validation.

Fallback resolution belongs in the read path. Decide once whether a missing translation falls back to the default locale, returns null, or returns the raw key. Set it in the package config rather than sprinkling ?? $model->title in Blade. With extra translations arriving in this release, check whether fallback behaviour or the locale list changed.

Use it in API resources, not raw attributes. Serialise through an API Resource or a toArray() override that calls the package's accessor, so clients receive a predictable shape. Returning the raw JSON column leaks every locale including drafts.

Seeding and imports. When importing content, write the translate field as a structured array keyed by locale in one pass. Batch this — per-locale save() loops on large imports are the common performance trap.

Testing. Assert on both the happy path and the fallback path: a translated attribute in a non-default locale, and one where the translation is absent. If the package registers its own locale resolver, use its testing helper or set the locale in setUp() so tests do not depend on ambient state.

Gotchas and Tips

• One-line release notes on a schema change is the main risk here. Treat v1.0.3 as potentially requiring a migration and a re-publish. Pin to 1.0.3 explicitly, deploy to staging, and confirm the column exists and is populated before rollout.
• Locales in config vs. locales in data. The extra translations shipped with this release probably add language files. Those only help if the app's locale list matches. Mismatched lists produce silent untranslated output, not an error — the hardest bug class here.
• JSON column quirks. Storing translations as JSON means where('title', 'x') will not match; you need driver-specific JSON path queries (whereJsonContains, -> syntax) and MySQL 5.7+/Postgres/SQLite 3.9+ awareness. Verify the package does not abstract this differently than you assume.
• Eager loading does not help. Translatable accessors read from the same row; the N+1 risk is elsewhere. Do not add with() for translation attributes and assume a win.
• Debugging missing translations. Log the resolved locale and the raw stored value together, not just the rendered output. Ninety percent of "translation is broken" reports are a wrong locale, a stale published language file, or a non-persisted save.
• Cache invalidation. If you cache rendered fragments or API responses, translation changes will not appear until the cache clears. Tag or version the cache key by content updated_at.
• Extension points: the package's locale resolver and the translation loader are the two seams worth understanding. If the resolver is bound in the container, you can swap it for a request-header or user-preference resolver without forking.
• Rollback plan. Before adopting the new translate field in production, confirm you can drop the column without data loss and that the previous package version reads a database that has it. Additive and nullable should mean a clean rollback; anything else needs a documented backfill.