Jiguang Push Bundle Laravel Package

Getting Started

tourze/jiguang-push-bundle 0.0.1 is an initial tagged release. The release notes only link to the commit history, so there is no documented feature list, migration guide, or explicit compatibility statement. Treat this as an early/experimental integration and pin the exact version until you have validated it in your app.

Start by checking:

1. composer.json for PHP/Laravel/Symfony version constraints and dependencies.
2. README.md for JPush credential configuration and supported send APIs.
3. src/ for the main client/service class, configuration object, and any framework integration.
4. config/, DependencyInjection/, or service-provider classes to determine whether this is Laravel-native or a Symfony-style bundle.
5. Tests/examples for the expected payload shape and error handling.

First use case: send one test push to a known registration ID or alias using JPush AppKey/MasterSecret from environment variables. Validate credentials, platform payload, and response handling before wiring it into application flows.

Note: the -bundle suffix often indicates Symfony bundle conventions. Verify whether Laravel auto-discovery/service providers are supported. If not, use it as a plain PHP dependency behind your own Laravel service/provider rather than assuming drop-in Laravel integration.

Implementation Patterns

Wrap the package client behind an application-level interface so push provider details do not leak through controllers or domain code:

interface PushNotifier
{
    public function sendToUser(string $userId, PushMessage $message): PushResult;
}

Common day-to-day patterns:

• Configure credentials through environment variables and Laravel config. Never hardcode the JPush MasterSecret.
• Send pushes from queued jobs, not synchronously in HTTP requests.
• Maintain your own device/registration-ID table keyed by user, platform, and app version. Resolve application users to JPush aliases/tags/registration IDs in one place.
• Centralize payload construction for Android, iOS, and notification vs. silent/data messages. Keep platform-specific options out of business logic.
• Use aliases or tags for audience targeting where possible, but keep a fallback path for direct registration IDs.
• Record push results, including JPush message IDs and error responses, for support and debugging.
• Add idempotency around retries to avoid duplicate notifications when a request times out after JPush accepted it.
• In tests, bind a fake PushNotifier or fake HTTP client. Do not call JPush in the default test suite.
• If the package is Symfony-oriented, create a small Laravel service provider that reads Laravel config and constructs the package client. Keep that adapter isolated so replacing the package later is cheap.
• Pin 0.0.1 exactly in composer.json and review the commit diff before upgrading.

A practical integration flow:

1. User action creates a domain event or queued job.
2. Job resolves target devices/aliases.
3. Job builds a provider-neutral message.
4. Adapter converts it to the package/JPush payload.
5. Adapter sends, logs result, and handles retryable vs. permanent failures.
6. Invalid registration IDs are marked for cleanup.

Gotchas and Tips

• 0.0.1 is an initial release with minimal release notes. Expect API instability and verify behavior from source/tests rather than assuming semver guarantees.
• The package name suggests a Symfony bundle. Confirm Laravel compatibility before relying on package auto-discovery, facades, or Laravel-specific config publishing.
• JPush uses AppKey/MasterSecret credentials. Keep the MasterSecret server-side only; never expose it to mobile clients or frontend code.
• Platform payloads differ significantly between Android and iOS. Test both notification and data-message behavior on real devices.
• Alias/tag targeting has constraints and eventual consistency. Validate audience resolution and avoid assuming every user has exactly one active device.
• Push APIs can return HTTP success with per-target failures. Parse the response body, not just the status code.
• Log request payloads with secrets removed. Log JPush message IDs and raw error codes for support.
• Retries can cause duplicate notifications. Use a job idempotency key or deduplication strategy.
• Clean up invalid registration IDs using JPush feedback/error responses; stale device tokens are a common source of silent delivery failures.
• In Laravel, run php artisan config:clear after changing push-related environment values, especially in cached-config deployments.
• Add a health-check or smoke command that sends a push only to a test device in non-production environments.
• Useful extension points: your own PushNotifier binding, custom payload builder, custom HTTP client, result/event logging, and a fake implementation for tests.