st
staging
Engineering guide Plans & features

Adding a new license feature

Ship a capability that is gated by subscription plan: register it in the addins database, enforce it in PHP, then wire plans in ST-admin.

CodeFeature constant
DBfeatures
DBplan_features
RuntimeFeatureChecker

Checklist

1

Define the feature constant

Add a unique name on the PHP Feature model. The string must match the row you insert in addins.features.

api/common/modules/featurechecker/models/Feature.php

2

Add a Yii migration

Create a migration that extends FeatureMigration so the feature row is inserted into addins.

api/console/migrations/

3

Link plans (optional migration)

Assign plan_features for existing plans via a second migration, or use ST-admin on draft plans only.

api/console/migrations/ or Plans & features

4

Run migrations

Apply changes to the addins database (local stack or api container).

scripts/migrate.sh or cd api && php yii migrate

5

Enforce in application code

Gate API and UI with FeatureChecker so only accounts on plans that include the feature can use it.

api / dashboard controllers

6

Verify in ST-admin

Open Plans & features: new row in the matrix, toggle on draft plans, Go live when ready to sell.

/plans-features

Code examples

1. Feature constant

api/common/modules/featurechecker/models/Feature.php
// In Feature.php
const FEATURE_MY_NEW_CAPABILITY = 'MY_NEW_CAPABILITY';

2. Migration

Extend FeatureMigration; it inserts into {{features}} if the name is not already present.

api/console/migrations/m260520_120000_add_my_feature.php
<?php

use console\models\FeatureMigration;
use common\modules\featurechecker\models\Feature;

class m260520_120000_add_my_feature extends FeatureMigration
{
    protected function getFeatureNames()
    {
        return Feature::FEATURE_MY_NEW_CAPABILITY;
    }
}

3. Enforce access

Typical API controller check
use common\modules\featurechecker\FeatureCheckerModule;
use common\modules\featurechecker\models\Feature;

$allowed = FeatureCheckerModule::getFeatureChecker()
    ->can(Feature::FEATURE_MY_NEW_CAPABILITY);
if (!$allowed) {
    throw new ForbiddenHttpException('Not available on your plan');
}

ST-admin workflow

Draft

Edit the matrix

Click cells to toggle plan_features. Use New draft plan to experiment without touching live plans.

Active

Go live / Activate

Makes the plan purchasable. Feature links you set on the draft are kept.

Legacy

Deactivate

Stops new sales. Existing subscribers keep their plan; matrix is read-only for feature links.

Open Plans & features

Troubleshooting

  • Feature missing in matrix — migration not applied to addins, or typo in features.name.
  • Cell click does nothing — plan is not a draft (isDraft=1).
  • User still has access — check account plan assignment and every FeatureChecker::can() call site (editor may use API only).
  • Draft plans need migration — ensure m260519_100000_add_is_draft_to_plans ran on addins.

Reference paths

PHP modelapi/common/modules/featurechecker/models/Feature.phpMigration baseapi/console/models/FeatureMigration.phpExamplem230504_074914_add_export_to_powerpoint_feature.phpST-admin APIGET /api/plan-features · PUT draft plan features

Also see st-admin/README.md for local ports, auth, and draft-plan behaviour.