Miesta konania a hľadanie v okolí

Miesto konania sa dá použiť pre viacero podujatí a jeho časové pásmo určuje, ako sa čítajú všetky miestne časy jeho podujatí:

$venue = Events::venues()->make(['en' => 'City Park', 'sk' => 'Mestský park'])
    ->address(street: 'Námestie slobody', city: 'Bratislava', region: 'BA', postalCode: '811 06', country: 'SK')
    ->formattedAddress('Námestie slobody, 811 06 Bratislava')   // optional; else built from the parts
    ->coordinates(48.1530, 17.1130)                             // or a Coordinates
    ->timezone('Europe/Bratislava')
    ->capacity(500)
    ->ownedBy($team)                                            // "my venues"
    ->meta(['floor' => 1])                                      // private: never in API output
    ->by($user)                                                 // checks the venue policy
    ->create();

Názov je povinný (pre každý jazyk), krajina je kód ISO 3166-1 alpha-2 (veľkými písmenami), časové pásmo platný názov IANA (inak events.venues.default_timezone, inak pásmo aplikácie), súradnice v rozsahu a kapacita ≥ 0 — len informatívna, keďže miesta počíta kapacita podujatia. Prázdne časti adresy sa uložia ako null.

Úprava a ďalšie operácie

use RoundlyConsulting\Events\DataTransferObjects\AddressData;
use RoundlyConsulting\Events\DataTransferObjects\UpdateVenueData;
use RoundlyConsulting\Events\DataTransferObjects\VenueData;

Events::venues()->by($user)->update($venue, new UpdateVenueData(capacity: 600));

// In PHP an address is one value: it replaces all six address columns, so pass every part you keep.
// (The API's PATCH changes each address field on its own.)
Events::venues()->update($venue, new UpdateVenueData(address: new AddressData(
    street: 'Hlavná 1', city: 'Košice', postalCode: '040 01', country: 'SK',
)));

// A DTO may carry its own actor; on a by() accessor it is that actor (another one is refused).
Events::venues()->create(new VenueData(name: 'Studio', owner: $team, actor: $user));
Events::venues()->by($user)->create(new VenueData(name: 'Studio', owner: $team));   // the same check

$venues = Events::venues()->by($user);   // checks the VenuePolicy on every following write

$venues->geocode($venue);               // look the coordinates up now (only missing ones unless force: true)
$venues->delete($venue);                // soft; refused (venue_in_use) while an unfinished event uses it
$venues->restore($venue);

Events::venues()->find(7);
Events::venues()->ownedBy($team)->get();          // an organizer's own list
Events::venues()->near($here, km: 10)->get();     // venues within 10 km

$venue->coordinates;            // ?Coordinates
$venue->formattedAddress();     // the stored one-line address, else the parts joined

• update() zmení len zadané polia. Nový názov, adresa alebo súradnice zvýšia SEQUENCE v kalendári pri ohlásených podujatiach miesta, ktoré ešte neskončili, takže odoberané kalendáre prevezmú nové LOCATION a GEO.
• delete() je soft delete, ktorý sa odmietne, kým miesto používa koncept alebo naplánované, odložené či presunuté podujatie. Minulé podujatia si zmazané miesto ponechajú ($event->venue zahŕňa aj zmazané) a API ho vykreslí s deleted: true.

Kto smie miesto konania meniť

Miesta konania sú fyzické priestory: akýkoľvek organizátor môže usporiadať podujatie na akomkoľvek mieste, vlastnenom aj zdieľanom. Vlastníctvo rozhoduje len o tom, kto ho upravuje:

Policies\VenuePolicy má viewAny a view (ktokoľvek), create (prihlásený, plus events.authorization.abilities.venues, ak je nastavené), update, delete, restore a geocode (pravidlá vyššie) a manageShared (administrátori a abilities.shared_venues; null znamená len administrátori). Vymeníte ju cez events.authorization.venue_policy. Cez API patrí miesto vytvorené bez vlastníka volajúcemu — zdieľané si vyžiadate cez shared: true. Dôveryhodné PHP (bez by()) sa nikdy nekontroluje, takže seedery a importy zdieľané miesta vytvoria.

Geokódovanie

Geokódovanie ide cez adresnú pipeline balíka Geolocation for Laravel, a to len vtedy, keď oň požiadate:

• ->geocode() na builderi alebo Events::venues()->geocode($venue) — hneď.
• events.venues.geocode_on_create = on — každé nové miesto bez súradníc, vo fronte po commite (Jobs\GeocodeVenueJob). Limit požiadaviek úlohu uvoľní na opakovanie po retryAfterSeconds() poskytovateľa; zmazané miesto sa preskočí.
• php artisan events:geocode hromadne a POST /api/event-venues/{venue}/geocode, ktorý vždy geokóduje znova.

php artisan events:geocode                 # venues without coordinates (--missing, the default)
php artisan events:geocode --venue=7       # one venue (skipped when it has coordinates, unless --force)
php artisan events:geocode --force         # every venue again
php artisan events:geocode --chunk=200     # venues per batch (default 100)

Vyhľadávanie pošle formattedAddress() do locateAddress() z geolocation; miesto bez akejkoľvek adresy je neúspech. Ak geokódovanie nevynútite, doplnia sa len chýbajúce súradnice a časové pásmo sa nikdy nezmení. Neúspech miesto ponechá a spustí VenueGeocodingFailed — aj vtedy, keď pipeline vráti svoju záverečnú predvolenú polohu, ktorá by všetky miesta umiestnila na to isté miesto. Úspech spustí VenueGeocoded.

V okolí

use RoundlyConsulting\Geolocation\DataTransferObjects\Coordinates;
use RoundlyConsulting\Geolocation\Facades\Geolocation;

$here = Geolocation::locateRequest($request)?->coordinates()   // the visitor's IP — see Privacy
    ?? new Coordinates(48.1486, 17.1077);

Events::browse($viewer)
    ->upcoming()
    ->near($here, km: 25)        // a bounding box on the venue's indexed coordinates, then the exact distance
    ->withDistance($here)        // adds distance_km (null for an event without a venue)
    ->orderByDistance($here)     // nearest first; events without a venue last in either direction
    ->paginate(20);

• km musí byť v intervale (0, events.geo.max_radius_km] (500); bez neho platí events.geo.default_radius_km (25). Podujatia len online nikdy nevyhovujú near().
• withDistance() zachová existujúci select (events.*, ak žiadny nie je); jeho väzby sú v časti select a radenie v časti order, takže počty pri stránkovaní sedia na každom engine. Scopes berú pomenované argumenty — near($here, km: 25).
• Vzdialenosť počíta ten istý vzorec po hlavnej kružnici ako Coordinates::distanceTo() z geolocation (R = 6371,0 km, ohraničený tak, aby protiľahlé body nikdy nespôsobili chybu), takže SQL a PHP sa na MySQL aj PostgreSQL zhodnú s presnosťou na meter. SQLite — len v testoch — používa zaregistrovanú funkciu events_distance_km().
• Geolocation::locateRequest($request) posiela IP adresu návštevníka poskytovateľom IP lokalizácie v geolocation — uveďte to vo vyhlásení o ochrane súkromia alebo sa na polohu radšej opýtajte.