Telefonkatalog Laravel Package

Technical Evaluation

Architecture fit

telefonkatalog is a thin third‑party adapter, not core domain logic. It wraps two Norwegian directory sources (Gulesider, Opplysningen1890) behind a Laravel‑style API and returns phone number data. Architecturally it belongs at the edge of the system, behind an interface you own (e.g. PhoneLookupService), so that the vendor coupling is contained and swappable. It should not be called inline from request handlers or domain models.

Integration feasibility

Low lift. Standard Composer install, service provider auto‑discovery, likely publishable config. No database migrations, no queue workers, no infrastructure changes implied by the release notes. A single engineer can integrate in under a day, excluding legal/ToS review.

Technical risk

• Scraping is the dominant risk. The v1.3.0 changelog confirms Gulesider changed its site structure and the scraper had to be rewritten from __NEXT_DATA__ to JSON‑LD. That is a live demonstration of external coupling, not a hypothetical. Expect recurrence.
• No upstream contract or SLA. Both sources are consumer websites with no API agreement; they can change markup, add bot protection, rate‑limit, or block IPs without notice.
• Legal/compliance. Directory listings include personal data for natural persons under GDPR. Scraping may conflict with the sources' terms of service. This needs a written position before production use, not after.
• Data-freshness and correctness are unverified. A "not found" from the scraper is not authoritative proof the number doesn't exist.
• Dropped Laravel 10 support in a minor version is a semver surprise and a supply-chain consideration for anyone relying on ^1.0.

Key questions

1. Does the package cache results, and is there any built‑in rate limiting or backoff? (Not mentioned in the release notes.)
2. Does the Opplysningen1890 "missing phone number" fix surface a typed result/exception, or a silent null?
3. How are transport failures (429, 403, 5xx, timeouts) distinguished from genuine empty results? The new edge‑case tests cover empty results — do they cover blocked/challenged responses?
4. Is there a documented user‑agent, timeout, and retry policy?
5. What is the maintainer bus factor, and what is the realistic patch latency when a source breaks again?
6. Has legal reviewed the ToS and GDPR position for our specific use case (internal enrichment vs. end‑user facing)?

Integration Approach

Stack fit

Targets Laravel 11 and 12 (Testbench ^9.0|^10.0), PHP 8.2+. Testing stack moved to Pest v3. Development tooling additions (justfile) and removed dev dependencies (nunomaduro/collision, pestphp/pest-plugin-arch) are irrelevant to production runtime — treat them as neutral.

Migration path

• On Laravel 10: this release is a hard stop. v1.3.0 drops support. Pin to ^1.2 explicitly in composer.json (e.g. "helgesverre/telefonkatalog": "~1.2.0") so an unrestricted composer update cannot silently pull a version your framework can't run. Note this is a breaking change shipped as a minor bump — do not assume ^1.0 is safe.
• On Laravel 11/12: straightforward composer require bump. No application code changes expected; the scraper internals changed, not the public API, though this should be confirmed against the package's own API surface before assuming.
• Do not upgrade Laravel and this package in the same change. Sequester the framework upgrade from the dependency bump so failures are attributable.

Compatibility

Laravel 11/12 only. Confirm PHP constraint against your runtime images. If you run a mixed fleet across services, inventory which services are on L10 before deciding — the package may be fine for one service and blocked for another.

Sequencing

1. Inventory Laravel versions in every service that would consume this.
2. Pin ~1.2.0 in any L10 service to freeze the risk.
3. For L11/12 services: define your own PhoneLookup interface and adapter first, with the package as an implementation detail.
4. Bump to v1.3.0 behind that interface.
5. Add contract tests against recorded fixtures so a future upstream breakage is caught by your CI, not your users.
6. Only then evaluate production enablement, after legal sign‑off.

Operational Impact

Maintenance

Higher than a typical Composer dependency, and the cost is recurring rather than one‑off. The Gulesider rewrite is the first data point; budget for periodic breakage and a maintenance owner with PHP skills to patch scrapers. If nobody owns that, the feature will rot silently.

Support

Community open‑source, effectively single‑maintainer, no commercial support path. Mitigation options in order of preference: (a) wrap behind your own interface so you can hot‑swap providers; (b) vendor/fork the scraper logic for the sources you actually use; (c) accept the risk with monitoring. Note that fixes depend on the maintainer's availability — the release notes give no indication of a response SLA.

Scaling

Scraping scales poorly by construction: every lookup is an outbound HTTP call to a third party you don't control. Expect latency in the hundreds of milliseconds to seconds, and throughput bounded by the sources' tolerance for your traffic, not your infrastructure. Required before any meaningful volume:

• Aggressive caching keyed by normalized phone number, with a defined TTL and staleness policy.
• Queueing so lookups never sit in the user request path.
• Concurrency and rate limits per source, well below anything that looks like abuse.
• A circuit breaker so a blocked source degrades gracefully instead of timing out.

Failure modes

The critical implementation detail: your adapter must be able to tell "not found" from "lookup failed." The release adds tests for empty results but the changelog does not confirm failure-vs-absence semantics are explicit. If both collapse to null, every consumer downstream will silently treat an outage as "no such number" — that is the failure mode most likely to cause real business harm.

Ramp-up

Low. A mid-level Laravel engineer is productive with this package in a few hours; the API surface is small. The real ramp-up cost is not technical — it is the domain and legal context: understanding Norwegian directory data quality, GDPR obligations for personal data, and what the business is actually allowed to do with the results. Budget that time on the legal/compliance side, not engineering.

Recommendation

Integrate only behind an owned interface, only with caching and queueing, only on Laravel 11/12, and only after a documented ToS/GDPR position. Treat the package as a best-effort enrichment source, never as an authoritative directory.