Download the PHP package matildevoldsen/quick-actions without Composer

matildevoldsen/quick-actions

Home screen quick actions for NativePHP Mobile apps, with iOS home screen shortcuts and Android launcher shortcuts driven from Laravel.

This package is a Composer package named matildevoldsen/quick-actions. It is built for iOS and Android, requires nativephp/mobile, and is maintained by Matilde Enevoldsen.

What it does

• Registers shortcut items from Laravel
• Syncs those items to iOS and Android through the NativePHP bridge
• Supports route-based shortcuts and signed event-dispatch shortcuts
• Can publish selected items into Spotlight and App Shortcuts so users can launch them from search
• Ships a NativePHP post-compile hook for the generated iOS project
• Includes Boost guidelines and a small JavaScript bridge helper for advanced SPA use

Requirements

• PHP 8.3+
• Laravel
• nativephp/mobile ^3.0
• Android SDK 29+
• iOS 18.0+

Installation

The package service provider is auto-discovered by Laravel. Plugin registration is still required so the native Swift and Kotlin code is compiled into your app.

Permissions and native configuration

This plugin does not request any extra Android permissions and does not add any iOS Info.plist usage descriptions.

Platform configuration shipped in nativephp.json:

• Android min_version: 29
• iOS min_version: 18.0
• Android init function: com.zinxan.plugins.quickactions.bootstrapQuickActions
• iOS init function: QuickActionsPlugin.bootstrap
• iOS post-compile hook: nativephp:quick-actions:post-compile

Usage (PHP)

Register quick actions during application boot so they are present before the response is finalized.

QuickActions is launcher/app-icon first. Shortcut is Spotlight/App Shortcuts first. Either builder can opt into both surfaces.

Where to register items

Typical places to register items:

• a service provider boot() method
• route bootstrapping for app-wide shortcuts
• request-specific UI flows before the response finishes

The package syncs the registry after the application has booted and again at middleware termination, so request-specific shortcuts can still be finalized safely.

API reference

QuickActions::addItem(string $title, ?string $id = null): QuickActionItem

Creates a launcher quick action definition. If no ID is passed, the package derives a stable slug from the title so installed shortcuts keep working across restarts.

Shortcut::create(string $id, string $title): QuickActionItem

Creates a Spotlight/App Shortcuts definition using the explicit ID API.

Separate surfaces, with opt-in crossover

QuickActionItem::icon(?string $symbolName): self

Sets the icon alias used by both platforms.

QuickActionItem::route(string $name, array $parameters = []): self

Resolves a named Laravel route and stores the resulting in-app path.

QuickActionItem::action(string $eventClass, array $payload = []): self

Creates a signed internal dispatch URL that resolves the given event class from the container using the payload as named constructor parameters.

The payload may include redirectTo; if omitted, the internal dispatch route redirects to /.

Surface methods

• QuickActionItem::addToQuickActions(bool $enabled = true): self
• QuickActionItem::addToShortcuts(bool $enabled = true): self
• QuickActionItem::addToSpotlight(): self (alias of addToShortcuts())
• QuickActionItem::spotlight(bool $enabled = true): self (alias of addToShortcuts())

QuickActionItem::addToSpotlight(): self

Opt-in shortcuts surfaces for a launcher quick action.

Only items marked with ->addToSpotlight() or ->addToShortcuts() are indexed into Spotlight/App Shortcuts when they start from QuickActions::addItem().

Fluent aliases

• QuickActionItem::openRoute(string $name, array $parameters = []): self
• QuickActionItem::dispatch(string $eventClass, array $payload = []): self

QuickActionsSync::sync(): void

Low-level sync service exposed through the QuickActionsSync facade alias. Most applications do not need to call this directly because the package syncs automatically.

Usage (JavaScript)

This package also ships a small JavaScript helper in resources/js/index.js for advanced SPA-side bridge calls. The preferred and durable integration is still the PHP API above, because PHP registration is what persists and rehydrates shortcuts across app launches.

Re-export the helper from your frontend build:

Then use it from Vue, React, or another SPA entrypoint:

QuickActionsBridge.sync() calls the same QuickActions.Sync bridge function used by the PHP synchronizer.

Events

This package does not dispatch its own fixed NativePHP event classes.

Instead, ->action() dispatches your event class when the signed quick-action URL is opened. The payload array is passed to Laravel as named constructor parameters.

Example:

Icon mapping

The package accepts a shared icon vocabulary and maps it to SF Symbols on iOS and framework drawables on Android.

Unknown iOS icons are attempted as raw SF Symbols before falling back. Unknown Android icons log a warning and fall back to ic_menu_gallery.

Platform notes

• iOS shows at most four dynamic quick actions.
• iOS only indexes items into Spotlight / App Shortcuts when they belong to the shortcuts surface.
• Spotlight entries use the item title plus app-name keywords so searching for the app can surface opted-in actions more reliably.
• The package persists shortcut payloads in storage/app/zinxan/quick-actions.json.
• Action dispatch payloads are mirrored to storage/app/zinxan/quick-actions-dispatch.json so they still work when cache is empty or split across workers.
• The iOS post-compile hook patches generated AppDelegate.swift and ContentView.swift to support cold-start and scene-based shortcut handling.
• Only one plugin should own iOS scene shortcut wiring in application(_:configurationForConnecting:options:).

If you regenerate native iOS sources and shortcut handling stops working, rerun:

Validation and testing

Recommended release checks:

For this package itself:

Boost guidelines

The package includes Boost guidance in resources/boost/guidelines/core.blade.php so AI tooling can discover the supported PHP and JavaScript patterns.

Local development

When developing this package locally in a NativePHP app, add it as a path repository:

With "symlink": false, refresh the mirrored vendor copy after edits:

License

MIT