Platform Ui Laravel Package

Getting Started

1. Prerequisites. platform-ui is a Laravel package that renders a frontend on top of the Enjin Platform backend. It expects enjin/platform-core (and its GraphQL API) to be installed, migrated, and reachable. Without a working core + database + blockchain credentials, the UI boots but sits on an empty/broken shell.
2. Install.

   composer require enjin/platform-ui
   php artisan vendor:publish --tag=platform-ui-config
   php artisan vendor:publish --tag=platform-ui-assets   # views, JS/CSS bundles
   php artisan storage:link
   

3. Register routes & auth. The service provider auto-registers the UI routes (typically /platform or similar). Guard them behind your existing auth middleware — most installs pair this with Sanctum sessions or a simple login. Make sure the authenticated user maps to a Player/Wallet in core.
4. First use case. After logging in, open the UI, connect a managed wallet, then walk through the Create Collection → Mint Token → View on-chain flow. That single path exercises auth, GraphQL queries/mutations, transaction signing, and queue workers — if that works end-to-end, the integration is healthy.

Start by reading config/platform-ui.php and the package's routes/ and src/Http/Controllers before touching anything custom. That's where 90% of integration decisions live.

Implementation Patterns

• Use it as an admin/backoffice panel. The most common pattern is not to build a customer-facing app but to drop this behind auth + can:admin and let ops staff mint, freeze, and transfer tokens without writing GraphQL by hand.
• Compose around it, don't fork it. Publish views/blade layouts and override the shell (nav, branding, footer) rather than editing vendor files. Keep custom pages as your own routes and link them into the UI's menu via config.
• Talk GraphQL directly for automation. When you need scripted behavior (bulk mint, batch transfers), skip the UI and hit the platform-core GraphQL endpoint with a Sanctum token. The UI is a reference implementation of the same queries — copy payloads from the browser network tab.
• Custom middleware for tenancy. If you're hosting multiple projects, wrap the UI routes with a middleware that scopes wallet/collection queries by auth()->user()->project_id, and enforce the same scoping in your own GraphQL proxies.
• Feature-flag via config. Use the published config to toggle sections (marketplace, fuel tanks, etc.) rather than commenting out views — this survives updates.
• Testing. Feature-test the UI routes with actingAs($admin)->get('/platform') to assert permissions render, and use Dusk/Pest browser tests for the mint flow against a local platform-core in Docker.

Gotchas and Tips

• Asset pipeline drift. If your app runs Vite and the package ships pre-built or Mix-based assets, expect console 404s. Check public/vendor/platform-ui after publish and confirm @vite/mix() calls match your build. Re-publish assets after upgrading.
• Route collisions. The package claims generic paths. Register your own routes before the package provider, or override paths in config, otherwise Route [platform] not defined or 404s from shadowed routes bite you.
• Config caching silently ignores publishes. After vendor:publish or editing config/platform-ui.php, run php artisan config:clear in local and remember config:cache in prod — several "it works locally" bugs are just stale config.
• Blockchain operations are async. Mint/transfer mutations enqueue jobs that talk to the chain. Symptom: UI shows success, nothing appears. Fix: queue:work running, correct QUEUE_CONNECTION, and platform-core's transaction broadcasting configured. Tail storage/logs and the failed_jobs table first.
• Auth mismatch between UI and GraphQL. Session auth for the UI does not automatically authorize the underlying API calls. Ensure the same Sanctum guard/token is forwarded, or the UI's AJAX gets 401s that look like UI bugs.
• Wallet sync lag. Fresh wallets can briefly show empty balances because indexers haven't caught up. Don't treat it as a bug — poll or add a manual refresh; document the delay for support.
• Version pinning matters. platform-ui and platform-core versions track each other closely. Pin both in composer.json and upgrade together; a half-upgraded pair produces cryptic GraphQL schema errors.
• Extension point: custom Blade components under resources/views/vendor/platform-ui/… are the safest place to inject project-specific UI without forking. Keep a changelog of files you override so upgrades stay auditable.