Cms Laravel Package

Getting Started

The sn-cms package ships a published config file (config/sn-cms.php) that drives its behaviour, and this release exposes the global search configuration as a first-class, overridable channel. Start here:

1. Publish the config if you haven't already: php artisan vendor:publish --tag=sn-cms-config.
2. Open config/sn-cms.php and locate the search key. This is the "整节透传" (whole-section pass-through) block referenced in the release — everything under sn-cms.search is handed to the search module as-is, so treat it as the public contract.
3. The quickest first win is the results-page search box placeholder:

// config/sn-cms.php
'search' => [
    'placeholder' => 'Search articles, pages, and media…',
    // ...other search keys
],

Your first real use case is almost always branding/localisation: giving the global search box a placeholder that matches your site copy (or a __('...') translation key) instead of the package default.

Implementation Patterns

Per-module overrides over global edits. The point of the new pass-through channel is that a module can declare its own search config rather than you editing the vendor config. Prefer overriding sn-cms.search from your application/module config (or an environment-specific config file) and leave the published defaults intact — this keeps upgrades from v1.0.15 onward non-destructive.

Treat search as an atomic block. Because the whole section is passed through rather than deep-merged, the cleanest pattern is to define the complete search array in one place in your app config and let it win:

// config/sn-cms.php (application copy)
'search' => array_merge(
    require base_path('vendor/.../config/sn-cms.php')['search'] ?? [],
    [
        'placeholder' => __('site.search_placeholder'),
    ],
),

If you only need one or two tweaks, this merge keeps you from silently dropping keys the package expects.

Placeholder as a translation concern, not a hardcoded string. The results-page search box forwards placeholder straight through, so put a translation key there and manage copy in lang/ per locale. This is the lowest-friction way to support multi-language sites without touching PHP.

Integration tip — verify the wiring end to end. After changing the config, hit the global search results route in the browser and confirm (a) the placeholder renders in the input's placeholder attribute, and (b) the value is escaped correctly if you included quotes or apostrophes.

Workflow for module authors. If you're building a module that plugs into global search, expose its own defaults under your module's config and let the host application's sn-cms.search override them. Document which keys you read so downstream apps know what's overridable.

Gotchas and Tips

Config caching will bite you. sn-cms.search is read from config at runtime; if you're running php artisan config:cache in production (you should be), any edit to the search block requires php artisan config:clear && php artisan config:cache. A stale cache is the single most likely reason "my placeholder didn't change."

Pass-through means no validation for you. Because the entire search section is forwarded, a typo'd key (e.g. placehoder) fails silently — the package renders its default instead of erroring. Debug with:

php artisan tinker --execute="dump(config('sn-cms.search'));"
# or
php artisan config:show sn-cms

Beware shallow array merging. Laravel's mergeConfigFrom (and most hand-rolled merges) are shallow at the top level — a nested search array in your app config can wipe out sibling keys. Either define the full block or use array_replace_recursive.

Placeholder is user-facing and echoed into HTML. If you're pulling the value from a DB setting or CMS-editable field, make sure it's escaped (Blade {{ }}, not {!! !!}) and that you're not introducing an XSS vector through an admin-editable string.

Extension point to watch. The sn-cms.search channel is the intended seam for module-level customisation. If a future release deep-merges this section or renames keys, your overrides could shift — pin the package version and re-check this block on upgrade. Watch the changelog for any move away from "整节透传" semantics.

Localisation quirk. If you pass a translation key as the placeholder, ensure the locale is resolved before the search view renders; in queued/CLI contexts the placeholder may resolve to the fallback language.