Df User Laravel Package

Getting Started

dreamfactory/df-user is not a package you composer require into an existing Laravel app — it is a DreamFactory platform module that ships inside the dreamfactory/dreamfactory distribution. Your "day one" steps are therefore about operating the platform, not wiring up a provider.

1. Confirm it's present. composer show dreamfactory/df-user in the DreamFactory root, or grep config/app.php / the package discovery cache for DreamFactory\Core\User\Providers\UserServiceProvider. The module is auto-discovered in a standard install.
2. Read these first, in order:
   • src/Models/User.php — Eloquent model, $hidden, $fillable, password mutator, getAuthIdentifierName().
   • src/Models/Role.php and UserApp.php — the RBAC and app-scoping relationships.
   • src/Services/User.php — the BaseSystemResource subclass that maps HTTP verbs to model operations and defines the OpenAPI schema.
   • database/migrations/ — user, role, user_role, and lookups.
3. Run the setup once: php artisan dreamfactory:setup (or df:refresh --seed in dev) so the module migrations and default roles (admin, user) exist.
4. First use case — authenticate and inspect: POST /api/v2/user/session with {"email":"...","password":"..."} returns a session token plus the user record. Then GET /api/v2/system/user/{id} with that token. This is the fastest way to see what the package actually exposes before you touch code.

If you're integrating an existing Laravel app, treat DreamFactory as a user/auth backend and call those REST endpoints from a Laravel HTTP client rather than trying to embed the module.

Implementation Patterns

API-first consumption. Almost everything you need is a platform endpoint: system/user for admin CRUD, user/register for self-service signup, user/password for change-password, user/request_password_reset + user/password_reset for the reset flow. Wrap these in a small Laravel service class so the rest of your app never sees raw DreamFactory URLs.

Custom fields. To add profile data (phone, tenant_id, preferences), create a new migration in your own DreamFactory package that alters the user table, and extend the User model via a model-extending event or a subclassed service. Do not edit the vendor directory — your changes vanish on composer update.

Event scripts for business logic. DreamFactory fires pre/post events per service operation (user.get.pre_process, user.post.post_process, system.user.create.post_process, etc.). Register listeners in your own package's service provider:

Event::listen('df.user.post.post_process', function ($event) {
    // $event->request, $event->response, $event->resource
    Mail::to($event->response->content['email'])->queue(new WelcomeMail(...));
});

This is the sanctioned extension point for onboarding emails, audit logging, and syncing users into an external IdP.

Roles as the integration seam. Assign roles on create/update via the user_role pivot; roles bind to apps, services, and system resources. In practice you create one role per API surface (e.g. mobile-app, admin-console) in the admin UI and just set role_id on user records from your provisioning code.

Testing. Hit the endpoints with a php artisan tinker HTTP call or a Pest test using Http::withToken($sessionToken)->post(...). Faster feedback than clicking through the admin console.

Gotchas and Tips

• Version-lock to the platform. df-user is tightly coupled to dreamfactory/dreamfactory and df-core. A stray composer update on the module alone will break the service registration. Pin both.
• Migrations are platform-managed. Don't run php artisan migrate blindly; use dreamfactory:setup / df:refresh so ordering and seeding (default roles, admin user) happen correctly.
• Password handling is Laravel's hasher. The model mutates password with Hash::make. If you backfill users from a legacy system, insert pre-hashed bcrypt strings — never plaintext — and set the mutator bypass deliberately.
• is_sys_admin is a big hammer. It bypasses role checks entirely. Prefer a scoped role for anything short of true platform administration, and audit any code path that sets it to true.
• Cache invalidation. Role and service lookups are cached; after changing a user's roles or an app's services, the affected session may keep stale permissions until the token expires or the cache is cleared (php artisan cache:clear / the platform's cache-clear endpoint). Budget for this in tests.
• Legacy columns. confirm_code, reset_password_code, and oauth_provider are vestigial in newer flows; check src/Services/User.php for which are still honoured before building on them.
• Extension points, in order of preference: event scripts → a sibling custom package that listens to events → subclassing the service and re-registering it in config. Never fork the repo.
• Debugging. Set APP_DEBUG=true in the DreamFactory .env and tail storage/logs/laravel.log; service exceptions surface as JSON with a error.code — cross-reference it against the module's exception classes rather than guessing.
• Zero dependents on Packagist means no community examples to crib from. When stuck, read src/Services/User.php and the df-core base classes; that's the real documentation.