Stubs Laravel Package

Technical Evaluation

What the artifact actually is. tarantool/stubs is not a runtime library — it is a declaration-only package (class/function/constant signatures with empty bodies) whose only consumers are IDEs (PhpStorm, Intelephense) and static analyzers (PHPStan, Psalm). It exists because the Tarantool PHP connector is delivered as a C extension (PECL tarantool) whose symbols are invisible to reflection-based tooling on machines where the extension is not built, which is the normal state of a Laravel developer's laptop and of most CI runners.

Architecture fit. Essentially zero coupling: no autoloaded production classes, no service provider, no config, no framework hooks. It is a require-dev artifact that sits alongside phpstan/phpstan or vimeo/psalm in any Laravel codebase. There is no architectural conflict with Laravel's conventions because nothing ships to production.

Integration feasibility. High, with one non-obvious wiring constraint. Stubs must be registered as analysis-only inputs — PHPStan's stubFiles/scanFiles, Psalm's <stubs>, or an IDE include path — and must not be added to Composer's files/autoload for runtime, or the class declarations will collide with the real extension and produce Cannot redeclare class fatals. Done correctly, this is a one-file config change.

Technical risk.

• Version drift. Stubs are a hand-maintained snapshot; nothing verifies they match the installed extension version. A stub can advertise a method the deployed extension does not have, converting a compile-time IDE warning into a runtime fatal.
• False confidence. Green PHPStan results prove the shape of the API, not that the extension is installed, reachable, or semantically equivalent. Static analysis passing must never be treated as an integration smoke test.
• Relevance risk (the biggest one). These stubs only pay off for the legacy PECL C extension. If the team standardizes on the pure-PHP tarantool/client, the stubs are redundant — that client ships real classes with docblocks that IDEs and analyzers resolve natively. This should be resolved before anything else.
• Low community signal. Zero stars, zero dependents, zero score. Mitigated somewhat by official Tarantool GitHub-org provenance and by a stub surface small enough to review line-by-line in minutes, but it means no peer vetting and no third-party bug reports.

Key questions.

1. Which connector is in use — PECL tarantool extension or pure-PHP tarantool/client? If the latter, this package is a no-op.
2. Which extension version is pinned in staging/production, and does a stub release correspond to it?
3. PHP and Laravel version matrix — do the stub files parse cleanly across all supported runtimes?
4. Do we run PHPStan, Psalm, or both, and at what level? Level 0 gives near-zero return.
5. Is a Composer require-dev addition acceptable in the shared platform template, or must this be vendored internally?

Integration Approach

Stack fit. Add to composer.json under require-dev; excluded automatically from composer install --no-dev production builds. Register in phpstan.neon (stubFiles: or scanFiles:) and/or psalm.xml (<stubs>). For PhpStorm, mark the vendor path as included but excluded from indexing-as-source, or rely on the Composer resolution. No Laravel config, no .env, no container bindings.

Migration path. Pilot in a single service that already talks to Tarantool. Capture a PHPStan baseline before and after; the delta is the measurable value (previously-unresolved calls to extension classes now type-checked). If the delta is real, promote the config snippet to the internal Laravel service template; if not, drop it and document why.

Compatibility. Two hard constraints: (a) stub files must parse under every PHP version in the matrix — stubs sometimes use newer syntax than the floor version; (b) the stubs must not shadow the extension on runners where the extension is actually installed. Prefer real extension reflection over stubs whenever extension_loaded('tarantool') is true.

Sequencing.

1. Resolve the connector question (extension vs. pure-PHP client) — gate for everything else.
2. Identify the exact PECL extension version in staging/production and pin the stub package to a matching tag/commit; never track dev-master.
3. Review the stub file contents (small, auditable) and record the API surface covered.
4. Wire into require-dev + static analysis config on one service.
5. Add a CI job running analysis at a meaningful level, plus a drift check: on a runner where the extension is installed, diff ReflectionExtension('tarantool') signatures against the stub declarations and fail on mismatch.
6. Document in the onboarding runbook: "if you add a Tarantool call and the IDE does not resolve it, check the stub pin first."

Operational Impact

Maintenance. Upstream lives in the official Tarantool org but is a low-traffic artifact with no evident release cadence. Assume it will lag new extension releases. We own the drift check that compensates for this; without it the stubs silently rot into a liability.

Support. Community-only, no SLA, no vendor escalation. The mitigation is size: the package is small enough to fork and patch internally at negligible cost if it is abandoned or wrong, which is why internal vendoring is a credible fallback rather than a project.

Scaling. Effectively free at runtime — no memory, no boot cost, no autoload pressure in production. The only scaling dimension is CI minutes and the number of repos that carry the config; standardize the snippet so this does not get re-litigated per service.

Failure modes.

• Stub/runtime mismatch → fatal Call to undefined method in production that analysis explicitly blessed.
• Misconfigured autoload → Cannot redeclare class at boot, typically only in environments where the extension is installed (i.e., staging/prod, not dev) — a classic late-detection failure.
• Stale stubs after an extension upgrade → analyzers keep passing against a removed API.
• Analyzer green mistaken for integration correctness → the real risk to watch culturally, not technically.
• Supply chain: dev-only and non-executing, but Composer scripts still run on install — review the archive or install with --no-scripts/--no-plugins in CI.

Ramp-up. Hours, not days, for anyone comfortable with PHPStan/Psalm configuration. Budget roughly half a day to include the drift check and runbook entry. The dominant cost is not the tooling — it is the diligence of pinning and verifying against the deployed extension version, which is a process obligation rather than a technical one.