MembersActivities Framework 1.1.0

1. Scope and Architecture

MembersActivities Framework 1.1.0 is a reusable domain framework for applications managing members, activities, cost items, subscriptions, payments, tickets and ticket scanning. It is implemented as a Composer package and extends the Controller Framework.

The Composer package declares PHP ^8.3, samoscon/controller-framework ^1.0.31 and the Mollie API package. Mollie remains an optional application-level integration even though its package is available to the framework.

Version 1.1.0 extends the domain model with persistent tickets and ticket scans while retaining the existing Activity and Member hierarchical model.

2. Release 1.1.0 Technical Changes

Version 1.1.0 introduces the following principal technical changes compared with 1.0.31.

2.1 Ticket domain model

In version 1.0.31, the quantity of tickets was represented by the quantity property of a subscription. Version 1.1.0 introduces an individual persistent Ticket entity.

This allows individual tickets to have their own token, state, scan history and identity.

2.2 Ticket scanning

The new TicketScan model records an attempt to scan a ticket. The framework can distinguish valid, already-used, cancelled, invalid and wrong-activity results.

2.3 Seat reservation conflict detection

Seat availability is no longer only a property of the seat map displayed to the user. The server performs a final check against existing reservations when the subscription is submitted.

2.4 Google Wallet

Google Wallet integration now works from persistent ticket entities. Each ticket can therefore be represented independently in Google Wallet.

3. Package Structure

src/
├── commands/
│   ├── DefaultCommand.php
│   ├── admin/
│   │   ├── AddActivityToCompositeCommand.php
│   │   ├── AddMemberToCompositeCommand.php
│   │   ├── AdminHomeCommand.php
│   │   ├── CreateActivityCommand.php
│   │   ├── CreateCostitemCommand.php
│   │   ├── CreateMemberCommand.php
│   │   ├── DeleteActivityCommand.php
│   │   ├── DeleteCostitemCommand.php
│   │   ├── DeleteMemberCommand.php
│   │   ├── DeletePaymentCommand.php
│   │   ├── EditActivityCommand.php
│   │   ├── EditCostitemCommand.php
│   │   ├── EditMemberCommand.php
│   │   ├── EditPaymentCommand.php
│   │   ├── RemoveActivityFromCompositeCommand.php
│   │   ├── RemoveMemberFromCompositeCommand.php
│   │   └── SearchMembersCommand.php
│   ├── downloads/
│   │   ├── DownloadXlsMembersCommand.php
│   │   └── DownloadXlsParticipantsCommand.php
│   ├── mollie/
│   │   ├── OrderToMollieCommand.php
│   │   ├── PaymentToMollieCommand.php
│   │   └── WebhookFromMollieCommand.php
│   └── user/
│       ├── ActivityCommand.php
│       ├── CreatePaymentCommand.php
│       ├── PaymentConfirmationCommand.php
│       ├── PublicActivityCommand.php
│       └── UserActivityCommand.php
│
├── model/
│   ├── activities/
│   │   ├── Activity.php
│   │   ├── ActivityComposite.php
│   │   ├── ActivityMapper.php
│   │   ├── ActivityTypeImplementation.php
│   │   ├── Costitem.php
│   │   ├── CostitemMapper.php
│   │   └── CostitemTypeImplementation.php
│   ├── subscriptions/
│   │   ├── Payment.php
│   │   ├── PaymentMapper.php
│   │   ├── PaymentTypeImplementation.php
│   │   ├── Subscription.php
│   │   ├── SubscriptionMapper.php
│   │   ├── SubscriptionTypeImplementation.php
│   │   ├── SubscriptionValidationStrategy.php
│   │   ├── Ticket.php
│   │   ├── TicketMapper.php
│   │   ├── TicketScan.php
│   │   ├── TicketScanMapper.php
│   │   ├── TicketScanTypeImplementation.php
│   │   └── TicketTypeImplementation.php
│   └── wallet/
│       └── GoogleWalletTicket.php

The Member model remains supplied by the Controller Framework and is normally specialized by the client application.

4. Architectural Patterns

5. Object Model Overview

5.1 Domain relationships

5.2 Composite relationships

Both Activity and Member use a recursive parent-child relationship.

The important design principle is that the parent and child are instances of the same domain type. This allows client code to work with individual objects and composite objects through a consistent abstraction.

6. Activity Model

membersactivities\model\activities\Activity is an abstract domain object extending the Controller Framework's DomainObject.

Responsibilities

• Instantiate the concrete client activity class based on the database row.
• Attach an activity type implementation based on classification.
• Resolve a parent activity when parent_id is present.
• Return participants.
• Determine whether the subscription period is over.
• Calculate the total amount received for the activity.
• Support the Activity Composite hierarchy.

Public extension point

public ?ActivityTypeImplementation
    $activitytypeimplementation = null;

Important methods

6.1 ActivityComposite

ActivityComposite extends Activity and implements the Composite pattern.

Children are loaded through the Activity mapper. The composite therefore represents a parent Activity while retaining the same base domain type.

This permits an application to treat a single activity and a hierarchy of activities consistently where appropriate.

For a composite, subscriptionPeriodOver() evaluates the relevant child activities.

7. Member Model

Member is supplied by the Controller Framework and specialized by the client application, normally as:

class Member extends \controllerframework\members\Member
{
    // client-specific behaviour
}

7.1 Member Composite

MembersActivities Framework 1.1.0 explicitly uses the same Composite principle for members.

The reference schema supports member groups through parent_id. A Member can therefore act as a parent while one or more other Member objects refer to it as their parent.

The relationship is recursive. A child Member is itself a Member and can therefore have its own children where the application permits this.

This design allows client applications to represent structures such as households or other application-specific member hierarchies without introducing a separate object type for each hierarchy level.

7.2 Composite design principle

The Activity and Member models intentionally follow the same object-oriented principle:

In both cases the parent is not a different domain type. It is a domain object containing references to objects of the same type.

8. Costitem Model

Costitem represents a subscribable item belonging to an activity.

public ?CostitemTypeImplementation
    $costitemtypeimplementation = null;

During getInstance(), the framework:

1. creates the concrete client Costitem class;
2. initializes database properties;
3. creates the classification-specific type implementation;
4. loads the related Activity when activity_id is present.

9. Subscription Model

Subscription represents a registration by a member for a cost item.

public ?SubscriptionTypeImplementation
    $subscriptiontypeimplementation = null;

When instantiated, the framework resolves:

subscription.member
subscription.costitem
subscription.payment
subscriptiontypeimplementation

The payment relation is optional because a subscription can exist before payment has been associated with it.

9.1 Ticket relationship

In version 1.1.0 a subscription can have multiple persistent Ticket objects.

The historical quantity concept should therefore no longer be interpreted as the complete ticket identity model. Individual Ticket records provide the persistent identity of each ticket.

10. Payment Model

Payment represents a financial transaction and extends the Controller Framework's DomainObject.

public ?PaymentTypeImplementation
    $paymenttypeimplementation = null;

The transaction in Payment::delete() ensures that deletion of the payment and its associated subscriptions is committed atomically; an exception causes a rollback.

11. Ticket Model

membersactivities\model\subscriptions\Ticket is a persistent domain object representing an individual ticket.

11.1 Responsibilities

• Represent one individual ticket.
• Maintain a unique ticket token.
• Maintain ticket status.
• Track whether the ticket has been used.
• Record the time at which the ticket was used.
• Provide atomic claiming of a ticket.
• Participate in Google Wallet integration.

11.2 Ticket properties

11.3 Ticket lookup

Tickets are identified by a unique token when used by external clients such as a scanner.

$ticket = \model\Ticket::findByToken($token);

The token should be treated as untrusted input and must always be validated on the server.

11.4 Atomic ticket claim

The Ticket model provides an atomic claim operation:

$success = $ticket->claim();

The operation is successful only when the ticket is still valid and unused.

This protects the ticketing system against simultaneous scans from different devices.

11.5 Ticket type implementation

TicketTypeImplementation

The ticket classification determines the concrete ticket behaviour. The default classification is RGLR.

12. TicketScan Model

TicketScan represents an individual attempt to scan or validate a Ticket.

12.1 Responsibilities

• Record a ticket scan.
• Associate the scan with a Ticket.
• Identify the scanner.
• Record the scan timestamp.
• Record the result of the scan.

12.2 Scan result values

valid
already_used
cancelled
invalid
wrong_activity

The exact presentation of these values is a client application concern, but the server remains authoritative for determining the result.

12.3 TicketScan type implementation

TicketScanTypeImplementation

The default classification is RGLR. Client applications may provide specialized scan behaviour through their own type implementation.

13. Google Wallet Model

GoogleWalletTicket encapsulates Google Wallet integration.

13.1 Ticket-based Wallet objects

Version 1.1.0 creates Wallet objects from persistent Ticket records.

This replaces the previous model where ticket instances were derived directly from subscription quantity.

14. Mapper Layer

Version 1.1.0 contains the following domain mappers:

ActivityMapper
CostitemMapper
SubscriptionMapper
PaymentMapper
TicketMapper
TicketScanMapper

Each mapper extends the Controller Framework Mapper and defines an allowed-field whitelist. This is important when performing update/insert operations through the persistence layer.

14.1 TicketMapper

The TicketMapper provides ticket-specific persistence operations including token lookup and atomic ticket claiming.

findByToken(string $token): ?Ticket

claimTicket(int $ticketId): bool

The atomic claim operation must be implemented at database level so that concurrent scanners cannot both successfully change the same ticket from unused to used.

14.2 TicketScanMapper

The TicketScanMapper persists scan records associated with tickets.

TicketScan
    │
    └── ticket_id ───► Ticket

15. Command Layer

The framework commands are grouped by responsibility.

Ticket scanning may be exposed through client-specific commands or through framework commands depending on the client application's routing and scanner architecture.

Commands are intended to be connected to routes through the Controller Framework configuration, normally controls.xml.

16. Command Decorators

Client applications should use Controller Framework CommandDecorator whenever framework command logic can be reused.

This is especially important for validation strategies, payment descriptions and client-specific ticket or scanner behaviour.

17. Strategy and Type Implementations

17.1 Type implementations

ActivityTypeImplementation
CostitemTypeImplementation
PaymentTypeImplementation
SubscriptionTypeImplementation
TicketTypeImplementation
TicketScanTypeImplementation

The classification field determines the concrete implementation.

For example:

class Activity_RGLR
    extends \membersactivities\model\activities\ActivityTypeImplementation
{
    // default activity behaviour
}

class Activity_STMP
    extends \membersactivities\model\activities\ActivityTypeImplementation
{
    public function seatmap(): bool {
        return true;
    }
}

17.2 Ticket type

class Ticket_RGLR
    extends \membersactivities\model\subscriptions\TicketTypeImplementation
{
    // regular ticket behaviour
}

17.3 TicketScan type

class TicketScan_RGLR
    extends \membersactivities\model\subscriptions\TicketScanTypeImplementation
{
    // regular scanner behaviour
}

The client application should use type implementations when behaviour genuinely depends on classification rather than adding classification-specific branching throughout the generic framework.

18. Subscription Validation

SubscriptionValidationStrategy is the extension point for business rules determining whether a member may subscribe to a cost item.

public function subscribe(
    \controllerframework\members\Member $member,
    \membersactivities\model\activities\Costitem $subscribableitem,
    array $properties
): array

Client applications can implement different policies, for example:

SubscriptionValidationPublic
SubscriptionValidationUser
SubscriptionValidationAdmin

The concrete strategy should be supplied through controlled application code, normally a CommandDecorator. A request parameter must never be treated as a class name and instantiated dynamically.

19. Request / Response Flow

The Request object is also used as a controlled communication channel between decorators and wrapped commands. This mechanism is used, among other things, for application-specific validation strategies and Mollie order descriptions.

20. Security Architecture

20.1 Authentication

Authentication and login levels are supplied by the Controller Framework. Commands should explicitly define whether they require no login, a user login or administrator login.

20.2 CSRF

State-changing operations should use POST and validate the CSRF token before modifying data.

20.3 AccessToken

Controller Framework 1.0.31 supplies AccessToken. MembersActivities uses it for protected payment operations and version 1.1.0 also uses a dedicated token purpose for ticket scanning.

AccessToken::generate(
    'mollie-order',
    (string) $paymentId
);

AccessToken::generate(
    'ticket_scan',
    (string) $activityId
);

The _SALTRAND secret used by the AccessToken mechanism must remain confidential and must not be stored in public source code.

20.4 Ticket scanner security

The ticket scanning endpoint should validate the activity-specific ticket_scan token before processing ticket tokens.

20.5 Input validation

Request parameters are untrusted. Validate IDs, email addresses, file names, redirects, query parameters, ticket tokens and all other externally supplied values according to their intended type and context.

21. Payment and Mollie Flow

The critical trust boundary is the payment amount: the amount must be read from the server-side Payment object and not accepted from a browser-submitted amount.

The order description is intentionally different: the client-specific CommandDecorator can set orderDescription on the Request so that different order types can supply different descriptions without modifying the generic payment command.

22. Ticket Scanning Flow

22.1 Correctness requirements

The scanner must not consider a ticket valid merely because the token exists.

The server should verify:

1. the scanning AccessToken is valid;
2. the Ticket exists;
3. the Ticket belongs to the relevant activity;
4. the Ticket has a valid status;
5. the Ticket has not already been used;
6. the atomic claim operation succeeds.

The final atomic claim is the authoritative concurrency protection.

23. Seat Reservation Consistency

Applications using seat maps must consider the difference between displayed availability and actual database state.

The seat conflict check therefore belongs at the server-side subscription creation boundary rather than only in the JavaScript seat map.

Client-side seat maps improve usability, but they are not authoritative for reservation consistency.

24. Database Model

24.1 Relationship detail

24.2 Ticket schema

24.3 Ticket scan schema

24.4 Other 1.1.0 database changes

remember_tokens.expires_at is nullable.

The following mail_queue fields are nullable:

subject
body
recipient

The reference schema uses InnoDB, utf8mb4 and foreign key constraints. It is intended as a starting schema for a new client application rather than a production migration script.

25. Transactions and Consistency

Payment deletion is implemented transactionally: related subscriptions are deleted first, then the payment itself is deleted; an exception rolls the operation back.

25.1 Ticket claiming

Ticket claiming is a different form of consistency requirement. The important property is not a multi-statement business transaction but an atomic conditional state transition.

Conceptually:

UPDATE ticket
SET
    used = 1,
    used_at = CURRENT_TIMESTAMP
WHERE
    id = :ticket_id
    AND status = 'valid'
    AND used = 0;

The caller can determine whether the claim succeeded from the affected-row result.

This prevents two concurrent scanners from both receiving a successful claim for the same ticket.

25.2 Seat reservation consistency

Seat reservation validation must similarly be performed against current server-side database state immediately before the subscription is persisted.

For client-specific multi-step business operations, transactions should be considered whenever several related database changes must succeed or fail as one logical operation.

26. Mail Queue

The mail_queue table supports asynchronous mail processing.

A typical lifecycle is:

The queue records processing information such as attempts, creation/start/send timestamps and an error field.

Version 1.1.0 allows subject, body and recipient to be nullable, which permits the queue to represent records whose mail content is completed at a later processing stage.

A cron command can process pending messages and clean up old sent records.

27. Extension Guide

27.1 Add a new activity type

1. Create a client Activity subclass if not already present.
2. Create Activity_XXXX extending ActivityTypeImplementation.
3. Store XXXX in the activity classification field.
4. Add client logic only where the type needs special behaviour.

27.2 Add a new payment type

1. Create a client Payment subclass.
2. Create Payment_XXXX extending PaymentTypeImplementation.
3. Implement statusReceived() when payment status changes require client-specific processing.

27.3 Add a new ticket type

1. Create a client Ticket subclass if required.
2. Create Ticket_XXXX extending TicketTypeImplementation.
3. Store XXXX in the ticket classification field.
4. Implement only ticket-specific behaviour.

27.4 Add a new TicketScan type

1. Create a client TicketScan subclass if required.
2. Create TicketScan_XXXX extending TicketScanTypeImplementation.
3. Store XXXX in the scan classification field.
4. Implement scanner-specific behaviour.

27.5 Implement a Member hierarchy

Member hierarchy support is based on the existing parent_id self-reference.

Parent Member
     │
     ├── Child Member
     └── Child Member

Client-specific code should treat the relationship as a domain hierarchy rather than introducing a separate "MemberGroup" object unless the application's business requirements genuinely require one.

27.6 Add client-specific subscription validation

1. Create a class extending SubscriptionValidationStrategy.
2. Implement the application-specific validation rules.
3. Inject the strategy through a controlled CommandDecorator.

27.7 Add a new command around an existing command

1. Create a client CommandDecorator.
2. Set the wrapped framework command in initCommand().
3. Use doExecuteDecorator() for client-specific preparation.
4. Define the required authentication level.
5. Register the route in controls.xml.

28. Migration from 1.0.31

Version 1.1.0 introduces new persistent domain entities and therefore requires more than a Composer version change for applications using the new functionality.

28.1 Composer

{
    "require": {
        "samoscon/membersactivities-framework": "^1.1.0"
    }
}

The Controller Framework remains at version 1.0.31.

28.2 Database migration

Applications should apply controlled database changes for:

• ticket;
• ticket_scan;
• nullable remember_tokens.expires_at;
• nullable mail queue fields.

28.3 Existing subscriptions

In version 1.0.31, multiple tickets could be represented by a subscription's quantity. Version 1.1.0 introduces individual Ticket records.

Applications using the ticket functionality should migrate existing relevant subscriptions to individual Ticket records.

The migration must generate unique ticket tokens and preserve any client-specific ticket information.

28.4 Google Wallet migration

Applications using Google Wallet should ensure that the required Ticket records exist before using the 1.1.0 Wallet implementation.

28.5 Ticket scanner migration

Applications introducing ticket scanning should implement:

• activity-specific ticket_scan AccessToken generation;
• server-side ticket-token lookup;
• activity verification;
• atomic ticket claiming;
• scan-result persistence where required.

29. API / Class Reference

30. Technical Review Checklist

• MembersActivities Framework version is 1.1.0.
• Controller Framework version is 1.0.31.
• PHP version satisfies the package requirement.
• PDO MySQL/MariaDB is configured correctly.
• Client model classes extend the appropriate framework classes.
• Classification values map to existing client type implementations.
• Activity parent-child relationships are handled correctly.
• Member parent-child relationships are handled correctly.
• Client-specific rules are implemented through strategies/decorators where appropriate.
• No validator or other class name is instantiated from untrusted request input.
• State-changing operations use POST and CSRF validation.
• Administrative commands have the correct authentication level.
• AccessToken secrets are protected.
• Payment amounts are obtained from server-side Payment objects.
• Mollie webhooks retrieve authoritative payment state from Mollie.
• Free SQL clauses never contain untrusted input.
• Redirects and HTTP header values are validated.
• Exceptions are centrally handled and not exposed as stack traces.
• Multi-step database operations use transactions where atomicity is required.
• Ticket records are created for subscriptions where ticket functionality is required.
• Ticket tokens are unique and treated as untrusted external input.
• Ticket scanning validates the activity-specific AccessToken.
• Ticket scanning verifies that the Ticket belongs to the relevant Activity.
• Ticket claiming is atomic.
• Already-used tickets are rejected.
• Cancelled tickets are rejected.
• Ticket scan results are recorded where an audit trail is required.
• Seat reservations are checked against current server-side state.
• Google Wallet objects are generated from actual Ticket records.
• Mail queue processing is configured and monitored.
• Google Wallet credentials are protected if the integration is enabled.
• Existing production data is migrated through controlled database changes rather than replacing the database with the reference schema.