Domain Maker Bundle Laravel Package

Getting Started

• Install with composer require the package at ^1.0.1, then run composer dump-autoload immediately — v1.0.1 ships an autoload/namespace change and a stale classmap is the most common cause of "class not found" right after upgrading.
• Look first at the package composer.json autoload.psr-4 block and its src/ root. That tells you the authoritative namespace you should be importing (DomainCore\...) and matches the directory layout of the source you'll be reading.
• Confirm the service provider is registered (auto-discovery via extra.laravel.providers, or manually in bootstrap/providers.php on Laravel 11+). If the package publishes config, run php artisan vendor:publish --tag=... before your first call.
• First use case: resolve one class out of the container and exercise it in php artisan tinker — e.g. app(\DomainCore\...\Client::class) — before wiring anything into a controller. That validates namespace, autoloading, and container bindings in a single step.

Implementation Patterns

• Constructor injection over app(). Resolve DomainCore classes through your controller/job/command constructor so the namespace lives in one use statement per file and is trivially greppable during future renames.
• Bind interfaces in a dedicated service provider. If the package exposes contracts, alias them to the DomainCore implementations in your AppServiceProvider (or a small DomainServiceProvider) rather than referencing concrete classes in application code. This is the cheapest insurance against the next namespace move.
• Wrap, don't scatter. Put a thin application-level adapter around the package's client/service and call that from controllers, jobs, and console commands. When the vendor namespace changes again, you edit one file.
• Queue and event payloads. Anything you dispatch should carry scalars or your own DTOs, not the vendor class. Serialized vendor objects in failed_jobs or queued payloads break silently after a namespace rename.
• Testing. Use the container ($this->app->instance(...), swap, or the package's fake if it ships one) so tests assert against the contract, not the fully-qualified DomainCore class name. Keep one smoke test that resolves the real binding so namespace drift fails fast in CI.
• Config-driven behaviour. Prefer the published config file over hardcoded class strings; if the config contains class => ... keys pointing at vendor classes, those are the first lines to audit on every upgrade.

Gotchas and Tips

• The v1.0.1 namespace move is a breaking change in a patch release. Composer will not warn you. Grep the whole app — including config/*.php, database/seeders, tests/, Blade templates, and any string-keyed array — for the old namespace before deploying.
• String references are invisible to static analysis. Morph maps, Relation::morphMap(), factory model properties, validation rule strings, and container keys built with ::class concatenation will all survive a use-statement rewrite and fail at runtime.
• Clear everything after upgrading: composer dump-autoload -o, php artisan config:clear, php artisan cache:clear, and any cached bootstrap files. On Octane, restart the workers — long-lived processes hold the old class strings.
• Config caching hides published config edits. If behaviour doesn't change after a config tweak, check for a stale bootstrap/cache/config.php.
• Check composer.lock diffs, not just the version number. A patch bump that only touches namespaces can still shift transitive constraints.
• Aliases and facades registered in config/app.php under aliases are string-based; rename them in lockstep with the namespace or you'll get "Alias not found" only on the code paths that use them.
• Extension points to lean on: container bindings (swap implementations without touching vendor code), the published config file, and any package events you can listen to instead of subclassing vendor classes — subclassing is exactly what a namespace rename punishes hardest.
• Debugging tip: when you hit a class-not-found after the upgrade, grep -rn "OldNamespace" vendor/ app/ config/ first. If it appears in vendor/, you have a mixed-version install (partial update or a stale composer.lock); delete vendor/ and reinstall rather than patching files by hand.