Laravel Resume Job Match Score Laravel Package

Technical Evaluation

Architecture fit

This is a thin Laravel service-provider wrapper over sharpapi/php-core, exposing SharpAPI's resume/job-match scoring behind publishable config and a container-bound client. That is the conventional shape for a Laravel integration package and fits cleanly into an existing app's service layer with no architectural concessions. The async job model (submit → poll fetchResults()) is the one substantive architectural constraint: it is blocking, so it belongs inside queued jobs, not the request cycle. v1.2.0 does not change this shape.

Integration feasibility

Composer-only install with a config publish step. No database migrations, no published assets, no middleware. The release corrects the documented publish tag to sharpapi-resume-match-score; the previously documented sharpapi-resume-job-match-score was wrong and would have silently produced no config file—a real onboarding trap now removed. Integration effort is measured in hours, contingent on resolving the sharpapi/php-core floor.

Technical risk

No deprecations and no major-version break. The release is a minor, but two of the changes are contract changes wearing a patch-note costume, which argues for pinning rather than floating.

Key questions

• Does api_job_status_use_polling_interval accept a floor or clamp, or can it be set to an interval low enough to self-inflict rate limiting?
• What backoff and retry behavior applies on polling failure, and does it differ between polling mode and Retry-After mode?
• On a failed job returning SharpApiJob, what surface exposes the failure—status enum, error message, raw payload—and is it documented?
• Does the ^1.4.1 constraint permit 1.5+ (forward-compatible) or is it effectively a narrow window?
• Are the Boost resources shipped in the production autoload path or dev-only?
• Is there a changelog or upgrade guide covering the error-contract change, or is the release note the only record?

Integration Approach

Stack fit

Standard Laravel package conventions: service provider, publishable config, env-backed settings. The Pest + Orchestra Testbench suite implies maintained support across current Laravel majors and a PHP 8.x floor—the package now has a testable compatibility matrix rather than an asserted one. The blocking fetchResults() polling call mandates queued execution with an explicit job timeout; this is a design requirement, not a preference.

Migration path

There is no prior installed base, so this is greenfield: composer require, publish config using the corrected sharpapi-resume-match-score tag, set SHARP_API_JOB_STATUS_USE_POLLING_INTERVAL and SHARP_API_JOB_STATUS_POLLING_INTERVAL explicitly rather than relying on defaults. For any environment already running a pre-1.2.0 build, treat the update as a minor with contract risk and pin the exact version in composer.json while validating.

Compatibility

Two things to confirm before merge: the resolved sharpapi/php-core version satisfies ^1.4.1 against the rest of the lockfile, and the Laravel/PHP version matrix is covered by the new test suite. The polling change is config-gated, so default runtime behavior is unchanged for anyone who never set the flag—a genuinely low-risk default path.

Sequencing

1. Resolve and pin dependencies; confirm no php-core constraint conflict.
2. Publish config with the corrected tag; diff against documented defaults.
3. Set polling env vars explicitly and record the chosen interval alongside its rationale.
4. Wrap calls in queued jobs with timeout and failure handling.
5. Add explicit InvalidArgumentException handling at startup or a health check, so a missing key fails visibly rather than at first customer request.
6. Add a regression test asserting a null-result failed job is detected as failure, not success.
7. Optionally install the Boost guidelines and skill for AI-assisted development.

Operational Impact

Maintenance

Small, single-purpose surface with one external dependency and a real test suite—maintenance cost is low. The residual risk is upstream: this package's health is coupled to sharpapi/php-core release cadence, and the constraint bump shows that coupling is active. The Boost guidelines modestly reduce onboarding drift by keeping generated code aligned with current core usage.

Support

Documentation accuracy improved materially; the publish-tag fix removes a class of silent-failure support tickets. Remaining sharp edge: the Boost skill is named sharpapi-resume-job-match-score while the config tag is sharpapi-resume-match-score. Minor, but it will generate confused questions—worth a one-line note in the runbook. Add a documented remedy for the missing-API-key path.

Scaling

The polling interval is the primary cost and rate-limit lever, and v1.2.0 is the first release where that lever actually moves. Teams enabling polling should set the interval at or above the API's typical Retry-After; setting it lower trades latency for request volume with no backpressure guarantee. Monitor request rate and 429s after enabling. Blocking polls also consume worker time, so queue concurrency and job timeout must be sized against expected scoring latency.

Failure modes

• Missing API key → InvalidArgumentException at construction. Fail-fast is desirable, but unguarded it crashes boot; handle at the boundary.
• Failed job with null result → SharpApiJob with no meaningful result. Code that assumes a returned object is a success will record false positives and corrupt downstream scoring data. This is the highest-consequence failure mode in the release.
• Polling enabled with a too-short interval → rate limiting and cost overrun.
• Polling disabled → falls back to Retry-After, which is correct but leaves cadence outside your control.
• Long polls in the web tier → worker exhaustion under load.

Ramp-up

Low. An experienced Laravel developer reaches productive use in well under a day, and the new test suite shortens the confidence-building phase considerably. The two items requiring deliberate review are the null-result handling contract and the polling interval value—both are configuration and code-review decisions, not learning curves.