Konfigurácia

Po nastavení kľúča balík funguje bez ďalšej konfigurácie — každá hodnota má predvolenú hodnotu a väčšina sa dá nastaviť cez env. Publikovaný config/google-places.php:

return [
    'key' => env('GOOGLE_PLACES_API_KEY'),

    'hosts' => [
        'places' => env('GOOGLE_PLACES_HOST', 'https://places.googleapis.com/v1'),
        'routes' => env('GOOGLE_ROUTES_HOST', 'https://routes.googleapis.com'),
        'geocoding' => env('GOOGLE_GEOCODING_HOST', 'https://maps.googleapis.com/maps/api'),
    ],

    'field_masks' => [
        'details' => 'id,displayName,formattedAddress,location,viewport,types,regularOpeningHours,photos',
        'autocomplete' => 'suggestions.placePrediction.placeId,suggestions.placePrediction.text,suggestions.placePrediction.structuredFormat,suggestions.placePrediction.types',
        'search' => 'places.id,places.displayName,places.formattedAddress,places.location,places.viewport,places.types,places.regularOpeningHours,places.photos',
        'routes' => 'originIndex,destinationIndex,distanceMeters,duration,condition,status',
    ],

    'http' => [
        'timeout' => env('GOOGLE_PLACES_TIMEOUT', 10),
        'connect_timeout' => env('GOOGLE_PLACES_CONNECT_TIMEOUT', 5),
        'retries' => env('GOOGLE_PLACES_RETRIES', 2),
        'retry_delay' => env('GOOGLE_PLACES_RETRY_DELAY', 200),
    ],

    'cache' => [
        'enabled' => env('GOOGLE_PLACES_CACHE', false),
        'store' => env('GOOGLE_PLACES_CACHE_STORE'),
        'ttl' => env('GOOGLE_PLACES_CACHE_TTL', 86400),
    ],

    'pagination' => [
        'max_pages' => env('GOOGLE_PLACES_MAX_PAGES', 5),
    ],

    'logging' => [
        'enabled' => env('GOOGLE_PLACES_LOGGING', false),
        'channel' => env('GOOGLE_PLACES_LOG_CHANNEL'),
    ],

    'rate_limits' => [
        'owner' => env('GOOGLE_PLACES_RATELIMIT_OWNER', 'app'),

        'places' => [
            'enabled' => env('GOOGLE_PLACES_PLACES_RATELIMIT_ENABLED', true),
            'limit' => env('GOOGLE_PLACES_PLACES_RATELIMIT', 600),
            'per' => env('GOOGLE_PLACES_PLACES_RATELIMIT_PER', 'minute'),
            'adaptive' => env('GOOGLE_PLACES_PLACES_RATELIMIT_ADAPTIVE', true),
            'max_wait' => env('GOOGLE_PLACES_PLACES_RATELIMIT_MAX_WAIT'),
            'jitter' => env('GOOGLE_PLACES_PLACES_RATELIMIT_JITTER'),
        ],

        // 'routes' => [...] and 'geocoding' => [...] — same keys, own env prefix
    ],
];

Všetky kľúče

Každá hodnota sa číta striktne: kľúč, ktorý nie je nastavený, dostane predvolenú hodnotu a čokoľvek neplatné vyhodí RoundlyConsulting\PackageToolkit\Exceptions\InvalidConfigurationException s názvom kľúča — nikdy sa potichu nepoužije náhradná hodnota. Prázdna hodnota znamená nenastavené: chýbajúci kľúč, null aj prázdna hodnota (riadok KEY= v hostiteľskej aplikácii, prázdny alebo len s medzerami) dostanú predvolenú hodnotu.

Prepínač typu bool prijme true/false, 1/0, on/off alebo yes/no — z .env aj z publikovaného súboru.
Celé číslo (int) prijme celé číslo alebo celočíselný reťazec ('30'). 'five', '5.5', '5s' alebo hodnota mimo rozsahu vyhodí výnimku. Timeouty, cache.ttl, pagination.max_pages a limit rate limitu musia byť aspoň 1; retries, retry_delay, max_wait a jitter aspoň 0.
rate_limits.{surface}.per musí byť presne second, minute, hour alebo day.
Reťazcové nastavenie — hosts.*, field_masks.*, cache.store, logging.channel, rate_limits.owner — musí byť reťazec. Prázdny host znamená vlastný host Google a prázdny store, kanál či vlastník predvolenú hodnotu. Maska polí predvolenú hodnotu nemá: prázdna vyhodí výnimku „required but missing“.

Kľúč	Predvolené	Env	Účel
`key`	null	`GOOGLE_PLACES_API_KEY`	API kľúč. Posiela sa ako X-Goog-Api-Key (Places/Routes) a key= (Geocoding). Povinný.
`hosts.places`	https://places.googleapis.com/v1	`GOOGLE_PLACES_HOST`	Host Places API (New). Reťazec; prázdna hodnota = nenastavené → vlastný host Google.
`hosts.routes`	https://routes.googleapis.com	`GOOGLE_ROUTES_HOST`	Host Routes API (vzdialenosť a čas presunu). Reťazec; prázdna hodnota = nenastavené → vlastný host Google.
`hosts.geocoding`	https://maps.googleapis.com/maps/api	`GOOGLE_GEOCODING_HOST`	Host Geocoding API (spätné aj priame geokódovanie). Reťazec; prázdna hodnota = nenastavené → vlastný host Google.
`field_masks.details`	pozrite config	—	X-Goog-FieldMask pre detail miesta. Každá maska musí byť reťazec; maska nemá náhradnú hodnotu, takže prázdna vyhodí výnimku (povinná, no chýba).
`field_masks.autocomplete`	pozrite config	—	X-Goog-FieldMask pre našepkávanie.
`field_masks.search`	pozrite config	—	X-Goog-FieldMask pre textové a okolité vyhľadávanie.
`field_masks.routes`	pozrite config	—	X-Goog-FieldMask pre vzdialenosť a maticu trás.
`http.timeout`	10	`GOOGLE_PLACES_TIMEOUT`	Timeout požiadavky (sekundy), aspoň 1.
`http.connect_timeout`	5	`GOOGLE_PLACES_CONNECT_TIMEOUT`	Timeout pripojenia (sekundy), aspoň 1.
`http.retries`	2	`GOOGLE_PLACES_RETRIES`	Počet opakovaní pri zlyhaní spojenia, 0 alebo viac.
`http.retry_delay`	200	`GOOGLE_PLACES_RETRY_DELAY`	Pauza medzi opakovaniami (ms), 0 alebo viac.
`cache.enabled`	false	`GOOGLE_PLACES_CACHE`	Cachovať idempotentné dopyty (detail, geokódovanie, vzdialenosť, matica, vyhľadávanie).
`cache.store`	null	`GOOGLE_PLACES_CACHE_STORE`	Cache store; nenastavené, null alebo prázdna hodnota = predvolený store. Hodnota, ktorá nie je reťazcom, vyhodí výnimku.
`cache.ttl`	86400	`GOOGLE_PLACES_CACHE_TTL`	Platnosť cache (sekundy), aspoň 1.
`pagination.max_pages`	5	`GOOGLE_PLACES_MAX_PAGES`	Bezpečnostný strop pre stránkované vyhľadávanie, aspoň 1; pri dosiahnutí sa zaloguje varovanie.
`logging.enabled`	false	`GOOGLE_PLACES_LOGGING`	Logovať každú požiadavku (endpoint, stav, trvanie). API kľúč sa nikdy nezaloguje.
`logging.channel`	null	`GOOGLE_PLACES_LOG_CHANNEL`	Log kanál; nenastavené, null alebo prázdna hodnota = predvolený kanál. Hodnota, ktorá nie je reťazcom, vyhodí výnimku.
`rate_limits.owner`	app	`GOOGLE_PLACES_RATELIMIT_OWNER`	Vlastník limitu, spoločný pre všetky API (google-places:{surface}:{owner}). Reťazec; prázdna hodnota = nenastavené → app.
`rate_limits.{surface}.enabled`	true	`GOOGLE_PLACES_{SURFACE}_RATELIMIT_ENABLED`	Obmedzovať toto API (places / routes / geocoding); false = bez obmedzenia.
`rate_limits.{surface}.limit`	600	`GOOGLE_PLACES_{SURFACE}_RATELIMIT`	Max. počet požiadaviek za okno, aspoň 1.
`rate_limits.{surface}.per`	minute	`GOOGLE_PLACES_{SURFACE}_RATELIMIT_PER`	Okno: presne second, minute, hour alebo day; čokoľvek iné vyhodí výnimku.
`rate_limits.{surface}.adaptive`	true	`GOOGLE_PLACES_{SURFACE}_RATELIMIT_ADAPTIVE`	Samoladenie podľa Retry-After z odpovede 429.
`rate_limits.{surface}.max_wait`	null	`GOOGLE_PLACES_{SURFACE}_RATELIMIT_MAX_WAIT`	Rýchle zlyhanie (ms, 0 alebo viac) namiesto čakania; null alebo prázdna hodnota = čakať.
`rate_limits.{surface}.jitter`	null	`GOOGLE_PLACES_{SURFACE}_RATELIMIT_JITTER`	Náhodný rozptyl (ms, 0 alebo viac) pridaný k odloženému volaniu; null alebo prázdna hodnota = žiadny.

Field masky

Places API (New) aj Routes API vyžadujú hlavičku X-Goog-FieldMask so zoznamom vrátených polí — požiadavka bez nej skončí chybou. Predvolené masky sú striedme; orežte ich, aby ste platili len za polia, ktoré používate, alebo ich rozšírte, keď potrebujete viac. Napríklad typované komponenty adresy pri mieste vyžadujú addressComponents v maske pre detail:

// config/google-places.php — add addressComponents so Place::components() is populated
'field_masks' => [
    'details' => 'id,displayName,formattedAddress,location,viewport,types,regularOpeningHours,photos,addressComponents',
    // ...
],

Jednotlivá požiadavka na detail môže masku prepísať aj bez zásahu do konfigurácie — pozrite Detail miesta.

Hosty

Každý produkt Google má vlastný host. Prepíšte ich, len ak Google smerujete cez vlastnú bránu. Spätné aj priame geokódovanie zámerne používa Geocoding API, ktoré sa autentifikuje parametrom key v URL; Places a Routes používajú hlavičku X-Goog-Api-Key.

Prostredie (env)

Bežné prepínače sa riadia cez env, takže konfiguráciu publikujete len zriedka:

GOOGLE_PLACES_API_KEY=your-google-maps-api-key

GOOGLE_PLACES_TIMEOUT=10
GOOGLE_PLACES_CONNECT_TIMEOUT=5
GOOGLE_PLACES_RETRIES=2
GOOGLE_PLACES_RETRY_DELAY=200

GOOGLE_PLACES_CACHE=true
GOOGLE_PLACES_CACHE_TTL=86400

GOOGLE_PLACES_LOGGING=true
GOOGLE_PLACES_LOG_CHANNEL=stack

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

Ponuka do 48 hodín Prezrieť všetky balíky