Iss Satellite Laravel Package

Getting Started

bildvitta/iss-satellite still ships a generic description, but v0.2.4 gives you something the previous release didn't: a traceable changelog and a real upstream repository. The release notes point at github.com/appnave/nave-satellite-iss (PR #18) — note that the GitHub org (appnave) and the Composer vendor (bildvitta) don't match. Resolve that discrepancy before you trust anything else.

1. Confirm identity and compatibility

composer show bildvitta/iss-satellite --all
composer show bildvitta/iss-satellite --all | grep -E 'source|homepage|versions'

You want: the source URL, the require block (PHP + illuminate/* constraints), and confirmation that v0.2.4 is a real tag rather than a branch alias:

git ls-remote --tags https://github.com/appnave/nave-satellite-iss

If the source URL points somewhere other than appnave/nave-satellite-iss, you're looking at a fork or a rename — treat it as a different package and audit accordingly.

2. Read the diff before reading the source

The v0.2.3 → v0.2.4 delta is a single PR. That's cheap and high-signal:

git clone https://github.com/appnave/nave-satellite-iss && cd nave-satellite-iss
git log --oneline v0.2.3..v0.2.4
git diff v0.2.3..v0.2.4

One PR touching "Mega queries for Distrato/AVRA flow" tells you the package is business-logic-bearing, not a thin generic SDK. That reframes the whole assessment: upgrades can change domain behaviour, not just transport.

3. Install and inspect

composer require bildvitta/iss-satellite:0.2.4
php artisan vendor:publish   # run interactively; don't guess the provider FQCN
grep -R "extends ServiceProvider" vendor/bildvitta/iss-satellite/src

Where to look, in order:

4. First use case: smoke-test one mega query in isolation

Don't wire the package into a product flow yet. Resolve the new Distrato/AVRA query entry point and exercise it once, under Http::fake() if it makes outbound calls:

Http::fake(['*' => Http::response(['ok' => true], 200)]);

$service = app(\Bildvitta\IssSatellite\...::class);
dump($service->/* mega query method from the v0.2.4 diff */);

A green test around one mega query before it touches production is still the highest-value first step — but now you also have a concrete scope: if you're not running a Distrato/AVRA flow, you may not need the new surface at all, and v0.2.3 may be sufficient.

Implementation Patterns

Wrap it behind your own boundary

The v0.2.4 note strengthens the original case rather than weakening it: the package now encodes specific business flows (Distrato/AVRA), with one external contributor and no public dependents. Isolate it:

// app/Contracts/SatelliteGateway.php
interface SatelliteGateway
{
    public function send(array $payload): Result;
}

// app/Services/IssSatelliteGateway.php
final class IssSatelliteGateway implements SatelliteGateway
{
    public function __construct(private readonly \Bildvitta\IssSatellite\Client $client) {}

    public function send(array $payload): Result
    {
        // translate your domain payload -> package payload here
    }
}

Bind it in a DomainServiceProvider. New package flows become new methods on your interface, not new call sites into vendor/.

Treat package output as input, not truth

Because the package now owns Distrato/AVRA query logic, the boundary should also own interpretation. Map its responses into your own DTOs immediately:

final class IssSatelliteGateway implements SatelliteGateway
{
    public function distratoStatus(string $contractId): DistratoStatus
    {
        $raw = $this->client->/* mega query */($contractId);

        return new DistratoStatus(          // your enum, your rules
            cancelled: (bool) $raw['distrato'] ?? false,
            raw: $raw,
        );
    }
}

If a future release changes what "Distrato" means, your domain doesn't silently change with it.

Config-driven setup, never hardcoded

// config/iss-satellite.php (published, then edited)
return [
    'base_url'   => env('ISS_SATELLITE_BASE_URL'),
    'token'      => env('ISS_SATELLITE_TOKEN'),
    'timeout'    => env('ISS_SATELLITE_TIMEOUT', 10),
    // add a kill switch for the v0.2.4 flow until you've validated it
    'mega_queries' => [
        'distrato_avra_enabled' => env('ISS_MEGA_DISTRATO_AVRA', false),
    ],
];

Publish → edit .env → php artisan config:cache. Never the other order.

Queue the mega queries — they are named "mega" for a reason

Large/composite queries are exactly the calls that blow PHP execution limits inside a web request:

final class RunDistratoMegaQuery implements ShouldQueue
{
    use Queueable, InteractsWithQueue;

    public int $tries = 3;
    public array $backoff = [10, 60, 300];
    public int $timeout = 120;

    public function handle(SatelliteGateway $gateway): void
    {
        $gateway->distratoStatus($this->contractId);
    }
}

Set worker retry_after above the job timeout, and the job timeout above the package HTTP/client timeout. Misordering these produces duplicate submissions and infinite retries — the classic Laravel queue triad bug.

For anything dashboard-facing, cache the result rather than re-running on every page load:

Cache::remember("distrato:{$id}", now()->addMinutes(15), fn () => $gateway->distratoStatus($id));

Pin to an exact version, and review the changelog on every bump

The package is pre-1.0. Under semver, 0.x minors are allowed to break, so ^0.2 is not the safety net it looks like.

"bildvitta/iss-satellite": "0.2.4"

Add a composer.lock diff review to your PR template for this dependency specifically, and subscribe to GitHub releases on appnave/nave-satellite-iss. v0.2.4 is a patch and additive — safe. The next v0.3.0 may not be.

Test against fakes, and pin the payload shape

Http::fake(['*' => Http::response(['ok' => true], 200)]);

$gateway->distratoStatus('abc-123');

Http::assertSent(fn ($request) =>
    str_contains($request->url(), 'expected-path')
    && $request['contract_id'] === 'abc-123'
);

Write one contract test per package flow you consume — at minimum one for whatever you use today and one for the new Distrato/AVRA surface if you adopt it. These tests are what make a v0.3.0 upgrade a five-minute review instead of an incident.

Run composer audit in CI too. Low bus factor is a supply-chain concern, not just a code-quality one.

Gotchas and Tips

Vendor/org name mismatch. Composer lists bildvitta/iss-satellite; releases come from appnave/nave-satellite-iss. That's fine if it's a rename or transfer, but verify it deliberately. If your security review audited the wrong repo, you have a gap.

Pre-1.0 semver. ^0.2.4 permits 0.3.0, which can break. Pin exactly, and bump manually after reading the release notes.

Mega queries are long-running by design. Check PHP max_execution_time, your DB/HTTP client timeouts, queue retry_after, and any gateway/load-balancer timeout between you and the upstream. A query that works in php artisan tinker can time out behind nginx.

Business-logic coupling increases with each release. v0.2.4 added domain flows. Every future minor is a potential behaviour change, not just an API change. Your gateway/DTO mapping is what keeps that blast radius contained.

Release-tag hygiene. The prior metadata advertised an implausible date. The changelog now resolves that, but the lesson stands: confirm the tag exists and that composer.lock records a tag, not a commit on main. If it's a commit, your "version" is a moving target.

Config caching order. Publish → .env → config:cache. Reversing it produces invisible "my new base URL isn't used" bugs. Diagnose with php artisan config:show iss-satellite.

Migration collisions. If the package publishes migrations, check table names before running. In multi-tenant or existing databases, copy the migration into your own database/migrations with a renamed table and adjust config rather than running theirs blind.

Autoload and discovery. Provider not registering after composer require? Check bootstrap/cache/packages.php, then:

composer dump-autoload
php artisan package:discover
php artisan optimize:clear

Debugging outbound behaviour. Telescope's HTTP client watcher, or Http::globalRequestMiddleware / Http::globalResponseMiddleware, shows you exactly what the package sends — including the mega-query request bodies — without touching vendor/. For non-HTTP clients, log at your gateway boundary.

Extension points to prefer: published config, container bindings for package interfaces, and Laravel events if dispatched. Avoid editing vendor/; fork to a private VCS repo instead:

"repositories": [{ "type": "vcs", "url": "[email protected]:yourorg/nave-satellite-iss.git" }],
"require": { "bildvitta/iss-satellite": "dev-main#<sha>" }

Bus factor is still 1-ish. v0.2.4 added a first-time contributor, which is a positive signal about velocity but not about redundancy. The abstraction layer remains your exit strategy, and MIT licensing keeps fork-and-vendor clean. Realistic worst case stays: "we absorbed a few hundred lines into app/Support/IssSatellite." Document the package's responsibilities in your own README so the next maintainer doesn't have to read vendor/ to know what it does.