PHPackages parabellumkoval/backpack-profile - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. parabellumkoval/backpack-profile ActiveLibrary[API Development](/categories/api) parabellumkoval/backpack-profile ================================ Implement user profile API & CRUD for backpack v0.1.1(7mo ago)02711MITPHPPHP ^8.2 Since Oct 4Pushed 1mo ago1 watchersCompare [ Source](https://github.com/parabellumKoval/backpack-profile)[ Packagist](https://packagist.org/packages/parabellumkoval/backpack-profile)[ Docs](https://github.com/parabellumkoval/backpack-profile)[ RSS](/packages/parabellumkoval-backpack-profile/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (4)Versions (3)Used By (0) Backpack Profile ================ [](#backpack-profile) Comprehensive user profile, referral, and wallet subsystem for Laravel applications that use Backpack. The package ships ready-to-use CRUD panels, API endpoints, referral triggers, wallet management, reward distribution, withdrawal workflows, and a Sanctum-based authentication layer that can be consumed from SPA or mobile clients. --- Feature Overview ---------------- [](#feature-overview) - **Profile lifecycle**: automatic profile creation for new users, profile CRUD for admins, REST endpoints for profile self-service. - **Authentication APIs**: email/password registration, login, logout, password reset, email verification, and Socialite OAuth flows (Google/Facebook) with Sanctum personal access tokens. - **Referral engine**: multi-level referral tree, reward events, trigger registry, reward ledger, and configurable payout logic. - **Wallet subsystem**: balance table, ledger journal, hold/release/capture semantics, CurrencyConverter integration, and withdrawal processing workflow. - **Backpack admin UI**: CRUD panels for profiles, referrals, rewards, reward events, wallet ledger, withdrawals, and an analytic dashboard with charts. - **Settings integration**: configuration groups exposed through the Backpack Settings package (currencies, withdrawal thresholds, trigger configuration, etc.). - **Extensibility hooks**: event listeners on user/profile creation, trigger registry, facades/services for programmatic access, publishable assets for overriding views/routes/config. --- Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 12.x - Backpack 6.x (CRUD + Settings packages) - Laravel Sanctum 4.2+ for API tokens - Laravel Socialite 5.23+ for social login (optional) - Database driver that supports JSON columns (MySQL 5.7+/MariaDB 10.2+/PostgreSQL 9.4+) --- Installation ------------ [](#installation) 1. **Install the package** ``` composer require parabellumkoval/backpack-profile ``` 2. **Run migrations** ``` php artisan migrate ``` This creates core tables such as `ak_profiles`, `ak_referral_partners`, `ak_reward_events`, `ak_rewards`, `ak_wallet_balances`, `ak_wallet_ledger`, and `ak_withdrawal_requests`. 3. **(Optional) Publish assets** ``` php artisan vendor:publish --provider="Backpack\Profile\ServiceProvider" --tag=config php artisan vendor:publish --provider="Backpack\Profile\ServiceProvider" --tag=views php artisan vendor:publish --provider="Backpack\Profile\ServiceProvider" --tag=migrations php artisan vendor:publish --provider="Backpack\Profile\ServiceProvider" --tag=routes ``` - Config is copied to `config/backpack/profile.php`. - Views land under `resources/views/vendor/profile` and `resources/views/vendor/backpack/crud`. - Migrations and route stubs are publishable if you need to customize them heavily. 4. **Configure Backpack Settings (recommended)** Register `Backpack\Profile\app\Settings\ProfileSettingsRegistrar` inside your Backpack Settings registrar so that referral, wallet, and withdrawal options become editable from the admin UI. --- Quick Start Checklist --------------------- [](#quick-start-checklist) TaskNotesConfigure `config/auth.php` guardsDefine a `profile` guard if you plan to use profile-authenticated routes.Sanctum personal access tokensEnsure `config/sanctum.php` is set up; SPA/mobile clients should store bearer tokens securely.Socialite credentialsSet `GOOGLE_CLIENT_ID`, `FACEBOOK_CLIENT_ID`, etc., and update `config/services.php`.Currency converter bindingBind `Backpack\Profile\app\Contracts\CurrencyConverter` to your implementation if you need real conversion rates.Settings defaultsReview `config/backpack/profile.php` (currencies, referral levels, middlewares, withdrawal minimums).--- Database Schema --------------- [](#database-schema) TablePurpose`ak_profiles`Profile metadata linked 1:1 with the `users` table (`user_id`). Stores locale, sponsor, marketing opt-in flags, referral code, etc.`ak_referral_partners`Flattened referral tree with parent relationships for fast traversal.`ak_reward_events`Event log for referral trigger executions (pending/processing/processed/failed, reversal support).`ak_rewards`Monetary/points rewards issued to beneficiaries (actor or upline) per event.`ak_wallet_balances`Snapshot of wallet balances per user and currency.`ak_wallet_ledger`Journal of wallet operations (credit/debit/hold/release/capture).`ak_withdrawal_requests`Withdrawal workflow records, including FX metadata and admin actions.`ak_event_counters`Incremental counters for idempotent trigger execution (`subject_type` + `subject_id`).> Note: legacy code still references columns such as `firstname`, `lastname`, and `addresses`. If you rely on these attributes, ensure your schema includes matching columns or adjust the model to align with the published migrations. See `IMPROVEMENTS.md` for known inconsistencies. --- Configuration Highlights ------------------------ [](#configuration-highlights) `config/backpack/profile.php` drives most behavior: - `user_model` / `profile_model`: customize linked Eloquent classes. - `private_middlewares`: middleware stack applied to wallet/withdrawal API routes (defaults to `['api', 'auth.api:sanctum']`). - `referral_enabled`, `referral_levels`, `referral_commissions`: legacy defaults for simple multi-level referral payouts. - `points` group: toggles the virtual points currency used for wallet operations (`key`, `name`, `base` currency backing the point). - `currencies`: list of fiat currencies exposed to the UI; affects select boxes and labels. - `currency_converter`: class implementing `Backpack\Profile\app\Contracts\CurrencyConverter` used by `WithdrawalService` and referral payouts. - `withdrawal` group: enable/disable withdrawals and configure minimum amounts. - `users` group: allow self-registration, require email verification, default role/locale. Backpack Settings extender (`ProfileSettingsRegistrar`) mirrors these options in a GUI-friendly manner. Ensure the registrar is invoked by the host application so admins can manage referral triggers, currencies, and withdrawal policies. --- Backpack Admin Panels --------------------- [](#backpack-admin-panels) Once the service provider boots, the following routes are available under the Backpack prefix (default `/admin`): - `profile` CRUD (`ProfileCrudController`): manage user profiles, inspect balances, sponsors, contact data, and explore the full referral tree via the details row. - `rewards` list (`RewardCrudController`): read-only grid of issued rewards, filters by beneficiary type, amount, currency. - `reward-events` list (`RewardEventCrudController`): inspect trigger executions, re-process or create reversal events. - `wallet-ledger` list (`WalletLedgerCrudController`): journal of wallet movements. - `withdrawals` list (`WithdrawalRequestCrudController`): approve/reject/mark paid, view FX and payout metadata. - `profile-dashboard` (`ProfileDashboardController`): dashboard with aggregate stats, chart.js graphs for wallet flows, reward volumes, recent referrals, withdrawals. - `referrals/settings`: placeholder for future Settings UI (requires integration with Backpack Settings). All admin controllers rely on Backpack's CRUD operations, custom columns (e.g., `user_card`, `price`, `status`), and the translation strings shipped under `resources/lang/en|ru`. --- API Surface ----------- [](#api-surface) ### Authentication (`/api/auth/...`) [](#authentication-apiauth) - `POST /api/auth/register` - `POST /api/auth/login` - `POST /api/auth/logout` (Sanctum token required) - `GET /api/auth/me` (Sanctum token required) - `POST /api/auth/password/change` (Sanctum token required) - `POST /api/auth/password/forgot` - `POST /api/auth/password/reset` - `POST /api/auth/email/verification-notification` (Sanctum token + throttle) - `POST /api/auth/email/resend` (throttle) - `GET /api/auth/verify-email/{id}/{hash}` (signed link) - `GET /api/auth/oauth/{provider}/url` - `GET /api/auth/oauth/{provider}/callback` Responses are JSON-only thanks to `ForceJsonResponse` middleware. The detailed request/response contract and recommended Nuxt/Auth.js integration steps are documented in `AUTH_SYSTEM.md`. ### Profile (`/api/profile/...`) [](#profile-apiprofile) - `GET /api/profile` (guard `auth:profile`) — returns `ProfileFullResource`. - `POST /api/profile/update` (currently guarded by `auth:sanctum`) — updates allowed fields after validation. - `GET /api/profile/referrals` (guard `auth:profile`) — paginated downline list using `ProfileTinyResource`. > Important: the controller expects an authenticated `profile` guard but the update route is wired to `auth:sanctum`. Align guards in your application or adjust the controller as described in `IMPROVEMENTS.md`. ### Wallet & Withdrawals (`/api/wallet/...`) [](#wallet--withdrawals-apiwallet) Routes are wrapped in middleware from `Settings::get('profile.private_middlewares')` (defaults to `['api', 'auth.api:sanctum']`). - `GET /api/wallet/withdrawals` - `POST /api/wallet/withdrawals` - `POST /api/wallet/withdrawals/{id}/cancel` `WithdrawalService` enforces minimum amounts, currency conversion, wallet holds, and ledger bookkeeping. Admin actions (approve/reject/mark paid) are exposed through Backpack routes. --- Services & Facades ---------------------- [](#services--facades) - `Backpack\Profile\app\Services\Profile`: high-level API for triggering referral events, reversing events, resolving currencies, and retrieving the configured user model. - `Backpack\Profile\app\Services\ReferralService`: core engine that records events, resolves uplines, distributes rewards, and performs reversals. - `Backpack\Profile\app\Services\WithdrawalService`: creates withdrawal requests, handles approval/rejection/capture, interacts with wallet balances. - `Backpack\Profile\app\Services\WalletService`: implements `authorize`, `capture`, `void`, and balance retrieval on the wallet ledger. - `Backpack\Profile\app\Services\TriggerRegistry`: registry for referral triggers implementing `Backpack\Profile\app\Contracts\ReferralTrigger`. - `Backpack\Profile\app\Services\ProfileFactory`: builds `Profile` instances and resolves sponsor linkage based on referral codes. - `Profile` facade (`Backpack\Profile\app\Facades\Profile`): shortcut to the `Profile` service. - Middleware: `CaptureReferral`, `ForceJsonResponse`, `CheckIfAuthenticateProfile`. All services are container-bound in `ServiceProvider`. You can override bindings in your application service provider if you need to replace behavior. --- Events, Notifications, and Observers ------------------------------------ [](#events-notifications-and-observers) - Events: `ProfileCreating`, `UserCreating` fire during model creation; default listeners populate names and (optionally) referral codes. - Notifications: placeholders for user onboarding (`UserRegistred`, `ReferralRegistred`, `ReferralBonus`, etc.) and withdrawal completion emails. - Observers: `ProfileObserver` and `TransactionObserver` include legacy logic; review them before enabling in production. --- Extending the Referral Engine ----------------------------- [](#extending-the-referral-engine) 1. Implement `Backpack\Profile\app\Contracts\ReferralTrigger`. 2. Register the trigger alias with `TriggerRegistry::register($alias, $class)`, typically from a service provider or module boot method. 3. Configure trigger settings (fixed/percent payouts, actor award, level distribution) via the Backpack Settings UI or `config/settings.php`. 4. Invoke `Profile::trigger($alias, $externalId, $payload, $actorUserId, $opts)` whenever an event occurs (e.g., order paid). Reversals can be created via `Profile::reverse(...)` or admin UI actions. --- Frontend Integration Notes -------------------------- [](#frontend-integration-notes) - Authentication is token-based: clients must send `Authorization: Bearer {token}` with Sanctum personal access tokens. - API responses are JSON, validation errors use standard Laravel structure (`errors` array). - Email verification is optional and controlled by `profile.users.require_email_verification`. - Social login flows expect the frontend to call `/oauth/{provider}/url`, redirect the browser, and handle `/callback` with optional redirect back to the SPA. - `AUTH_SYSTEM.md` contains step-by-step guidance tailored for Nuxt 3 + Auth.js, including error handling and state transitions. --- Testing & Development ------------------------- [](#testing--development) - The repository currently ships with placeholder tests under `packages/backpack/profile/tests`. Update them to use PHPUnit/Pest against the modern package namespace before relying on automated coverage. - Consider adding feature tests that cover registration, login, referral triggers, withdrawal lifecycle, and admin actions to avoid regressions. --- Known Gaps & Roadmap ------------------------ [](#known-gaps--roadmap) See `IMPROVEMENTS.md` for a curated backlog of technical debt and missing functionality (schema mismatches, outdated controllers, guard inconsistencies, missing tests, etc.). Addressing those items is recommended before turning the package into a reusable release. --- License ------- [](#license) The package is open-sourced software licensed under the [MIT license](LICENSE). ### Health Score 37 — LowBetter than 83% of packages Maintenance78 Regular maintenance activity Popularity14 Limited adoption so far Community8 Small or concentrated contributor base Maturity39 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 218d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/1a9edb05ebf647a1976e4dbf92497c0186607984165f62b97b6498a01e9141ab?d=identicon)[parabellumKoval](/maintainers/parabellumKoval) --- Top Contributors [![parabellumKoval](https://avatars.githubusercontent.com/u/27732309?v=4)](https://github.com/parabellumKoval "parabellumKoval (57 commits)") --- Tags laraveluserprofileaccountbackpackparabellumKoval ### Embed Badge ![Health badge](/badges/parabellumkoval-backpack-profile/health.svg) ``` [![Health](https://phpackages.com/badges/parabellumkoval-backpack-profile/health.svg)](https://phpackages.com/packages/parabellumkoval-backpack-profile) ``` ### Alternatives [bagisto/bagisto Bagisto Laravel E-Commerce 26.2k161.6k7](/packages/bagisto-bagisto)[unopim/unopim UnoPim Laravel PIM 9.4k1.8k](/packages/unopim-unopim)[rupadana/filament-api-service A simple api service for supporting filamentphp 204103.8k7](/packages/rupadana-filament-api-service) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)