Mobilekitv4 Laravel Package

Getting Started

This is a starter kit, not an installable package. You don't composer require it into an existing app — you either scaffold from it or fork it and make it your own. Confirm which in the README before you plan anything else, because the answer determines your whole upgrade story.

Minimal path:

git clone https://github.com/jeffersongoncalves/mobilekitv4 my-app
cd my-app && composer install && npm install
cp .env.example .env && php artisan key:generate
# configure DB in .env
php artisan migrate --seed
php artisan make:filament-user      # create your admin login
php artisan serve                   # browse to /admin

Then get the native shell running:

php artisan list | grep native      # confirm the exact NativePHP command names in this version
php artisan native:install
php artisan native:run

Where to look first, in this order:

1. composer.json — pin down the Laravel/Filament/NativePHP versions you actually got, plus the required PHP version.
2. config/nativephp.php (or equivalent) — app ID, name, permissions, and which native plugins are enabled.
3. The Filament panel provider in app/Providers/Filament/ — this tells you whether there's one panel or several.
4. routes/ and resources/views/ — find the mobile-facing surface. In kits like this it's usually a Blade/Livewire screen set that the NativePHP webview loads, separate from the admin panel.

First use case: treat the Filament panel as your back office and the webview as the client. Pick something small and end-to-end — a Note model with a Filament resource for admin CRUD and one mobile screen listing and creating notes. That exercises the whole seam (migrations, model, panel, mobile route, native build) in an afternoon and surfaces every rough edge in the kit at once.

Implementation Patterns

Two surfaces, one domain layer. The productive shape is: models, policies, and actions live in app/ and are shared; Filament resources in app/Filament/ are admin-only; mobile screens are thin. Resist putting business logic in Filament resources — you'll need it on the mobile side and you'll end up duplicating it.

Filament for CRUD, Livewire for the app. Use Filament resources for anything an administrator does (user management, content moderation, settings). Use plain Livewire components plus Tailwind for the mobile screens, matching whatever the kit already wires up. Don't try to reuse Filament resources as the mobile UI — the styling and navigation assumptions don't survive the transition.

Native features via the bridge, wrapped in your own service. Camera, geolocation, filesystem, and notifications are exposed either as PHP facades or through a JS bridge depending on the NativePHP version. Wrap whatever the kit gives you behind a small interface in app/Services/ so screens depend on your API, not on Native\... calls scattered through Blade files. It also gives you a fake for browser-based testing.

Develop in the browser, verify on device. Most screens iterate faster at php artisan serve than through a native rebuild. Keep the mobile routes working in a normal browser, and reserve native:run for validating permissions, safe-area layout, and anything touching hardware.

Seed idempotently. The kit almost certainly seeds demo data. On a mobile build, migrations run against an on-device SQLite database at boot. Use updateOrCreate in seeders and avoid destructive migrations once you've shipped — there is no "drop and re-migrate" on a user's phone.

Version control your native projects. Check in ios/ and android/ (or wherever the native shells land). You will need to edit Info.plist and AndroidManifest.xml for permissions, deep links, and display name, and you want those changes reviewable and revertable.

CI split. Run Pest/PHPUnit and static analysis on every push. Run native:build on a matrix that includes macOS (iOS requires Xcode) and Linux/macOS (Android needs the SDK and JDK) — or just accept that release builds are a manual, documented ritual.

Gotchas and Tips

Forking means no upstream merges. With 14 stars and a last release in the future-dated 2026-09-22 slot, treat this as a snapshot of opinionated scaffolding. git remote add upstream and cherry-pick selectively, or accept divergence. There will be no security-patch cadence handed to you.

Bleeding-edge version matrix. Laravel 13.x, Filament 4.x, and current NativePHP are all recent major versions. Pin exact versions in composer.lock, commit it, and read upgrade guides before bumping. Filament 4 in particular rearranged resource/panel structure versus 3.x, so third-party plugins and old tutorials won't line up.

Build toolchain, not PHP, is the blocker. iOS builds need macOS + Xcode + a signing identity. Android needs the SDK, a JDK, and Gradle. Budget a day for a clean machine before you budget any for features.

Assets and APP_URL. The webview loads from a bundled server, so Vite's dev server must be reachable from the device. Use npm run dev -- --host and set APP_URL to your machine's LAN IP, not localhost. Run php artisan filament:assets after theme changes; unstyled admin panels are almost always this.

Secrets ship in the binary. Anything in .env at build time is inside the app. Never put API keys, mail credentials, or DB passwords there — proxy through your own backend, or accept that the key is public. This is the most commonly skipped step and the most expensive to fix.

No reliable queue or scheduler on device. Workers and cron don't survive app suspension. Use the sync driver on mobile, do work in request handlers, and push anything long-running to a server endpoint.

Debugging the webview. native:run surfaces PHP logs, but client-side errors need the webview inspector (Safari Web Inspector for iOS, chrome://inspect for Android). Add a global JS error handler that POSTs to a debug route in local builds — it saves hours on device-only bugs.

Permissions fail silently when misconfigured. Camera or location returning nothing usually means the native manifest entry is missing, not that your code is wrong. Check Info.plist / AndroidManifest.xml first.

Extension points that actually hold up: Filament plugins for admin (they're additive and well-isolated), Laravel service providers for shared wiring, and NativePHP's event system for hardware callbacks. Avoid editing files the kit's generators regenerate; your changes will vanish on the next native:install.