Skip to content

Extension points

tilttek/friend-challenges

The package is at 0.x: its extension points are stable only from its 1.0 release. Until then, a minor version may change them, and its CHANGELOG says how.

PointWhat an application givesShipped
Contract\ChallengeStoreWhere the challenges are kept: a table of records, a document storeStore\InMemoryChallengeStore
Contract\PrizeEscrowWhere the prizes are held: see EscrowEscrow\PointsPrizeEscrow, Escrow\InMemoryPrizeEscrow
Contract\FriendshipWho is a friend of whom, from the site's social graphStore\InMemoryFriendship
Contract\ModerationWhere reports go, and who moderates: see ModerationStore\InMemoryModeration
ChallengeRulesHow long a challenge lasts, its review, its largest prizeits defaults
Psr\EventDispatcher\EventDispatcherInterfaceWhere the events gonone: nothing is dispatched
Psr\Clock\ClockInterfaceThe time of each moveSymfony\Component\Clock\NativeClock

Every point is passed to the constructor of FriendChallenges, which keeps nothing between two calls.

Writing a store

A ChallengeStore keeps one record a challenge, Challenge::toArray(), and gives it back through Challenge::fromArray(). What every implementation does:

  • get($id) gives the challenge, or null.
  • add($challenge) keeps a new challenge, and throws ChallengeConflict when one of the same identifier is kept.
  • update($challenge, $expected) keeps the challenge at its next version if and only if the kept one is still at version $expected, and otherwise throws ChallengeConflict and writes nothing. In a database, an UPDATE … WHERE id = ? AND version = ? that counts the rows it changed gives exactly that.
  • due($at, $limit) lists the identifiers of the open challenges whose review_ends_at is at or before $at, the earliest first, $limit at most; an index on the state and review_ends_at answers it.
  • involving($member, $limit) lists the identifiers of the challenges that name the member — see Challenge::involves(): the creator, the invitees and the participants —, $limit at most, for its erasure. A table of the members of each challenge, written with the record, answers it.

Keep the times of the record as the UTC texts it holds, or in UTC columns. When the challenges and the escrow live in the same database, keep the creation of a challenge and its hold in one transaction.

The events

Each event is dispatched once its move is kept and settled, never for a move made again:

EventWhenCarries
Event\ChallengeCreatedA challenge is created and its prize heldThe challenge, its creator
Event\MemberInvitedOnce for each friend invited, at the creationThe challenge, the member
Event\ParticipantJoinedA member takes partThe challenge, the member
Event\ProofSubmittedA participant submits a proofThe challenge, the proof, the participant
Event\ProofDecidedA proof is accepted, rejected or removedThe challenge, the proof, its state
Event\ChallengeWonA proof is accepted and the prize paidThe challenge, the winner, the proof, the prize, its unit
Event\ChallengeEndedA challenge is cancelled, expires or is removed, and its prize given backThe challenge, its state
Event\ChallengeFrozenA moderator freezes a challengeThe challenge
Event\ChallengeUnfrozenA moderator unfreezes a challengeThe challenge

The events carry identifiers only. A listener that notifies a member, pushes the page through Mercure or sends a Messenger message sends those identifiers, and reads the rest from the store.