$keywords * @return array{id: string, url: string, alt_description: ?string}|null */ public function searchPhoto(array $keywords, string $orientation = 'portrait', ?string $colorBucket = null): ?array { $key = config('services.unsplash.access_key'); if (! $key) { Log::warning('Unsplash access key not configured'); return null; } $cleanKeywords = array_values(array_filter(array_map('trim', $keywords))); if (empty($cleanKeywords)) { return $this->tryFallbacks([], $orientation, $key); } $query = implode(' ', $cleanKeywords); // 1. all keywords + color $photo = $this->fetchOne($key, $query, $orientation, $colorBucket); if ($photo) { return $photo; } // 2. all keywords, no color if ($colorBucket !== null) { $photo = $this->fetchOne($key, $query, $orientation, null); if ($photo) { return $photo; } } // 3. only the first keyword if (count($cleanKeywords) > 1) { $photo = $this->fetchOne($key, $cleanKeywords[0], $orientation, null); if ($photo) { return $photo; } } // 4. generic fallbacks return $this->tryFallbacks($cleanKeywords, $orientation, $key); } /** * @return array{id: string, url: string, alt_description: ?string}|null */ private function fetchOne(string $key, string $query, string $orientation, ?string $colorBucket): ?array { if ($query === '') { return null; } $params = [ 'query' => $query, 'orientation' => $orientation, 'per_page' => 1, ]; if ($colorBucket) { $params['color'] = $colorBucket; } $cacheKey = 'unsplash:'.md5(json_encode($params)); $result = Cache::get($cacheKey); if ($result === null) { $response = Http::withHeaders(['Authorization' => 'Client-ID '.$key]) ->timeout(10) ->get('https://api.unsplash.com/search/photos', $params); if (! $response->successful()) { Log::warning('Unsplash search failed', ['status' => $response->status(), 'query' => $query]); return null; } $result = $response->json(); // Only cache successful responses that actually returned results, so // a transient empty hit doesn't get pinned for an hour. if (! empty(data_get($result, 'results'))) { Cache::put($cacheKey, $result, now()->addHour()); } } $first = data_get($result, 'results.0'); if (! $first) { return null; } return [ 'id' => data_get($first, 'id'), 'url' => data_get($first, 'urls.regular'), 'alt_description' => data_get($first, 'alt_description'), ]; } /** * Try each generic fallback keyword in turn. * * @param array $skip fallback keywords to skip (already tried) * @return array{id: string, url: string, alt_description: ?string}|null */ private function tryFallbacks(array $skip, string $orientation, string $key): ?array { foreach (self::FALLBACK_KEYWORDS as $keyword) { if (in_array($keyword, $skip, true)) { continue; } $photo = $this->fetchOne($key, $keyword, $orientation, null); if ($photo) { Log::info('Unsplash fell back to generic keyword', ['keyword' => $keyword]); return $photo; } } Log::warning('Unsplash exhausted all fallbacks'); return null; } }