User Bundle Laravel Package

Getting Started

Step 0 — settle the framework question before anything else. integrated/user-bundle uses Symfony's packaging vocabulary ("Bundle"), and its Bitbucket host plus zero dependents strongly suggest an internal Symfony artifact. Laravel has no bundle loader: a class extending Symfony\Component\HttpKernel\Bundle\Bundle will not register from config/app.php, and its DependencyInjection/*Extension.php, Resources/config/services.yaml, and compiler passes assume a Symfony container. Confirm in 60 seconds:

git clone https://bitbucket.org/eactive/integrated-user-bundle.git
cat composer.json                       # look for symfony/*, doctrine/*, illuminate/*
find . -name "*Bundle.php" -o -name "services.yaml" -o -name "*Extension.php"
find . -path "*migrations*" -o -path "*Entity*" -o -name "User.php"

• Symfony classes + Doctrine entities present → not installable in Laravel. Go to the "reference implementation" path below.
• Only illuminate/* deps, a ServiceProvider, a Migrations/ dir → evaluate as a normal package, but you still need a Composer entry.
• No framework deps at all → best case; extract and wrap.

Consuming it from a Laravel app (either of the two viable buckets). It is not on Packagist, so add a VCS repository and authenticate non-interactively:

"repositories": [
  { "type": "vcs", "url": "https://bitbucket.org/eactive/integrated-user-bundle.git" }
],
"require": { "integrated/user-bundle": "dev-main#<commit-sha>" }

export COMPOSER_AUTH='{"bitbucket-oauth":{"bitbucket.org":{"consumer-key":"...","consumer-secret":"..."}}}'
composer update integrated/user-bundle --prefer-source

Pin a commit SHA. There are no tags, so ^1.0 will resolve to nothing and dev-main will silently drift.

Where to look first, in order: composer.json (deps + license), the bundle extension / service provider (what it actually registers), the user entity/model (what schema it owns), Resources/migrations or database/migrations (what it will run), and any security/guard config (whether it wants to own authentication).

First real use case. Do not point this at consumer signup. The honest first use case for a Laravel team is internal admin/staff user CRUD and role metadata — the back-office surface where "good enough, shipped" beats bespoke, and where a bad day is an annoyed ops person rather than a locked-out customer. If you cannot get there in a throwaway app in two days, stop.

The "reference implementation" path (likely outcome). If it is Symfony-only, the day-to-day leverage is that you read it and port the domain: the User entity fields, the role model, the password policy rules, the reset-token flow. That is a half-day of reading that can save you a week of design deliberation on role semantics — which is a legitimate, if unglamorous, return.

Implementation Patterns

Keep Laravel's Auth manager as the source of truth. Whatever you take from the bundle, do not let it own the guard. Bind to Illuminate\Contracts\Auth\Guard and Illuminate\Contracts\Hashing\Hasher as usual; treat the bundle's classes as domain data only. If the package ships its own session handling or password hashing, that is a red flag — isolate or discard it.

Adapter + interface boundary. Wrap everything in a first-party contract so the identity layer stays swappable. This is the single highest-value pattern here, because you are adopting unmaintained code:

// app/Contracts/UserDirectory.php
interface UserDirectory {
    public function find(int $id): ?UserProfile;
    public function assignRole(int $id, string $role): void;
    public function rolesFor(int $id): array;
}

// app/Providers/UserBundleServiceProvider.php
public function register(): void
{
    $this->app->singleton(UserDirectory::class, function ($app) {
        return new BundleUserDirectory(
            $app->make(\Integrated\UserBundle\Repository\UserRepository::class)
        );
    });
}

Bind in config/app.php (Laravel 10 and earlier) or bootstrap/providers.php (Laravel 11+). Every call site talks to UserDirectory, never to the bundle.

Mirror, then path-repository. Clone the repo into your internal Git host and depend on the mirror. This removes Bitbucket credentials from every CI runner and survives upstream deletion — a realistic outcome for a repo with this profile.

"repositories": [{ "type": "path", "url": "../vendor-mirror/user-bundle" }]

Capture migrations as a baseline, do not run them. If the package ships migrations, publish them once, edit them to match your conventions (timestamps, index names, uuid vs bigIncrements), commit them as your migration, and never re-publish. You own the schema from that moment.

Dual-guard avoidance. If the bundle wants a security.yaml firewall, it does not map to Laravel's config/auth.php guards. Pick one: either the bundle's authentication or Laravel's. Mixing produces a split-brain where Auth::user() and the bundle's own identity object disagree after a session refresh.

Shadow-read rollout. Write the new path behind a feature flag; run it alongside existing auth in production reading the same user rows, comparing outputs, before flipping the write path. This is worth the extra day on any identity change.

Port the value objects, not the framework glue. The genuinely reusable pieces in a bundle like this are usually PasswordPolicy, Role, Permission, and reset-token semantics — plain PHP. The Symfony/Symfony-Security plumbing is what does not survive the crossing. Copy the former into app/Domain/Identity/, reimplement the latter natively.

Test at the boundary, once. Write integration tests against UserDirectory covering registration, login, logout, password reset, and role enforcement. Because there are zero external eyes on this code, your tests are the only regression net you will get.

Gotchas and Tips

ServiceProvider is not a Bundle — and the failure is silent. Registering a Symfony bundle in Laravel does not throw; it just does nothing, and you spend an afternoon wondering why $app->make(...) returns an unbound class. If you see DependencyInjection/ or Resources/config/, stop and confirm the target framework.

Doctrine will drag a second ORM into an Eloquent app. A doctrine/orm dependency in a Laravel project means a parallel connection, entity manager, proxy cache, and migration story. Rarely worth it. Check composer.json before composer require; composer why doctrine/orm after.

Password hashes are a blast radius, not a detail. If the bundle hashes with a different algorithm or cost than your existing users.password, you cannot mix them. Verify before migrating any user row; a failed rehash on production credentials locks out your whole base. Hash::info($hash)['algoName'] on a sample is your go/no-go.

No tags means no semver. composer update on dev-main will happily pull a force-push. Pin the SHA in composer.json, commit composer.lock, and treat any upstream bump as a code review, not a routine update.

Bitbucket auth in CI. COMPOSER_AUTH with an app password works, but every runner needs the secret, and the credential leaks into build logs if you are careless. The mirror-path pattern above is the fix; use it from day one rather than retrofitting after the first broken pipeline.

No license metadata. composer.json with no license key means legal review is a blocking prerequisite for SaaS distribution. Treat "unknown" as "proprietary" until told otherwise, and get the answer in writing.

Config trees do not translate. Symfony's Configuration.php tree builder (->children()->scalarNode()) has no Laravel analogue. Map it into config/user-bundle.php returning a plain array, and validate it in your service provider with Validator if the defaults matter.

Events are a different dispatcher. Symfony\Contracts\EventDispatcher\EventDispatcherInterface and Laravel's Illuminate\Contracts\Events\Dispatcher do not share a bus. If the bundle dispatches UserRegisteredEvent, you will need a bridge listener that re-dispatches onto Laravel's dispatcher, or you will silently miss the hook. Grep for dispatch( first.

Debugging means reading the source. With no docs, no community, and no issue tracker, dd() in your adapter and grep -rn across the mirror are your tools. Keep a NOTES.md in the adapter directory recording what each bundle class actually does — it is the only mitigation for the knowledge-concentration risk.

Fork-and-patch runbook. You will eventually hit a bug with no upstream fix. Decide now where the fork lives, who merges into it, and how you bump the SHA. Write it down before you need it at 2am.

Extension points are limited to your adapter. Do not subclass or monkey-patch bundle internals; override behaviour at the UserDirectory seam. That is the only layer you can upgrade, replace, or rip out without touching call sites — and given this package's adoption profile, "rip out cleanly" is a feature you should design for on day one.