Coupon H5 Link Bundle Laravel Package

Getting Started

This is an initial 0.0.1 tag with no README or changelog content beyond a commit link, so treat the first hour as reconnaissance rather than integration.

composer require tourze/coupon-h5-link-bundle:0.0.1

Pin the exact version — see Gotchas.

Look in this order:

1. vendor/tourze/coupon-h5-link-bundle/composer.json — the require block tells you the PHP floor and which tourze/* base packages get pulled in; extra tells you whether it ships a Laravel provider or a Symfony bundle class.
2. vendor/tourze/coupon-h5-link-bundle/src/ — find the class that actually builds a URL. Tourze packages follow a naming convention (*Bundle.php for the bundle entry point, plus a service class such as a link generator/resolver). The constructor signature is your real API documentation.
3. tests/ — with no docs, the test suite is the only executable spec for expected input/output shape.
4. README.md — if present, usually a stub in early Tourze releases.

The first use case is narrow and obvious: given a coupon (ID/code/tenant), produce the H5 landing URL you embed in an SMS, push notification, QR code, or WeChat share card. Wire it into one endpoint or job, verify the output by hand, then spread it.

If the package is a Symfony bundle (likely, given the publisher) and exposes no Laravel service provider, register it manually:

// app/Providers/AppServiceProvider.php
$this->app->singleton(LinkGenerator::class, function ($app) {
    return new LinkGenerator(config('services.coupon_h5.base_url'));
});

Implementation Patterns

Wrapper service, not scattered calls. The vendor API surface will move. Put one thin class between your app and the package:

final class CouponLink
{
    public function __construct(private LinkGenerator $generator) {}

    public function for(Coupon $coupon): string
    {
        return $this->generator->generate($coupon->code);
    }
}

Everything downstream — controllers, jobs, Blade — depends on CouponLink, so a 0.0.x breaking change touches one file.

Generate at the edge, not in the model. Links belong to the delivery channel (SMS vs. QR vs. in-app), not to the Coupon entity. Keep them in the notification/job that sends them so you can vary the base URL per environment or per channel later.

Cache per coupon, keyed by inputs. H5 links are cheap but not free, and campaign sends are high-volume:

return Cache::remember("coupon-link:{$coupon->id}", now()->addHour(), fn () => $this->for($coupon));

Invalidate on coupon mutation if the link encodes mutable state.

Config over constants. Put the H5 base domain in config/services.php (or publish the package config with php artisan vendor:publish) so staging and production differ without code changes. Never hardcode a domain inside a queued job — a bad deploy then poisons the queue backlog.

Test against a fake, not the network. Bind a stub implementation in your test suite:

$this->app->instance(CouponLink::class, new class {
    public function for(Coupon $c): string { return "https://example.test/c/{$c->code}"; }
});

This keeps your campaign tests fast and immune to whatever the package does internally.

Integration path for sending: Coupon::created → queued SendCouponNotification job → builds link via CouponLink → mail/SMS/push driver → store the sent URL on the coupon or a coupon_deliveries table for support and analytics.

Gotchas and Tips

• 0.0.1 has no compatibility promise. Composer's ^0.0.1 resolves only >=0.0.1 <0.0.2, which is fine, but be explicit: "tourze/coupon-h5-link-bundle": "0.0.1". Read every subsequent 0.0.x diff before bumping; assume breaking unless proven otherwise.
• Symfony-vs-Laravel bootstrapping is the top risk. Tourze publishes mostly Symfony bundles. A *Bundle.php with DependencyInjection/ and YAML/XML service definitions will not be auto-wired by Laravel's container — the Bundle class is a no-op there, and services declared in YAML simply won't exist. You'll be instantiating classes by hand or writing your own provider. Budget for this; it's the difference between a 20-minute and a 2-hour install.
• No documentation means read the tests. If tests/ is also missing or empty, treat the package as source-available rather than supported: pin it, wrap it, and be prepared to vendor a fork.
• Constructor injection is your only contract. Check the constructor for scalar args (base URL, secret, TTL) versus injected services — scalars mean you must supply config yourself; injected services mean you must satisfy those too.
• Watch transitive tourze/* dependencies. These bundles frequently share a small framework of base packages. composer why tourze/coupon-h5-link-bundle and a scan of composer.lock will show you what actually landed. Unexpected transitive upgrades are a common source of "it worked yesterday."
• Verify the PHP and extension floor first. If composer.json requires something above your CI matrix, resolve it before writing any code — otherwise you'll discover it in the pipeline.
• Debugging: php artisan tinker and app(LinkGenerator::class) is the fastest smoke test. If the class won't resolve, the exception tells you whether it's a missing binding (your provider) or a missing dependency (theirs).
• Extension points are unknown at 0.0.1. Don't subclass the vendor's generator to add behavior. Compose instead — wrap it in your own class and keep the vendor type out of your public signatures. That's what keeps the upgrade path survivable when the 0.1.0 API lands.