Generator Bundle Laravel Package

Getting Started

This is the first public release (v1.0), so treat the package as young and pin it in composer.json ("vendor/package": "1.0.*" or an exact constraint) until you've validated it against your codebase.

Minimal steps:

1. composer require vendor/package — Laravel package auto-discovery should register the service provider; if not, add it manually to config/app.php.
2. Publish the config if the package ships one: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider". Commit the published file so environment drift is visible in review.
3. Since v1.0 has no extensive docs, read the service provider and the config file first — they are the real API surface for this release. Then run php artisan list to see whether the package registers any commands.
4. Run the package's own test suite or a smoke script before wiring it into application code.

First use case: generating or resolving class names (the release notes' only known issue concerns class-name generation and FQN handling). Start with a single, isolated call site — e.g. one generator command or one config-driven class map — and inspect the raw output before it reaches anything that consumes it.

Implementation Patterns

Normalize at the boundary. Because generated names may or may not be FQN, wrap the package in a thin application-level service rather than calling it from many places:

final class ClassNameResolver
{
    public function resolve(string $name): string
    {
        return ltrim(app(PackageContract::class)->resolve($name), '\\');
    }
}

Everything downstream then receives a single canonical form, and you have exactly one place to patch when the known issue is fixed upstream.

Normalize on input, not just output. If the package accepts class names as arguments, pass fully-qualified names built with ::class (which never carries a leading backslash). That avoids triggering the non-FQN code path entirely where possible — it is the cheapest workaround for the v1.0 bug.

Config-driven class maps. If the package is configured with a map of names to classes, keep the mapping in a dedicated config file and resolve it through your wrapper. Add a test that asserts every mapped class is class_exists() and that the string has no leading backslash, so a bad entry fails in CI rather than at runtime.

Use it behind an interface. Bind the package's contract/implementation in a service provider and type-hint your own interface in application code. This release is v1.0; the odds of an API change in v1.x are high, and a single binding isolates you from it.

Test both branches explicitly. Write data-provider tests covering FQN input (App\Models\User) and non-FQN input (Models\User, User) and assert the normalized result. The known issue only manifests on one of those paths, so a single happy-path test will not catch it.

Generation workflows. If you use the package in a scaffolding/generator command, assert the generated file's output rather than only the command's exit code — the leading-backslash defect produces syntactically valid but semantically odd strings, which exit-code assertions miss.

Gotchas and Tips

The leading-backslash bug. When names are not generated with an FQN, v1.0 prefixes them with \. In PHP this mostly "works" (new $class, class_exists('\App\Foo'), and container resolution generally tolerate it), which is exactly why it slips through. It breaks on:

• String comparison and array_key_exists lookups against ::class output ('App\Foo' !== '\App\Foo').
• Anything that uses the string as an identifier: cache keys, config keys, route/event names, log correlation IDs, database columns.
• Equality checks after get_class($object), which never returns a leading backslash.
• Serialized values and API payloads — the backslash leaks into JSON and then into consumers.

Immediate mitigation: normalize with ltrim($name, '\\') at every entry and exit point, and add a CI assertion (str_starts_with($resolved, '\\') should always be false).

Debugging. Print the value with var_dump() rather than echo/dump() when chasing this — a leading backslash is invisible in most log output and in HTML. Log the string's length alongside its value; an off-by-one is a fast signal.

Config caching. Run php artisan config:cache in staging before deploying. Packages that read config at container-boot time behave differently cached vs. uncached, and the first release is a common place for that bug to hide. Always php artisan config:clear after editing the published config locally.

Version pinning. Pin to 1.0.* and upgrade deliberately. Watch the changelog specifically for the FQN fix — when it lands, keep your normalization wrapper (it's harmless and defensive) but delete any workaround logic that compensated for the bug.

Extension points. Before forking or patching, check whether the package exposes a contract or binding you can override in your own service provider — swapping the implementation is usually sufficient to correct string handling without vendoring code. Avoid editing vendor/ directly; the fix disappears on the next composer update.

Report it upstream. The known issue is documented, so file or upvote the tracking issue with your concrete failure case (string comparison, cache key collision, etc.). Reproductions that show semantic breakage, not just cosmetic backslashes, are what get it prioritized.