Aller au contenu

Utilisation

tilttek/friend-challenges

Créer un défi

Un membre demande un défi avec un ChallengeDraft : son identifiant, choisi par l'application — un ULID, un UUID —, son titre de 120 caractères au plus, son lot, sa fin, les amis qu'il invite, qui peut y participer, qui juge ses preuves, ses conditions de 2 000 caractères au plus et, pour un vote, les votes nécessaires.

use Tilttek\FriendChallenges\ChallengeDraft;
use Tilttek\FriendChallenges\Prize;
use Tilttek\FriendChallenges\Validation;
use Tilttek\FriendChallenges\Visibility;

$challenge = $challenges->create(new ChallengeDraft(
    id: '01JD3',
    title: 'Paint ten minis in a week',
    prize: new Prize(100),                       // 100 points; new Prize(5, 'gems') for another unit of points
    endsAt: new DateTimeImmutable('+7 days'),
    invitees: [$bea, $cy, $dee],
    visibility: Visibility::Friends,             // the default; Visibility::Open lets any member take part
    validation: Validation::Vote,                // or Validation::Creator, the default, or Validation::Moderator
    description: "Ten minis.\nOne photo of each.",
    votesNeeded: 2,
), $ana);

La création vérifie le brouillon selon les ChallengeRules du site — la durée du défi, le plus gros lot —, vérifie que chaque invité est un ami du créateur par Contract\Friendship, détient le lot pris sur les points du créateur, conserve le défi, puis répartit ChallengeCreated et un MemberInvited pour chaque ami. Le même brouillon envoyé de nouveau par le même créateur rend le défi qu'il a créé et ne détient rien de plus ; le même identifiant avec un autre brouillon est refusé. Un lot que les points du créateur ne couvrent pas lance InsufficientPoints, et rien n'est créé.

Un défi entre amis en invite de 1 à 50 ; un défi ouvert n'invite personne en particulier. Le créateur établit et juge le défi, et n'y participe jamais.

Participer

$challenges->join('01JD3', $bea);
$challenges->decline('01JD3', $dee);

Un ami invité — ou n'importe quel membre, dans un défi ouvert — participe jusqu'à la fin du défi ; un défi accepte 100 participants au plus. Un ami invité peut décliner ; le défi garde qui a décliné, et une application montre au créateur qui participe, jamais qui a décliné. Un ami qui a décliné peut encore participer avant la fin.

Les preuves et leur examen

$challenges->submitProof('01JD3', 'proof-1', $bea, 'upload:8812');
$challenges->approve('01JD3', 'proof-1', $ana);
$challenges->reject('01JD3', 'proof-2', $ana);

Un participant envoie une preuve jusqu'à la fin du défi : un identifiant de la preuve, choisi par l'application, et une référence opaque du justificatif que conserve l'application — un téléversement, un journal de partie, un message —, de 500 octets au plus et sans espace. Un participant envoie cinq preuves au plus, et un défi en contient 200.

Les preuves sont examinées jusqu'à reviewEndsAt, la fin du défi plus l'examen que donnent les règles, trois jours par défaut. Qui les examine dépend de sa Validation :

ValidationQui approuve ou rejetteQuand une preuve est acceptée
CreatorLe créateurÀ l'approbation du créateur
ModeratorUn modérateur du site, comme le dit Contract\Moderation::mayModerate()À l'approbation d'un modérateur
VoteLe créateur et les participants, chacun sur les preuves des autresQuand les votes nécessaires l'approuvent ; rejetée quand les votes nécessaires la rejettent

Un votant vote une fois sur une preuve et ne change pas son vote. La première preuve acceptée gagne : son participant est le gagnant, le lot lui est payé, et ChallengeWon est réparti.

Comment un défi se termine

MouvementParQuandLe lot
Une preuve acceptéeSon jugeAvant la fin de l'examenPayé au gagnant
cancel()Le créateurAvant l'envoi de toute preuveRendu au créateur
expire(), expireDue()Une tâche planifiéeUne fois l'examen fini, sans preuve acceptéeRendu au créateur
remove()Un modérateurTant que le défi est ouvert ou geléRendu au créateur
open ──► won
 │ ▲  └─► cancelled | expired
 ▼ │
frozen ──► removed ◄── open

Un défi réglé ne change plus jamais. Chaque mouvement qui termine un défi répartit ChallengeWon ou ChallengeEnded, après son mouvement de séquestre.

Lire un défi

get($id) rend le Challenge : son état, ses participants, ses preuves avec leur état et leurs votes, son gagnant et le moment de son règlement. Challenge::toArray() rend l'enregistrement que conserve une application, et Challenge::fromArray() le relit, vérifié champ par champ et dans son ensemble : un enregistrement qu'aucun mouvement n'aurait pu écrire est refusé avec InvalidChallenge.

Heures

Toute heure est conservée en UTC à la microseconde près, quel que soit le fuseau horaire de l'horloge ou du brouillon. La bibliothèque ordonne les heures avec < et >=, et ne compare deux heures que par ce qu'elles écrivent, jamais avec == ni ===.