Inštalácia

Pridajte balík, spustite jeho inštalátor a potom migrácie. Service provider sa objaví automaticky spolu s providermi balíkov Roundly, na ktorých stavia. Fasáda nemá globálny alias — importujte RoundlyConsulting\Events\Facades\Events:

composer require roundly-consulting/events-for-laravel
php artisan events:install
php artisan migrate

events:install odmietne pokračovať, kým existuje nakonfigurovaná tabuľka, ktorá nepatrí balíku — events je v aplikáciách bežný názov tabuľky (analytika, event sourcing) — a uvedie kľúč events.tables.*, ktorý treba zmeniť; vlastné tabuľky balíka po migrácii rozpozná podľa ich stĺpcov. Inak publikuje events-config a migrácie lifecycle-migrations, tags-migrations, media-migrations a events-migrations (pri zapnutej histórii slugov aj sluggable-migrations), už publikované súbory ponechá a vypíše typy kľúčov vedľa seba spolu s ďalšími krokmi. Opätovné spustenie je bezpečné, aj po migrate — napríklad keď neskôr potrebujete publikovať migrácie histórie slugov.

1. Pred migráciou ujasnite typy kľúčov

Migrácie podľa dvoch typov kľúčov volia typy stĺpcov. Pri bigint id používateľov vyhovujú predvolené hodnoty. Pri kľúčoch UUID alebo ULID ich nastavte ešte pred php artisan migrate:

EVENTS_PRIMARY_KEY_TYPE=uuid   # events and every column pointing at one (= lifecycle.key_type, tags.key_type)
EVENTS_KEY_TYPE=uuid           # organizers, attendees, co-hosts, invitees, actors (= your users)
LIFECYCLE_KEY_TYPE=uuid
LIFECYCLE_ACTOR_KEY_TYPE=uuid
TAGS_KEY_TYPE=uuid

Pri events.tags.scope = organizer je organizátor rozsahom štítkov, preto sa events.key_type musí rovnať aj tags.key_type. Model, ktorého kľúč nesedí, sa odmietne ešte pred akýmkoľvek SQL s odkazom na events.key_type — PostgreSQL by inak odpovedal surovou chybou „invalid input syntax for type bigint“ — a events:doctor ohlási každý nesúlad.

2. Ak treba, premenujte tabuľky

Názov každej tabuľky je konfigurovateľný. Ak už vaša aplikácia tabuľku events má, premenujte ich pred inštaláciou:

// config/events.php — set before events:install and php artisan migrate
'tables' => [
    'events' => 'meetup_events',            // your app already has an events table
    'venues' => 'event_venues',
    'tiers' => 'event_admission_tiers',
    'rsvps' => 'event_rsvps',
    'hosts' => 'event_hosts',
    'invitations' => 'event_invitations',
    'reminder_deliveries' => 'event_reminder_deliveries',
],

3. Pridajte traity do modelov

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use RoundlyConsulting\Events\Concerns\AttendsEvents;
use RoundlyConsulting\Events\Concerns\OrganizesEvents;
use RoundlyConsulting\Events\Contracts\Organizer;

class User extends Authenticatable implements Organizer
{
    use AttendsEvents;     // $user->rsvp($event)->going(), isGoingTo(), eventFeed(), seats freed on deletion
    use Notifiable;        // notices
    use OrganizesEvents;   // the Organizer contract's defaults
}

AttendsEvents umožní modelu odpovedať na podujatia a čítať ich, OrganizesEvents dodá predvolené hodnoty kontraktu Organizer a Notifiable prijíma notifikácie. Potom uveďte modely, na ktoré sa API smie odvolávať, cez alias — tímom ako organizátorom sa venuje stránka Organizátori, spoluorganizátori a pozvánky:

// config/events.php — the aliases the JSON API uses, never class names
'organizers' => [
    'user' => App\Models\User::class,
    'team' => App\Models\Team::class,      // list every organizer class, teams included
],

'attendees' => [
    'user' => App\Models\User::class,
],

4. Naplánujte sweepy

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('events:sweep')->everyMinute();      // held seats expire, waitlists move up, reminders go out
Schedule::command('lifecycle:sweep')->everyMinute();   // finished events complete at their end

Do plánovača sa za vás nič nepridá. Bez events:sweep vypršia rezervované miesta až pri ďalšom zápise do ich podujatia a neodíde žiadna pripomienka; bez lifecycle:sweep sa skončené podujatia nikdy samy neukončia.

5. Skontrolujte inštaláciu

php artisan events:doctor
php artisan events:doctor --counts     # also compare every event's counters with a recount
php artisan events:doctor --json       # [{severity, check, message}]

Doctor spustite po inštalácii a po každej zmene konfigurácie — zoznam kontrol nájdete na stránke Artisan príkazy.

Prechod z verzie 1.0

Verzia 1.1.0 pridáva jednu migráciu. Migrácie publikujte znova a spustite migrate:

php artisan vendor:publish --tag=events-migrations   # adds only 0008_store_event_instants_as_datetime
php artisan migrate

Na MySQL zmení 0008_store_event_instants_as_datetime každý časový stĺpec siedmich tabuliek balíka z TIMESTAMP na DATETIME: stĺpce TIMESTAMP z verzie 1.0 odmietnu dátumy po 19. 1. 2038 a pri časovom pásme s letným časom ako časovom pásme relácie MySQL aj každú hodnotu v medzere, keď sa hodiny posúvajú dopredu. Migrácia tieto tabuľky prestavia, preto ju spustite v pokojnom čase a s rovnakými nastaveniami databázového pripojenia, aké má vaša aplikácia — uložené hodnoty sa prevedú v časovom pásme relácie, v ktorom boli zapísané, takže zostanú nezmenené. Na PostgreSQL a SQLite nemení nič. events:doctor upozorňuje, kým tabuľka podujatí ukladá TIMESTAMP.

Ak ste publikovali routes/events.php, pridajte do jeho vonkajšej skupiny UseConfiguredGuard, aby čítacie routy rozpoznali používateľa guardu, ktorý uvádza váš auth_middleware (pozrite JSON API):

// routes/events.php, published before 1.1 — the outer group
use RoundlyConsulting\Events\Http\Middleware\UseConfiguredGuard;

Route::prefix(EventsConfig::routesPrefix())
    ->middleware([...EventsConfig::routesMiddleware(), UseConfiguredGuard::class])
    ->name('events.')
    ->group(static function (): void {
        // …
    });

Správanie, ktoré sa vo verzii 1.1 zmenilo:

• Predvolené referenčné resources vykresľujú type ako alias modelu z events.organizers alebo events.attendees (user) — ten istý, ktorý prijímajú telá požiadaviek a cesty alias:key —, namiesto krátkeho názvu triedy (User). Trieda, ktorá nie je ani v jednej mape, sa naďalej vykreslí krátkym názvom. Klienti, ktorí porovnávali type s krátkym názvom triedy, majú porovnávať s aliasom — alebo nastavte events.resources.* na vlastný resource.
• confirm() správcu bez referencie platby teraz znamená zaplatené inak, napríklad v hotovosti pri vstupe: online checkout rezervácie, jeho URL aj suma sa zahodia, takže neskoršia online platba toho checkoutu sa nenájde — vráťte ju. S referenciou sa miesto počíta ako zaplatené, ako doteraz.
• Účastník so stavom going alebo held, ktorý pridáva hostí, už nesmie obsadiť voľné miesta, na ktoré by sa zmestila skupina z čakacej listiny pre ten istý typ vstupenky (EventFullException, pri type vstupenky TierSoldOutException). changeGuests() správcu sa nemení.
• Vlastná platená odpoveď účastníka žiada o checkout cez manažér, takže ju Events::fake() zaznamená: po platenom RSVP assertPaymentRequested() prejde a assertNoPaymentRequested() zlyhá.

Bez inštalátora

php artisan vendor:publish --tag=events-config --tag=lifecycle-migrations \
    --tag=tags-migrations --tag=media-migrations --tag=events-migrations

Migrácie sa len publikujú — balík ich nikdy nenačíta sám — a časovú značku dostanú pri publikovaní. Ôsma, 0008, prepne časové stĺpce na MySQL na DATETIME a inde nemení nič.

php artisan vendor:publish --tag=events-translations   # lang/vendor/events/{en,sk}/*.php
php artisan vendor:publish --tag=events-views          # resources/views/vendor/events/json-ld.blade.php
php artisan vendor:publish --tag=events-routes         # routes/events.php — loads instead of the package's

Jazyky a preklady

Názvy, popisy, názvy typov vstupeniek a miest konania aj slugy podujatí sú pre každý jazyk zvlášť cez translatable-for-laravel: zadajte mapu jazykov (['en' => 'Jazz Night', 'sk' => 'Jazzový večer']) alebo reťazec v aktuálnom jazyku; čítanie ide podľa aktuálneho jazyka a potom podľa záložného reťazca. Jazyky aplikácie musia byť v translatable.locales (predvolene en, sk) — inak označovanie podľa názvu vyhodí invalid_tag. Vlastné texty balíka sú v angličtine a slovenčine s rovnakými kľúčmi a ich menný priestor je events::. Súbory:

Ak chcete zmeniť niektorý riadok alebo pridať jazyk, publikujte ich cez --tag=events-translations.

php artisan about

php artisan about --only=events

Sekcia Events ukáže podobu inštalácie — nikdy žiadne tajomstvo: