In Other Shops Laravel Package

Getting Started

Upgrade to v0.54.0 before touching order/admin or storefront search if any consumer stores catalog name/description in the translations table. Column-backed catalogs are unaffected, but the release is additive and contains a required fix for translatable catalogs.

Look first at docs/periphery.md → “Catalog text is not a column”. Then inspect Commerce\Filament\CommerceSchema::buildOrderableOptions() if you customize the order admin, and Storefront\Actions\ListBrowsables if you extend storefront listing/search behavior.

First use case: render labels through the new public API instead of assuming a name column:

use Support\ModelLabel;

$label = ModelLabel::for($model);
// name -> title -> label -> slug -> "{alias} #{id}"

It is never null and never empty, and it resolves through getAttribute() so it works with InteractsWithTranslations.

Implementation Patterns

• Use model behavior for labels. Prefer ModelLabel::for($model), getBrowsableName(), and getCartableLabel() over direct $model->name reads. The contract is methods, not columns.
• Keep Filament order options on the package path. Continue using CommerceSchema::buildOrderableOptions() for orderable option lists. Option keys remain {alias}:{id}; do not reimplement them with pluck('name', 'id').
• Use translation-aware queries for search/sort. ListBrowsables no longer does where('name', 'like') or orderBy('name'). If you extend storefront listing/search, filter and sort through translation-aware joins/subqueries or package-supported scopes, not raw column names.
• Audit custom admin resources. Any custom Filament table, filter, export, or option builder that reads name/description directly should be converted to ModelLabel::for() for display and translation-aware queries for filtering.
• Add translatable fixtures to your test suite. Use TestTranslatableCartable and TestTranslatableBrowsable as templates. Keep column-backed fixtures too so both catalog shapes are covered.
• Test query behavior against MySQL. SQLite is useful for fast unit coverage, but not for catching missing-column query bugs in this area.

Gotchas and Tips

• SQLite can hide this class of bug. Laravel’s double-quoted identifiers hit SQLite’s string-literal behavior, so where('name', ...) against a missing column can silently become WHERE 'name' ... and orderBy('name') can become a no-op. Do not trust a green SQLite suite for query-level catalog assumptions.
• Unknown column 'name' in 'field list' on order show/edit means old code is still using pluck('name', 'id') or equivalent. Check package version first, then audit custom Filament code.
• Model access works; query access does not. InteractsWithTranslations overrides getAttribute(), so $model->name and ModelLabel::for($model) can work while where('name') still fails. The contract never promised a name column.
• Search-box failures may be latent. The storefront listing fault would surface on first use of search. Exercise search explicitly after upgrading, even if the catalog pages currently load.
• Signatures and {alias}:{id} option keys are unchanged. This is additive at the API level, but the fix is mandatory for translatable catalogs.
• ModelLabel::for() is a safe fallback, not a data guarantee. It always returns a string, but the final fallback still depends on alias/id. Use it consistently instead of ad hoc ?? chains.
• Add regression coverage for ListBrowsables. It previously had no direct tests; add integration coverage around the search box and option building with translation-backed models.