# Installation Instructions

## Requirements

- **Drupal:** 10.2+ or 11.x
- **PHP:** 8.2+
- **Dependencies:** `drupal:user` (included in Drupal core)

Optional integrations (no hard dependency):

- Drupal Commerce — trigger `assign()` from order workflows
- ECA / Rules — subscribe to lifecycle events
- Views — filter and display membership data

---

## Installation

### 1. Install via Composer

```bash
composer require drupal/membership_manager
```

This adds the module to `web/modules/contrib/membership_manager/` and updates `composer.lock`.

### 2. Enable the module

```bash
drush en membership_manager -y
```

Enabling the module performs the following:

- Registers the `membership` content entity type (database storage).
- Registers the `membership_plan` config entity type.
- Installs default configuration from `config/install/membership_manager.settings.yml`.
- Registers the `membership_expiry` queue worker.
- Registers the `_membership_active` route access checker.
- Creates permissions: `administer memberships`, `view own membership`, `create memberships`, `delete memberships`.

### 3. Clear the cache

```bash
drush cr
```

### 4. Configure global settings (optional)

Visit **/admin/config/membership/settings** to adjust:

| Setting | Default | Description |
|---|---|---|
| Cron enabled | Enabled | Controls whether cron processes expired memberships. |
| Batch size | 200 | Maximum expired memberships enqueued per cron run. Set to `0` for unlimited. |
| Role synchronisation | Enabled | Master toggle for role grant/revoke on membership changes. |
| Lifecycle events | Enabled | Master toggle for event dispatching. |

All settings are enabled by default. Disable them only if you have a specific reason.

### 5. Create Drupal roles (if using role synchronisation)

If your membership plans will sync Drupal roles, create the roles first:

1. Go to **/admin/people/roles**.
2. Add a new role (e.g. `member`, `premium`, `subscriber`).
3. Note the role's machine name — you'll reference it in the membership plan.

The module does not create roles automatically. It grants and revokes existing roles.

### 6. Create a membership plan

1. Go to **/admin/membership/plans/add**.
2. Fill in the plan details:

   - **Machine name:** Unique ID used in code (e.g. `pro_monthly`).
   - **Label:** Human-readable name (e.g. "Pro Monthly").
   - **Plan type:** `free`, `paid`, or `trial` (informational only).
   - **Duration:** Numeric value + unit (e.g. `30` + `day`). Set to `0` for unlimited.
   - **Renewal mode:** `manual`, `automatic`, or `none`.
   - **Max memberships:** Cap on concurrent active memberships. Set to `0` for unlimited.
   - **Grace period:** Days after expiry before access is fully revoked.
   - **Feature keys:** Entitlement keys (one per line) checked via `userHasFeature()`.
   - **Initial status:** Status on assignment: `active`, `pending`, or `trial`.
   - **Sync Drupal role:** Role machine name (e.g. `member`) to grant on activation.
   - **Dispatch lifecycle events:** Enable to send events on lifecycle changes.

3. Save the plan.

### 7. Export configuration (recommended)

```bash
drush config:export
```

This exports the membership plan and global settings to `config/sync/` for deployment across environments.

---

## Verification

After installation, verify the module is working:

### Check the module is enabled

```bash
drush pm:list --status=enabled --filter=membership_manager
```

Expected output:

```
Membership Manager  | enabled | 1.x
```

### Check the routes are available

```bash
drush route:list --name=membership_manager
```

Expected routes:

- `membership_manager.membership.add` — /admin/membership/memberships/add
- `membership_manager.membership.list` — /admin/membership/memberships
- `membership_manager.plan.add` — /admin/membership/plans/add
- `membership_manager.plan.list` — /admin/membership/plans
- `membership_manager.settings` — /admin/config/membership/settings

### Check the queue worker is registered

```bash
drush queue:list --name=membership_expiry
```

Expected output:

```
membership_expiry  | 0 items
```

### Test a membership assignment

```php
// In drush php:eval or a custom script:
$user = \Drupal\user\Entity\User::load(1);
$plan_id = 'pro_monthly'; // your plan machine name
$service = \Drupal::service('membership_manager.manager');
$membership = $service->assign($user, $plan_id);
echo "Membership created: " . $membership->id() . "\n";
```

---

## Uninstallation

To remove the module:

```bash
drush pmu membership_manager -y
composer remove drupal/membership_manager
drush cr
```

This will:

- Delete all `membership` content entities.
- Delete all `membership_plan` config entities.
- Remove the `membership_manager.settings` configuration.
- Remove the module files from `web/modules/contrib/`.

**Warning:** Uninstalling deletes all membership data. Export your data before uninstalling if you need to preserve it.

---

## Troubleshooting

### "The membership plan could not be found"

Ensure the plan machine name matches exactly. Plan IDs are case-sensitive.

### Role not granted after activation

1. Verify the role exists at `/admin/people/roles`.
2. Check that `role_sync_enabled` is enabled at `/admin/config/membership/settings`.
3. Confirm the plan has the correct role machine name in "Sync Drupal role".

### Events not firing

1. Check that `events_enabled` is enabled at `/admin/config/membership/settings`.
2. Confirm the plan has "Dispatch lifecycle events" enabled.
3. Both conditions must be TRUE for events to fire.

### Cron not processing expired memberships

1. Verify `cron_enabled` is enabled at `/admin/config/membership/settings`.
2. Run `drush cron` and check the watchdog logs for membership_manager messages.
3. To process immediately: `drush queue:run membership_expiry`.
