Yahoo Finance Laravel Package

Product Decisions This Supports

• Build vs. buy, scoped correctly. The package is thin glue — a service provider, one singleton client, typed request/response models, and enums — over the yfapi.net commercial API. Its value is a head start on plumbing and Laravel conventions, not data, compute, or algorithms. Treat adoption as "buy a sprint of boilerplate," not an architecture commitment.
• Which features it realistically unlocks: watchlists, quote cards, holdings/portfolio valuation snapshots, simple performance charts (history with configurable range and interval), daily digest emails and threshold alerts, internal research dashboards, CRM/account-context enrichment, and credible demo data for prototypes.
• Which features it does not de-risk: intraday ticks, order books, fundamentals, earnings, options chains, news/sentiment, cross-asset normalization, or anything requiring redistribution of market data to end users. The upstream vendor's terms constrain product scope — that is a roadmap decision, not an engineering one.
• Roadmap sequencing. Good fit for discovery, MVPs, and internal tools where "fresh within minutes" is an acceptable freshness bar. Not the substrate for a customer-facing, revenue-bearing market-data surface without a second data source and a caching/quota layer around it.
• Vendor selection. The real buy decision is yfapi.net versus Alpha Vantage, Finnhub, Polygon, Twelve Data, or IEX. Because the client is small and framework-agnostic, switching cost is low — so keep the vendor choice reversible by wrapping the client behind your own interface rather than calling it from controllers and jobs.
• Budget and legal line items. A yfapi.net key with tiered pricing becomes a recurring cost; its quota and terms-of-service review belong to product and legal. The library exposes apiKey via config/env, which makes the cost visible but does not answer the commercial questions.
• Buy vs. fork. The codebase has a deliberate generic ApiClient / EndPoints / Models split and a documented, mechanical recipe for a new endpoint (request model + endpoint + response model + factory + client method + tests). If you need one or two calls the package lacks, extending or forking is a contained task — which materially reduces the risk of adopting a low-adoption dependency.

When to Consider This Package

Adopt when:

• You are on Laravel 10–12 and PHP 8.2–8.4, with a DI-first codebase. The package is facade-free, constructor-injected, final readonly, and declare(strict_types=1) throughout, so it clears most lint and static-analysis gates without a fight.
• You need exactly two primitives — quote and history — in a small number of places: an internal dashboard, a scheduled report, a digest email.
• Volume is low and tolerant of latency or occasional failure. Quote-on-page-load, nightly snapshots, and weekly digests are the natural shapes.
• You either hold a yfapi.net key or are willing to buy one and accept its terms.
• GPL-3.0 is acceptable in writing. Internal-only use, no distribution of the application to customers, or explicit legal sign-off. Confirm this before the first commit; it is the single most likely blocker.
• You value maintained hygiene over writing it yourself: phpcs, phpstan, phpmd, and PHPUnit run across PHP 8.2–8.5, main is protected with required checks, and there is a stated versioning policy (widening supported ranges is minor; changing public methods, models, or enums is major). That is above-average discipline for a package this size.

Look elsewhere — or write ~200 lines yourself — when:

• You ship closed-source binaries, appliances, on-prem products, or marketplace plugins where GPL obligations attach. Prefer an MIT/Apache-licensed client, or own the code.
• You need an SLA, contractual support, a published security-disclosure process, or procurement sign-off on vendor viability. Adoption signals are low and maintainer concentration is unclear and must be confirmed; the bus factor is a person, not a company.
• Data must be redistributable to your customers, or you need real-time/low-latency feeds, websockets, fundamentals, options, or news. That is the wrong upstream source regardless of library quality.
• You expect caching, retry/backoff, rate-limit awareness, batching, or queue integration out of the box. You will own that layer.
• You plan to run PHP 8.5 in production imminently — 8.5 appears in tooling and CI, but confirm composer.json runtime constraints before betting a rollout on it.
• You are outside Laravel 10–12 or below PHP 8.2.

How to Pitch It (Stakeholders)

Executives — "It buys us a sprint, not a platform." Integrating a market-data surface normally means auth, endpoint handling, response parsing, and typed models. This package already does that, so a feature team ships quotes and history in days instead of a sprint. Costs are a small tiered data subscription, roughly half a day of integration, and a legal review. Log three risks: license — GPL-3.0 must be cleared before build and it constrains any future distribution model; supply — low adoption and unclear maintainer depth, mitigated by the library being thin, with a replacement cost measured in days; upstream — hard dependence on a third-party vendor's terms, quotas, and uptime, which no client library can absorb. Recommendation: approve for internal tools and discovery; do not let it underpin a customer-facing, revenue-bearing market-data product without a second data source and a caching/rate-limit layer. Keep the exit cheap by wrapping the client behind our own interface.

Engineering — "It's boring in the right ways." Composer-installable; the service provider merges and publishes a small config (apiUrl, timeout, apiKey from env) and binds a singleton client on a Guzzle/PSR-18 stack with the X-API-KEY header pre-attached. No facades; contracts are injected. Enums for Interval, Range, Region, and Lang (with select-trait helpers) and typed request/response models with factories mean autocomplete instead of array soup. YahooFinanceClient::create() accepts an injected HTTP client and logger, so tests run offline against recorded JSON over a mocked PSR-18 client — mirror that pattern rather than mocking the network. Adding a call is mechanical and documented. All gates are enforced: phpcs, phpstan, phpmd, PHPUnit 11.5/12. Respect the constraints: PHP ^8.2 floor, Laravel 10–12, no helpers, no facades, sprintf over interpolation, name properties after their types. Budget explicitly for what is not included — caching, retry/backoff, quota handling, and a fake client for local development — and assign an owner before the first integration ticket.