Vendra User Laravel Package

Getting Started

• Install with composer require misaf/vendra-user. Be aware this repository is a read-only subtree split of the misaf/vendra monorepo — issues, PRs, and full history live upstream at misaf/vendra under packages/vendra-user. File bugs there, and check composer.json for the Laravel/PHP constraints before bumping.
• Know the namespace up front: everything is Misaf\VendraUser. Your first three stops are:
  • src/Models/User.php — the canonical user entity and its relationships (profile, addresses, tags).
  • The package service provider — it registers TenantTableRegistry entries, model bindings, routes, and Filament panel wiring.
  • database/migrations — required columns, foreign keys, and which tables call TenantSchema::addTenantColumn().
• Publish and review config/migrations before migrating. Confirm the exact publish tags in the service provider (vendor:publish with --tag=); typical Laravel packages expose config, migrations, and translations separately. Read config/vendra-user.php for table names, connections, route prefixes, middleware, and model bindings.
• Run php artisan migrate, then verify tenancy: any table whose migration calls TenantSchema::addTenantColumn() must be registered with TenantTableRegistry in the package service provider so vendra-tenant:enable {tenant} can retrofit pre-existing schemas.
• First use case, greenfield: use the package User model directly and add your domain fields in your own migration. First use case, existing app: keep App\Models\User, implement the package contract, and pull in the package trait rather than swapping the model wholesale.
• Sanity-check your environment immediately with the package's own gates: php artisan test --compact --testsuite=vendra-user and composer stan. If those pass on a clean install, your Laravel/PHP versions and dependency graph are compatible.
• If you're working inside the monorepo, use Laravel Boost application-info and search-docs before editing, and apply the laravel-best-practices skill to any Laravel PHP you touch.

Implementation Patterns

• Compose, don't replace. For brownfield apps, implement the package user contract on your existing model and use the trait. For greenfield Vendra storefronts, extend the package model. Either way, config/auth.php providers, password brokers, gates, and policies must all point at the same class.
• Create users through the package's registrar/service. Direct User::create() bypasses profile creation, address bootstrapping, and domain events. Use the package registration path, then attach your own data in a listener or follow-up action so you keep the decoupling.
• Address handling. Use the package address model and relationships for customer addresses; eager load them whenever you list customers or render account/checkout pages. Override address validation in a form request rather than editing vendor code — country-specific formatting and rules are config-driven.
• Translatable persistence is an explicit domain decision. If you add a field to a model's $translatable array, that column must be JSON, and you must carry translation-awareness through traits/casts, factories, validation, Filament locale UI, API serialization, and tests. Conversely, a field not in $translatable must use a scalar column and must not use Spatie Translatable, translatable slug traits, locale switchers, or translated callbacks.
• Tags are optional and package-agnostic. Any tag-consuming model uses Misaf\VendraSupport\Capabilities\HasOptionalTags as the single source of its tags() relationship and pivot metadata. Define a stable package-owned tag type, use TagIntegration for availability and UI integration, and never import the concrete Vendra Tagger model/provider or define the relationship through Spatie HasTags. Tagger belongs under Composer suggest, not require.
• Filament admin UI ships in this module. User domain behavior and the Filament admin classes live in packages/vendra-user; extend resources/pages there rather than duplicating them in the host app.
• Social login is out of scope here. SocialiteUser, SocialiteRegistrar, and the filament-socialite wiring live in the separate misaf/vendra-socialite package. Don't reintroduce them, and don't add a dutchcodingcompany/filament-socialite dependency to this package.
• Respect the module boundary. Models, factories, seeders, policies, observers, console commands, Filament classes, config, migrations, translations, and tests all stay inside Misaf\VendraUser. The host app should only integrate the module, not host user-domain code.
• Testing convention. Add focused Pest coverage for any change, keep factories in-module, and run the package suite plus static analysis before pushing. Create users through the package service in test setup so profiles/addresses are consistent, and assert relationships and dispatched events explicitly.
• Events over edits. Hook registration and profile-update events for onboarding emails, CRM sync, and default-address creation. This is the extension point that survives upgrades.
• API/UI surface. If the package registers routes or views, either consume them or disable them in config and expose your own controllers/resources. Wrap package models in API resources so internal columns (tenant IDs, tag pivots) don't leak.

Gotchas and Tips

• Translatable field mistakes are the most common self-inflicted bug here. A field added to $translatable without a JSON column (or a scalar field that sneaks into a translatable trait) will pass review and fail at runtime or, worse, silently store arrays in a varchar. Audit factories, validation, and Filament locale tabs together whenever you touch it.
• Tenant registry omissions only surface later. A table migrated with TenantSchema::addTenantColumn() but missing from TenantTableRegistry won't be retrofitted by vendra-tenant:enable {tenant}. Preserve configured table names and connections when registering — hardcoding them breaks multi-connection setups.
• Don't over-require Vendra dependencies. A Vendra dependency intentionally exposed through the public API of a directly required Vendra platform package is part of that package's supported contract — don't add a redundant direct require. This applies only to Vendra platform packages under require; never extend it to require-dev, suggest, incidental implementation dependencies, or third-party packages. Removing or replacing an exposed dependency is a breaking change, and self.version must stay aligned across the Vendra package graph.
• Config caching. After publishing or upgrading, run php artisan config:clear before config:cache. New keys in a release are invisible while a stale cached config is active — this is the classic "the config file clearly says X" false alarm.
• Upgrading from v1.11.0 to v1.12.3 is opaque. The release note is only a compare link, so there are no itemized changes. Diff published config and migrations between the two tags, and re-run registration, login, profile update, and address flows in staging. Pin v1.11.0 as your rollback target.
• Migration ordering. Package migrations may assume users already exists. With an existing users table, adjust timestamps or skip the package's user-table migration rather than editing published files — add your own columns in a separate migration.
• Model swap fallout. Switching the auth provider to the package user model touches password resets, remember tokens, policies, and every relationship referencing App\Models\User. Update all references, not just config/auth.php.
• Route and middleware collisions. If the package registers account/customer routes, disable them in config when you have your own, or you'll get duplicate route names and stacked middleware.
• Debugging relationship weirdness. Use DB::listen() or Telescope to inspect queries when profile/address relations misbehave, then cross-check foreign key column names against the published config — mismatches there are silent until a null relationship appears.
• Stay out of vendor. Custom user models, event listeners, view overrides, and separate migrations are the supported extension points. Editing published package files guarantees a painful next upgrade.
• In the monorepo, keep edits inside packages/vendra-user and preserve public contracts. Run php artisan test --compact --testsuite=vendra-user and composer stan locally; apply the tailwindcss-development skill only when you actually change Blade markup or Tailwind classes.