Setting Bundle Laravel Package

Getting Started

The package is driven by a single Artisan manage command — start there before touching config or code.

1. Install and discover the surface area

   composer require <vendor>/<package>
   php artisan list | grep -i manage
   php artisan help <package>:manage
   

   The command signature (arguments, options, --help output) is the authoritative documentation for what the package can do. Read it before reading the source.

2. Publish and inspect config (if offered)

   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
   

   Check whether the package ships migrations, a config file, or both. Run php artisan migrate if migrations are present.

3. First use case: set a value, then read it back

   php artisan <package>:manage set key "value"
   php artisan <package>:manage get key
   

   As of v1.1.3, the manage command accepts an explicit empty value:

   php artisan <package>:manage set key ""
   

   This is the quickest way to confirm the package is wired up correctly and to verify the release you actually have installed (composer show <vendor>/<package>).

4. Where to look next

   • The command class (src/Console/) — the set/get handling and the validation rules applied to the value argument.
   • The service provider — bindings, singletons, and any cached state.
   • The config file — storage driver, table name, cache key/TTL, default values.
   • The test suite — existing feature tests for the command are the best spec for edge-case behaviour.

Implementation Patterns

CLI-first workflows. Treat the manage command as the primary interface for provisioning and one-off data fixes. It is well suited to deploy scripts, post-deploy hooks, and runbook steps where you want a reproducible, auditable action rather than a Tinker session.

# deploy script
php artisan <package>:manage set feature_flag.enabled "true"
php artisan <package>:manage set announcement.banner ""

Empty value as an explicit "clear". With v1.1.3, set key "" is a real write of an empty string rather than an error or a no-op. Use it deliberately to blank out a stored value where deletion would be wrong (e.g. clearing copy while keeping the record and its metadata). If you want the value gone entirely, prefer the package's delete/unset path if one exists — empty string and absence are now two distinct states, and downstream code should treat them differently.

Wrapping the command in application code. Don't shell out from request handlers. If you need programmatic writes, call the underlying service/repository the command delegates to, and inject it. Keep the command as a thin adapter so both paths stay in sync.

class BannerSettings
{
    public function __construct(private ManageService $service) {}

    public function clear(): void
    {
        $this->service->set('announcement.banner', '');
    }
}

Seeders and factories. For repeatable local environments, call the service from a seeder rather than invoking Artisan, so the operation participates in transactions and doesn't depend on a booted console kernel.

Environment separation. Values written by the command are stored wherever the configured driver points. In CI, always set the driver explicitly for the test environment; never let a test run inherit the production connection.

Multi-tenant setups. If the package is tenant-scoped, resolve the tenant context before invoking the command — typically via an option or by wrapping the call in the tenancy bootstrap. Verify against a second tenant, not just the default one.

Gotchas and Tips

Empty vs. null vs. missing. This is the main behavioural hazard introduced by v1.1.3. Three states now exist:

• key absent → fall back to config default
• key present, value "" → truthy-check bugs (if (!$value), ?:, ?? all treat it as absent)
• key present, value "0" → falsy in PHP; do not treat it as empty

Audit any consumer that uses loose checks or ?? before relying on empty-value writes.

Shell quoting. set key "" works, but unquoted set key followed by another flag will swallow the flag as the value, and set key '' inside a Docker sh -c string can be stripped to nothing. Prefer set key "" and test the exact invocation your deploy script uses.

Validation rules. The command likely validates the value. If a rule such as required or filled was previously applied, the empty-value path may still be rejected depending on how the release implemented it — run it and confirm on your installed version rather than assuming.

Config and route caching. If the package reads config at bootstrap, php artisan config:cache can bake stale values into a long-running process. Re-run the command and, if values are read from config rather than the store directly, clear the cache.

Queued workers. Workers hold booted state and will not see a value written after they started. Restart workers after running the manage command: php artisan queue:restart.

Long-lived processes. Octane, Horizon, and serve daemons behave the same way — anything memoising the value needs a restart or an explicit refresh.

Cache invalidation. If the package caches writes, verify the invalidation path is actually exercised by the empty-value write. Empty strings are a classic source of cache-key collisions when the cache layer coalesces falsy values.

Debugging. Run with -vvv to see the command's own output, and check the package's log channel if it defines one. If a write appears not to persist, compare the configured store against where you're reading from — mismatched driver between command and application is the most common cause.

Extension points. The command class and any bound service are usually resolvable and overridable. For behaviour changes (custom validation, extra side effects such as event dispatch on write), extend the command or rebind the service in a provider rather than forking the package.

Version pinning. The empty-value capability is behaviour, not just a fix. Pin ^1.1.3 if your deploy scripts depend on set key "" succeeding; an older 1.1.x will behave differently and the failure will be silent at the script level.