Ux Native Cli Laravel Package

Technical Evaluation

Architecture Fit

• Framework coupling is materially deeper in v0.5.0. Prior releases were Symfony-flavored but CLI-centric; v0.5.0 introduces three Symfony-native runtime coupling points that Laravel has no direct equivalent for:
  1. Asset Mapper (symfony/asset-mapper) now serves the bridge Stimulus controllers (@akyos/ux-native-cli) instead of copying them into the project.
  2. UX Live Component traits (NotificationTrait, ScanQRTrait) are Symfony UX Live Component constructs.
  3. Top bar is now driven by Symfony path-configuration rules (top_bar), extending the server-side contract.
• Bridge surface expanded from 1 to 3. native:update:config can inject --notification, --barcode-scanner, and --admob. For Laravel this means the adapter must plan for three bridge families, not one:
  • Barcode scanner: camera permissions, native plugin lifecycle, scan-event handoff to the backend.
  • AdMob: monetization SDKs, ad unit IDs, consent (GDPR/ATT), and per-environment ad config — a new configuration and compliance surface with no prior coverage.
  • Notification: unchanged from v0.3.0 (token bridge + akyos/native-push).
• Config reinjection between markers is a new architectural pattern. native:update:config rewrites native.yaml-derived values (URL, name, icon, top bar) into generated native source between markers, and native:build runs this as a pre-build step. Implications:
  • The build is no longer read-only/hermetic — it mutates checked-in source. Reproducibility and CI diff-noise must be managed.
  • Markers define a machine-owned region inside project files. Manual edits inside markers are silently clobbered; manual edits outside are preserved. This is a workable contract but must be documented and enforced in review.
  • Symfony config semantics (native.yaml) are still the source of truth; the native.yaml→config/native.php conversion burden from v0.3.0 is unchanged and now feeds a patching step rather than only scaffolding.
• Positive: idempotent bridge upgrades. native:update:config adding missing bridges means existing native projects can be upgraded incrementally without --force re-init. This is a real reduction in migration risk versus v0.3.0.
• Icon generation from native.icon for both platforms is framework-agnostic (image resampling), low-risk; adds an image-processing dependency (GD/Imagick) and an asset pipeline input.
• akyos/native-push remains the recommended companion and remains a first-class architectural decision; framework alignment is still unverified.
• Coverage gap: this review compares v0.5.0 against a v0.3.0 baseline. v0.4.0 was never assessed. Before committing, diff v0.4.0 for config-key or contract changes that v0.5.0 builds on.

Integration Feasibility

• Still feasible as CLI: native:init, native:build, native:qr-install, device install, and now native:update:config are shell-out and file-rewrite operations that port cleanly to Artisan.
• Newly infeasible without adaptation:
  • Asset Mapper: no Laravel equivalent. Options: (a) publish controllers via php artisan vendor:publish into resources/js and register through Vite; (b) ship a shim resolving @akyos/ux-native-cli specifiers to Vite aliases; (c) serve controllers as static assets. Option (a) is the pragmatic default and restores a customization escape hatch the package just removed.
  • Live Component traits: no Laravel equivalent. NotificationTrait/ScanQRTrait must be reimplemented as Livewire traits (or plain controller/service helpers) exposing the same behavioral contract. This is net-new Laravel code, not a port.
  • Top bar path config: served JSON can be produced by a Laravel controller; the contract must be mirrored and versioned alongside the existing tabs/modals config.
• Feasible but needs design:
  • native:update:config in Laravel: implement as an Artisan command reproducing marker semantics exactly, reading from config/native.php. Must be idempotent, must fail loudly if markers are missing, must be safe to run twice.
  • Build-time mutation: decide whether native:build performs the reinjection (parity with upstream) or whether CI runs native:update:config explicitly and the build verifies cleanliness. The latter is better for reproducible builds.
  • Barcode scanner backend: deep-link/event routing for scan results into Laravel; permission-denied and unsupported-device paths.
  • AdMob backend: ad unit ID distribution per environment (test vs. production IDs), consent state, and a kill-switch — all new config keys.
• Challenges carried forward: YAML→PHP config conversion, DI/container wiring, event dispatcher replacement, akyos/native-push alignment, Apple signing and push credentials.

Technical Risk

Key Questions

1. Framework Alignment
   • Does the Laravel adapter shim Asset Mapper or publish controllers to Vite? Who owns the published copy on upgrade?
   • Is there an acceptable Laravel contract for NotificationTrait/ScanQRTrait, or is this the point where a fork becomes the cheaper path?
   • Does akyos/native-push support Laravel, or must it be wrapped/forked?
2. Config & Marker Contract
   • Should config/native.php remain the source of truth, with native:update:config rendering into markers — or should markers be generated from scratch each build?
   • What happens when markers are missing, duplicated, or the surrounding file has been refactored?
   • Is native:update:config safe to run in CI and idempotent across repeated runs?
3. Build & Signing
   • Is native:build allowed to mutate the workspace, or do we gate it behind --no-update-config and run the update step explicitly in CI?
   • How do we surface gradlew/xcodebuild failures to Laravel's exception/log channels with correlation IDs?
   • Where do Apple Developer credentials live for -allowProvisioningUpdates in CI? What is the rotation and revocation runbook?
4. New Bridges
   • Barcode: what is the scan-result payload schema, and how does it route into Laravel? Permission-denied fallback?
   • AdMob: test vs. production ad unit IDs per environment, consent/ATT handling, kill-switch, and whether ads are permitted in debug builds?
   • Notification: unchanged from v0.3.0 — auth binding of token to user, multi-device, APNs/FCM failure surfacing.
5. Top Bar & Path Configuration
   • Is top_bar served dynamically from Laravel or baked in at build time? What is the versioning contract with tabs/modals?
   • How do installed apps handle a config change that alters the top bar after release?
6. Long-Term Maintenance
   • Given v0.5.0's deeper Symfony coupling, is a standalone Laravel package (akyos/laravel-native-cli) still sufficient, or is a maintained fork the honest answer?
   • Who tracks upstream releases — including the unreviewed v0.4.0 — and re-runs this assessment?

Integration Approach

Stack Fit

• Laravel Compatibility Matrix:

  Component	Laravel 10+ Support	Workaround Needed
  Symfony Console	✅ (symfony/console)	Manual Artisan registration.
  Symfony Config	✅ (symfony/config)	Convert YAML to config/native.php.
  Symfony Process	✅ (symfony/process)	None.
  Symfony FrameworkBundle	❌	Replace with Illuminate\Foundation\Application.
  Symfony UX Native	❌	Custom bridge (akyos/laravel-native).
  Symfony Asset Mapper (new)	❌	Publish controllers to resources/js, register via Vite.
  UX Live Component traits (new)	❌	Reimplement as Livewire traits / services.
  akyos/native-push	⚠️ Unverified	Verify; wrap Firebase Admin SDK / APNs HTTP/2 if needed.
  Firebase Admin SDK	✅ (kreait/firebase-php)	Fallback if native-push is Symfony-only.
  APNs HTTP/2	✅ (edamov/pushok or similar)	iOS-direct delivery fallback.
  Image generation (native.icon)	✅	GD or Imagick; pin in CI image.

• Recommended Stack:
  • PHP 8.2+, Laravel 10+.
  • Custom package akyos/laravel-native-cli wrapping the Symfony bundle, including: notification-token route, path-config endpoint (including top_bar), marker-aware native:update:config, and a vendor:publish asset path for the Stimulus controllers.
  • Push delivery via akyos/native-push if Laravel-compatible; otherwise kreait/firebase-php + APNs library.
  • Barcode: native plugin + Laravel endpoint for scan payloads (define schema before building).
  • AdMob: env-scoped ad unit IDs, consent service, kill-switch flag in config/native.php.
  • Secrets: App Store Connect API key, APNs .p8, Firebase service account in CI secret manager.

Migration Path

1. Phase 0: Baseline Re-review (3–5 days, new)
   • Diff v0.4.0 release notes and config keys against the v0.3.0 baseline.
   • Confirm v0.5.0 marker format and Asset Mapper asset paths on a sample Symfony project.
2. Phase 1: Proof of Concept (2 weeks)
   • Install akyos/ux-native-cli in a Laravel 10 project; register via custom service provider.
   • Run native:init with path overrides (storage/native/android).
   • Validate native:update:config marker semantics on a scratch project.
   • Build Android (simpler than iOS).
3. Phase 2: Config Abstraction (1–2 weeks)
   • native.yaml → config/native.php with env vars, including ios_development_team, notification, barcode, AdMob, icon, and top_bar settings.
   • Define the marker contract and a lint check for missing/duplicated markers.
4. Phase 3: CLI Integration (1 week)
   • Register commands in Artisan; implement native:update:config with idempotency and dry-run mode.
   • Handle interactive prompts via Laravel's Prompt helper.
5. Phase 4: Hotwire Native Bridge + Assets (3–4 weeks, expanded)
   • Replicate symfony/ux-native detection and JSON config serving (tabs, modals, top_bar).
   • Implement the notification-token endpoint (route, auth, storage, pruning).
   • Publish Stimulus controllers via vendor:publish; wire alias in vite.config.js.
   • Reimplement NotificationTrait/ScanQRTrait as Livewire traits (or service methods).
6. Phase 5: iOS Support & Signing (1–2 weeks)
   • xcodebuild/devicectl on macOS CI; ios_development_team + App Store Connect API key for -allowProvisioningUpdates.
   • Validate icon generation output for iOS asset catalogs.
7. Phase 6: Push (1–2 weeks)
   • Integrate akyos/native-push or wrapper; configure Firebase + APNs .p8.
   • End-to-end testing across foreground/background/closed-app deep links.
8. Phase 7: Optional Bridges (1–2 weeks each, new)
   • Barcode scanner: permissions, scan payload schema, backend routing.
   • AdMob: ad unit IDs per env, consent/ATT, kill-switch, compliance review.

Compatibility

• Android: High — Gradle/Java tooling is cross-platform; FCM standard.
• iOS: Low–medium — macOS-only; requires xcodebuild/devicectl, Apple Developer credentials for real-device signing, and icon asset catalog regeneration.
• Push: FCM covers both via Firebase; APNs direct is the iOS-only alternative.
• Asset pipeline (new): Symfony Asset Mapper → no Laravel equivalent. Vite-based publishing is the compatibility route; expect import-specifier and versioning differences to be the main friction.
• UI traits (new): Symfony UX Live Components → Livewire is analogous but not compatible; traits must be reauthored.
• Offline mode: Client-side caching; backend must version path config, including top_bar. Debug builds now disable WebView cache — a DX win, no backend impact.
• Laravel-specific: Artisan replaces Console; config()/env replaces Symfony config; Laravel events/queues replace Symfony lifecycle hooks; vendor:publish + Vite replaces Asset Mapper.

Sequencing

1. Prerequisites: symfony/console, symfony/process, endroid/qr-code, GD/Imagick; ANDROID_HOME/JAVA_HOME/ANDROID_SDK_ROOT in .env; Apple Developer account, ios_development_team, APNs .p8, Firebase project.
2. Baseline: complete Phase 0 v0.4.0 diff before writing adapter code.
3. Core: service provider registration; publish native.php; implement marker-aware native:update:config with --dry-run and idempotency tests.
4. CI hardening (new): run native:update:config explicitly, then native:build --no-update-config, then assert a clean git diff.
5. Bridge: path-config endpoint (tabs/modals/top_bar), notification-token route, published Stimulus controllers, Livewire trait equivalents.
6. Push: integrate companion package; wire secrets; test all app states.
7. Optional bridges: barcode, then AdMob (compliance-first).
8. Deployment: native:qr-install locally; CI builds with --platform=all --no-install, -allowProvisioningUpdates on macOS runners.

Operational Impact

Maintenance

• Dependencies:
  • Two upstream packages to track: akyos/ux-native-cli and akyos/native-push — upgrade them together.
  • New asset dependency: the published Stimulus controllers are now ours — upstream changes must be manually reconciled on each bump.
  • New runtime deps: image processing (GD/Imagick) for icon generation; AdMob/barcode SDKs pinned per platform.
  • Native tooling versions (gradlew, xcodebuild, adb, xcrun) pinned in CI images.
• Marker contract ownership (new): the marker format is an external contract; if upstream changes it, our patching step breaks silently or corrupts files. Add a contract test against a fixture project.
• Credential lifecycle: APNs .p8, Firebase service accounts, Apple provisioning profiles/certs — expiry, rotation, revocation. -allowProvisioningUpdates means build hosts hold Apple account authority.
• Config drift: v0.5.0 adds icon, top_bar, barcode, and AdMob keys to the YAML→PHP conversion backlog; v0.4.0 keys may also be missing and must be diffed.
• Upgrade path: monitor upstream for further Symfony-native coupling; given v0.5.0's Asset Mapper and Live Component dependencies, a maintained Laravel fork is now a credible long-term option.

Support

• Debugging:
  • Android: log gradlew output with correlation IDs; include the post-native:update:config diff hash.
  • iOS: provisioning/profile errors are the top real-device failure; runbook for team-ID mismatch, expired profile, -allowProvisioningUpdates failures, and icon-catalog mismatch.
  • Push: surface BadDeviceToken, Unregistered, expired key in structured logs; distinguish config vs. device-token failures.
  • Config reinjection: retain a copy of the last-rendered native config; when reports mention stale URL/name/top bar, compare rendered vs. expected.
  • Asset serving (new): Vite manifest and controller-version mismatch will look like "bridge does nothing" in the app — add a version banner in debug.
  • New bridges: separate playbooks for camera-permission failures (barcode) and ad-fill/consent failures (AdMob).
• Escalation matrix: build/toolchain, asset pipeline, push delivery, Apple account, and (new) ads/consent compliance have different owners.

Scaling

• Push volume: FCM/APNs quotas; batch sends, queue with retry/backoff, respect APNs HTTP/2 concurrency.
• Token storage: one row per device per user; prune on Unregistered/BadDeviceToken; index by user and token.
• Build concurrency: macOS runners are scarce/expensive; queue builds and cache Gradle/SPM. Reinjection-on-build increases per-build work — cache the rendered config keyed by config hash.
• Path config / offline: serve from cache/CDN; invalidate on release; version top_bar alongside tabs/modals.
• Asset delivery (new): published controllers now ship through the app's asset bundle — bundle size and cache-busting become app-release concerns.

Failure Modes

• Marker mismatch during native:update:config (new): missing/duplicated markers → either silent skip (stale app config) or partial file corruption. Fail closed and alert.
• Build mutates source (new): native:build rewriting files causes CI diff noise, spurious merge conflicts, or committed generated changes.
• Asset Mapper→Vite divergence (new): controllers not published/aliased → bridges silently no-op in the app.
• Live Component trait reimplementation drift (new): Laravel trait diverges from upstream behavior → notification/scan flows break after an upstream bump.
• Silent push failures: expired/revoked APNs .p8 or Firebase account — no user-facing error; requires health checks and delivery metrics.
• Signing failures: profile drift, expired cert, wrong ios_development_team — blocks real-device builds only.
• Notification bridge unreachable: token never registered → no pushes for that device; alert on registration failure rate.
• AdMob consent/ID misconfiguration (new): production ads served with test IDs (or vice versa), or consent not captured — revenue and compliance impact.
• Barcode permission denial (new): scanner unusable with no fallback → feature dead-end.
• Path config version skew: backend changes top_bar/tabs; installed app caches old config → broken navigation and deep links.
• Companion package breaking change: akyos/native-push upgrade incompatible with the wrapper — pin and stage upgrades.
• Cross-platform CI drift: Android passes, iOS fails after a macOS runner image change.

Ramp-up

• Learning curve widens again: v0.5.0 adds an asset pipeline (Vite/Asset Mapper parity), Livewire trait authorship, and — if the optional bridges are enabled — native camera and ad SDK work. AdMob additionally pulls in consent/compliance review.
• Ownership: explicit owners for (a) Apple credentials/signing, (b) Firebase/APNs credentials, (c) push delivery and token storage, (d) asset/bridge publishing, (e) ads and consent compliance if AdMob is enabled.
• Documentation: marker contract reference, credential rotation runbook, push debugging playbook, path-config schema (tabs/modals/top_bar), asset-publish upgrade procedure, and a per-bridge enablement checklist.
• Phased enablement: ship Android + push first; then iOS signing and real-device install; then Hotwire UI assets and top_bar; validate offline/path config; add barcode and AdMob only after the core pipeline is stable.
• Decision checkpoint: before committing, resolve whether the Laravel path is a wrapper package or a maintained fork. v0.5.0's Asset Mapper and Live Component dependencies make the wrapper path meaningfully more expensive than it was at v0.3.0.