227

Product support

Get help in the plugin support forum.

Categories

The plugin is a skeleton for building multi-tenant SaaS (Software as a Service) applications using OctoberCMS.

Here are some examples where Cumulus may help:

  • system for your clients' companies where they can have their private data in the cloud (your server) while other clients cannot see each other's data - like invoicing system, client management system, etc.
  • system for schools where classes can share some data and have access to some data while cannot see other classes data like exams system, school diary, etc.
  • every system that supports cutting functionality for different plans (like "Free", "Plus", "Pro", etc.)

Cumulus Subscriptions

Check out the latest version of Cumulus Subscriptions. It makes the Cumulus environment complete.

The following plugins are required
This plugin is also included into the following bundle
The following plugins extend or depend on the plugin
The following theme uses this plugin

Installation

You can install Cumulus in the following ways:

  1. from OctoberCMS Marketplace,
  2. clone the code from GitHub repo into /plugins/initbiz/cumuluscore directory,
  3. install using Composer composer require initbiz/oc-cumuluscore-plugin,

TL;DR

If you want to play with Cumulus right away (see the video below):

  1. install Cumulus theme
  2. run php artisan cumulus:seed command

After that, you are ready to play with a Cumulus based app with example data seeded (user demo@example.com with password demo) :). See Cumulus Demo documentation for more info about the command.

Cumulus demo video thumbnail

Terms explanation

Frontend user / User

Frontend users are managed by RainLab.User plugin. They can log in to your application and in most cases, they will be your clients' accounts. See RainLab.User documentation for more info about this.

By design, your clients' accounts have to have restricted access to the application functionality and data so that they do not see other clients' data (of course if you do not want to).

Backend user / Admin

Backend users / admins are developers or application owners. By design backend users have access to application panel and places like registered users, their subscriptions, invoices, usage stats and so on.

Cluster

Clusters are groups of users who share some data between them and can be described as one entity. The most common example is the company but it also applies to offices, office branches, classes in school, schools, etc.

You can understand clusters as tenants in multi-tenant architecture but remember that, in Cumulus, a user can have access to more than one cluster.

Clusters are not usergroups from RainLab.User plugin (like guest, registered and so on)

Clusters add one more abstraction layer between user roles and permissions in the application. This means you can give a cluster a part of the functionality in your system. In Cumulus we use features to do it.

Plan

Plans are used to organize sets of Cumulus features that are given to clusters. A cluster can have only one plan assigned at a time, but a lot of clusters can have the same plan.

The easiest way to get the idea is to imagine an example pricing table with plans like "Free", "Plus" and "Pro".

(Cumulus) Features

Cumulus Features (or just features) are parts of the whole functionality of our application. Access to them is given to clusters by assigning them to plans. Every plugin of yours can register its own features.

Example plan

Clusters' usernames

Clusters' usernames are unique strings to be used in URLs so that URLs can be changed by the client the way they want to. The same feature on Facebook and Twitter is called username so we decided to use the name username as well.

Using usernames has to be enabled in general Cumulus settings (using usernames in URLs). By default, Cumulus will use the cluster's slug.

Developer guide

Before you proceed, ensure you understand the terms explained before.

Preparing Cumulus pages

In Cumulus we specify four groups of pages that according to content we provide are:

  1. publicly visible, where we put our offer, regulations, contact form, login form, register form, etc.,
  2. pages for registered and logged in users, where they can manage their profiles, read messages, select cluster they want to enter, etc.,
  3. visible only to users assigned to cluster, like cluster's dashboard, cluster settings, etc.,
  4. visible only to clusters that have access to particular features

Accordingly, we will create the following pages:

  1. public pages such as login page and other public pages,
  2. pages that require the user to be logged in that have the Session component from RainLab.User embedded and configured,
  3. pages that require the user to be assigned to a particular cluster that have the CumulusGuard component embedded,
  4. pages that require the current cluster to have access to a particular feature that have the FeatureGuard component embedded and configured.

See the demo app to get the idea.

As a consequence, if you want to check if the user is:

  1. signed in,
  2. assigned to a cluster and
  3. the cluster has access to a feature

you have to embed all the components (Session, CumulusGuard and FeatureGuard) on one page (or its layout):

Feature guard

Registering Cumulus features

You can register Cumulus features using the registerCumulusFeatures method in your Plugin.php:

public function registerCumulusFeatures()
{
    return [
       'initbiz.cumulusinvoices.read_invoices' => [
           'name' => 'initbiz.cumulusinvoices::lang.feature.manage_invoices',
           'description' => 'initbiz.cumulusinvoices::lang.feature.manage_invoices_desc',
       ]
    ];
}

Preparing menu

If you want to build an application menu for your users, use Rainlab.Pages menu builder feature. Cumulus extends the plugin and adds it's own menu item type: Cumulus page.

If you select the type then the cluster's username or slug will be automatically injected in the URL.

What is more, you can select features that will be required to show the entry in the menu. Remember that only one feature is enough to show the menu (more like logical "or" than "and"). If no feature is selected then everybody will see the menu entry.

Static menu in Cumulus

Components

UserClustersList

The component is rendering a view for a user to select the cluster he/she wants to enter. If the user is assigned to only one cluster then the component will transparently redirect browser as it was clicked.

Clusters list component

CumulusGuard

The CumulusGuard component is checking if a logged-in user has access to the cluster that he/she tries to visit.

What is more, the component pushes the current cluster to the page object and sets active cluster's slug in session variable and cookie as cumulus_clusterslug.

FeatureGuard

The feature guard is checking if the current cluster can see the page based on features it has access to.

Remember that only one of the checked features is enough to let the user see the page

If you want to filter content on one page based on features, use canEnterFeature Twig function.

Feature guard

ClusterFiltrable trait

Filtering data by cluster

You can easily filter the data returned by the model using the ClusterFiltrable trait.

If you have cluster_id as a relation column for your model, you can easily filter the data by using clusterIdFiltered() method:

Invoices::clusterIdFiltered()->get();

If you have cluster_slug in your model as a relation column than you can alternatively use clusterFiltered() method:

Invoices::clusterFiltered()->get();

You can also customize the attribute and the column by specifying other parameters like:

ExampleModel::clusterFiltered($attributeValue, 'attribute_column')->get();

Cluster unique

If you want to check if a parameter is unique in the cluster scope (for example invoice number that can safely collide with other clusters but cannot be the same for one cluster) then you can use the clusterUnique method from the trait.

The method returns validation rule for October's validator which you can use in the model's constructor.

For example, to check if invoice_number is unique in the cluster scope we can use the following snippet:

public function __construct(array $attributes = array())
{
    parent::__construct($attributes);
    $this->rules['invoice_number'] = $this->clusterUnique('invoice_number');
}

If you want to customize the table name or column name to build a unique rule then you have to use parameters in the method. By default it will use $this->table attribute and cluster_slug as a column name, for example:

$this->rules['invoice_number'] = $this->clusterUnique('invoice_number', 'invoices', 'slug');

You can alternatively use the clusterIdUnique method if your data is to be filtered by the cluster's id.

Additional features

Auto assign

Auto assigning is a Cumulus function that automatically assigns users and clusters during their registration. Go to Settings -> Cumulus -> Auto-assign and you will find two tabs: "Auto-assign users" and "Auto-assign clusters".

Auto assign users

Auto assign users

While auto assigning users to clusters you can decide whether you want to:

  • create a new cluster using variable specified in "variable name (for example "Company name" from variable companyName),
  • choose existing cluster for every newly registered user,
  • get cluster slug from the variable (for example variable called companyName),

You can also decide whether you want to add a user to a group (RainLab.UserGroup) after registering or not.

Auto assign clusters

Auto assign clusters

While auto assigning clusters to plans you can decide if you want to:

  • assign the cluster to concrete plan (in most cases something like Free or Trial) or
  • get the plan from a variable (if you want to send the plan from registration form)

Remember:

  • auto assigning clusters will work only if creating a new cluster is enabled in "Auto-assign users" tab
  • auto assigning clusters to plans from variable will be possible only when you allow that in the plan

Registering cluster's features

Registering Cumulus features differs from registering cluster's features. Registering Cumulus features in the system is described here.

Every time a cluster obtains access to a feature (for the first time, once) we call it registering cluster's feature. Registering clusters' features is the process of running some 'registering' code when a cluster gets access to a feature whether by changes of the cluster's plan or plan's features.

To register a cluster's feature you have to bind to the initbiz.cumuluscore.registerClusterFeature event like that:

Event::listen('initbiz.cumuluscore.registerClusterFeature', function ($cluster, $featureCode) {
    if ($featureCode === "initbiz.cumulusinvoices.manage_invoices") {
        // perform some registering code, for example, seed tables for the cluster with sample data
    }
});

The event is blocking so if you decide to stop the process of registration then return false and an exception will be thrown.

Extend clusters' usernames unique rule

If you use the usernames feature then you have to ensure that they are unique.

The Helpers::usernameUnique method ensures that the username is unique in the cluster's table, but you can extend its logic by using the initbiz.cumuluscore.usernameUnique event.

Using the UpdateCluster component from Cumulus plus it will automatically check if the username is unique.

canEnterFeature() Twig function

If you want to check in views if the current cluster has access to a feature than use canEnterFeature('feature.code') Twig function.

For example:

{% if canEnterFeature('initbiz.cumulusdemo.paid_feature') %}
    Something visible only to those who have access to initbiz.cumulusdemo.paid_feature.
{% endif %}

You can also use canEnterAnyFeature if you want to check if the cluster has access to any of the supplied features in the array. What is more, the method accepts feature codes that end with the *.

Contributions / Issues

If you want to get in touch, write to contact@init.biz or directly to @tomaszstrojny on OctoberCMS's official Slack.

Every contribution is very welcomed, thank you for your time in advance.

Post your issues or pull requests via GitHub or Product support page.

  • Found the plugin useful on 19 Jun, 2019

    So many possibilities for creating an excellent subscription based SAAS application - quite brilliant!

  • author

    Replied on 19 Jun, 2019

    Thanks for the review :)

    More features and extensions for Cumulus are under development so stay tuned!

  • Found the plugin useful on 22 May, 2018

    Thank you for awesome plugin!

  • author

    Replied on 19 Jun, 2019

    Thank you for your review! :)

3.2.2

Small cluster model fix and add additional_data

Oct 30, 2019

3.2.1

Small fixes, preparing for new features

Oct 01, 2019

3.2.0

Deregistering cluster features

Sep 26, 2019

3.1.1

Bug fixes

Sep 23, 2019

3.1.0

Add timestamps, fix slugs and validation

Sep 14, 2019

3.0.3

Shorten primary name

Sep 12, 2019

3.0.2

Clean code

Sep 11, 2019

3.0.1

Fix the buggy migration

Sep 10, 2019

3.0.0

!!! Upgrade to v.3, check upgrade guide

Sep 10, 2019

2.3.0

Add related plans for downgrading and upgrading paths

Aug 29, 2019

2.2.0

Added allow user registration checkbox to plans

Jul 03, 2019

2.1.3

Fixed seeding after soft deletion

Mar 22, 2019

2.1.2

Fixed typo

Mar 22, 2019

2.1.1

Added softDelete trait for Plan Model

Mar 11, 2019

2.1.0

Added softDelete trait for Cluster Model

Mar 11, 2019

2.0.11

Fixed buggy migration

Feb 21, 2019

2.0.10

Now working with Cumulus Theme again

Feb 18, 2019

2.0.9

Fixed assigning clusters to empty plans

Feb 17, 2019

2.0.8

Cleaned translations and added Polish translation

Feb 12, 2019

2.0.7

Small fix of auto assigning

Feb 08, 2019

2.0.6

Small fix with registering cluster features

Dec 18, 2018

2.0.5

!!! Moved some helpers to Initbiz.InitDry plugin. Install the plugin if want to proceed.

Dec 13, 2018

2.0.4

Registration of clusters features support added

Dec 10, 2018

2.0.3

!!! Username for cluster added. Read the upgrade guide.

Nov 17, 2018

2.0.2

Better fix for the previous drop

Nov 09, 2018

2.0.1

Dropping foreign for MySQL fixed

Nov 09, 2018

2.0.0

!!! Before upgrading to 2.0.0 read the upgrade guide

Nov 08, 2018

1.3.13

Added helper getFileListToDropdown

Oct 09, 2018

1.3.12

User-cluster relation fixed

Oct 05, 2018

1.3.11

View fixes, translations and plan filter in cluster list

Oct 05, 2018

1.3.10

Cleaned registering and extending views

Sep 07, 2018

1.3.9

Added backend permissions to restrict access to controllers and settings.

Sep 07, 2018

1.3.8

Added empty cluster dashboard for better permissions managing

Sep 07, 2018

1.3.7

Fixed extending RainLab.User backend menu by other plugins

Sep 07, 2018

1.3.6

Removing cookie and session cluster_slug on logout + small fix

Sep 07, 2018

1.3.5

Added unique in cluster scope validation rule + minor fixes

Aug 17, 2018

1.3.4

Added handling transactions on user register

Jul 06, 2018

1.3.3

!!! Updated repository interface. Temporarily removed validation. Refactored cluster repository + minor fixes

Jun 27, 2018

1.3.2

Fixed typo

Jun 25, 2018

1.3.1

!!! Changed method getClusterModulesName to getClusterModulesSlugs + optimized cluster repo

Jun 19, 2018

1.3.0

!!! Removed cumulusDashboard and cumulusSettings components. They have been moved to CumulusPlus extension

Jun 19, 2018

1.2.2

Fixed recurrent dependencies in repositories

Jun 11, 2018

1.2.1

Set event listeners priorities

Jun 11, 2018

1.2.0

First Cumulus extension - Cumulus Announcements: octobercms.com/plugin/initbiz-cumulusannouncements

May 31, 2018

1.1.17

Created plan repo and added some useful methods to existing ones

May 30, 2018

1.1.16

Cleanup modules creating and listing them in settings

May 27, 2018

1.1.15

Updated table initbiz_cumuluscore_modules -> added nullable description column

May 27, 2018

1.1.14

Added ClusterFiltrable trait for models to easy filter their data using cluster_slug property

May 24, 2018

1.1.13

Funny part here. Both session and cookie should have been used. They are named cumulus_clusterslug :)

May 24, 2018

1.1.12

Changed the concept from session to cookie: cumulus_clusterslug

May 24, 2018

1.1.11

Put current cluster slug to Session with key: initbiz.cumuluscore.currentClusterSlug

May 23, 2018

1.1.10

Firing events: addClusterToPlan and addUserToCluster

May 18, 2018

1.1.9

Dropping foreign

Mar 16, 2018

1.1.8

Small organizational fixes

Mar 08, 2018

1.1.7

Fixed MySQL refreshing plugin

Jan 30, 2018

1.1.6

Fixed MySQL installation

Jan 30, 2018

1.1.5

Beautified cluster view in backend

Jan 26, 2018

1.1.4

Moved Cluster slug property from all components to CumulusComponentProperties trait

Jan 22, 2018

1.1.3

Changed texts to strings, extended cluster table

Jan 20, 2018

1.1.2

Fixed auto assigning with tests

Jan 17, 2018

1.1.1

Managing automatically adding users and clusters from settings view + cleanup and small fixes

Jan 16, 2018

1.1.0

Added unique at slug in Modules table

Jan 10, 2018

1.0.9

Added dynamic method onRedirectMe for building login pages

Jan 04, 2018

1.0.8

Fixed one to many relation between Plan and Cluster

Nov 09, 2017

1.0.7

After clean up, Cumulus is ready to be published on Marketplace

Oct 11, 2017

1.0.6

Created table initbiz_cumuluscore_plan_module

Oct 10, 2017

1.0.5

Created table initbiz_cumuluscore_plans

Oct 10, 2017

1.0.4

Created table initbiz_cumuluscore_modules

Oct 10, 2017

1.0.3

Created table initbiz_cumuluscore_cluster_user

Oct 10, 2017

1.0.2

Created table initbiz_cumuluscore_clusters

Oct 10, 2017

1.0.1

Initialize plugin.

Oct 10, 2017

Upgrade guide

from v.2. to v.3.

The repositories were moved to the models.

General:

  1. Ensure you have enabled Allow registration on plans that you automatically assign clusters to.
  2. prepareClusterSlug from ClusterFiltrable trait has changed to prepareClusterToFilter

Events:

  1. initbiz.cumuluscore.addClusterToPlan became initbiz.cumuluscore.autoAssignClusterToPlan and is run only on auto assigning cluster to plan
  2. initbiz.cumuluscore.addUserToCluster became initbiz.cumuluscore.autoAssignUserToCluster and is run only on auto assigning user to cluster
  3. initbiz.cumuluscore.beforeAutoAssignNewCluster is removed, instead use initbiz.cumuluscore.beforeAutoAssignClusterToPlan
  4. initbiz.cumuluscore.beforeAutoAssignUserToCluster and initbiz.cumuluscore.beforeAutoAssignClusterToPlan added
  5. registerClusterFeature(string $clusterSlug, string $feature) event now looks like that registerClusterFeature(Cluster $cluster, string $feature)
  6. initbiz.cumuluscore.beforeClusterSave was removed. Use typical model binding and bind to beforeSave instead.

Helpers:

  1. getCluster now returns Cluster object
  2. clusterId, clusterUsername, getClusterUsernameFromUrlParam and getClusterSlugFromUrlParam were removed, use getClusterFromUrlParam instead

All repositories:

  1. getByRelationPropertiesArray() -> $model->relation()->get() and foreach with unique()

UserRepository:

  1. getUserClusterList($userId) -> $user->clusters()->get()

PlanRepository:

  1. getPlansUsers($plansSlugs) -> $plan->users + foreach and unique().

ClusterRepository:

  1. getClustersUsers($clustersSlugs) -> $cluster->users()->get() + foreach and unique().
  2. getClustersPlans($clustersSlugs) -> $plans->push($cluster->plan()->first()) + foreach and unique().
  3. canEnterFeature($clusterSlug, $featureCode) -> $cluster->canEnterFeature($featureCode)
  4. getClusterFeatures($clusterSlug) -> $cluster->features
  5. usernameUnique($username, $clusterSlug) -> Helpers::usernameUnique($username, $clusterSlug
  6. addClusterToPlan($clusterSlug, $planSlug) -> $cluster->plan()->associate($plan)

ClusterFeatureLogRepository:

  1. clusterRegisteredFeatures(string $clusterSlug) -> $cluster->registered_features
  2. registerClusterFeature(string $clusterSlug, string $feature) -> $cluster->registerFeature(string $feature)
  3. registerClusterFeatures(string $clusterSlug, array $features) -> $cluster->registerFeatures(array $features)

Cluster Model:

  1. Relation clusterRegisteredFeatures renamed to featureLogs

from v.2.0.2 to v.2.0.3

Introducing Clusters' usernames

Clusters' usernames is a new feature of Cumulus, where your users can specify their "username" in URL. Click here for more info about the feature.

While installing this version Cumulus will by default copy Clusters' slugs to their usernames so by default usernames will be seeded and everything should work out of the box if you enable using usernames.

ClusterSlug becomes ClusterUniq

ClusterSlug property from Cumulus components becomes ClusterUniq. That is because it can be either a slug or a username. It depends on the setting in the General settings tab in Backend Settings.

The only thing you have to change is ClusterSlug to ClusterUniq in all the places you have been using it directly. Those places are:

  • layouts and pages in themes using Cumulus,
  • components that have been using the clusterSlug param,
  • external methods that used components' clusterSlug param.

As a consequence method defineClusterSlug becomes defineClusterUniq.

cluster and clusterData variables injected to the page by CumulusGuard have changed

the cluster variable so far has been actually cluster's slug. This was a misleading convention that had to be changed. Right now cluster is the object of the current cluster model, while the clusterData variable is removed.

from v.1.x.x to v.2.0.0

It is big. I know. It is funny in technology that after you create something it does not make sense after you work with it for some time. This is what happened to modules and some conventions we used in versions 1.x.x. Sorry about the number of changes, but we hope our plugin will be much better and usable after the upgrade.

Database changes

Make backup before proceeding.

At the beginning of Cumulus, we did not know some of October's and Laravel's conventions. While designing and developing Cumulus we used our own experience and ideas. During this time we get familiar with October's naming suggestions. As a consequence in version 2.0.0, we decided to change a few names.

Cluster full_name becomes name

Full_name from clusters table becomes name.

Primary keys in Cumulus

In version 1.x.x we were using cluster_id, module_id and plan_id as a primary keys. From now all of them will become id.

Drop modules

initbiz_cumuluscore_modules and initbiz_cumuluscore_plan_module tables will be dropped during upgrade to 2.0.0. Because of that, the relation between your plans and modules will be lost. You should create a backup of initbiz_cumuluscore_plan_modules and initbiz_cumuluscore_modules if you want to review them after the upgrade.

In most cases, it should be easy to restore them as modules were whole plugins. Only plans and their relations with modules have to be restored in feature convention.

Modules becomes features

The biggest change in Cumulus v.2 concerns modules. We noticed, that it was not enough for the plugin to register only one feature (since modules were actually features of the system). This led us to the plugin registration file, where now plugins can register as many features as they want to (more info in the documentation).

Methods from ClusterRepository that concerns modules will right now use features. It applies to almost every "module" word in methods and attributes names. What is more, modules used slugs while features use codes. So every time where we were talking about module slug, right now it is about feature code.

Modify modules

Before updating to v.2 you will have to ensure you register features as described in the documentation for all of your modules.

What is more, you have to remove the initial migration previously created by create:module command:

  1. remove file named register_initbiz_cumulus_module.php
  2. remove line running it in version.yaml file (at the beginning)
ModuleGuard becomes FeatureGuard

The responsibility of the ModuleGuard component was to ensure that the plan has access to the specified module and return 403 (Forbidden access) if it does not. The responsibility of FeatureGuard is the same but it checks if plan has access to any of the features specified in component configuration.

Access to only one feature is enough to enter the page.

Command create:module removed

As a consequence the command create:module is removed. If you want to create something similar then create a normal OctoberCMS plugin using create:plugin command and by adding registerCumulusFeatures method (details in documentation).

Settings model becomes AutoAssignSettings

If you have used the Settings model somewhere in your code then you will have to change its name to AutoAssignSettings.

Because of that, you will have to reconfigure auto-assign in settings or update initbiz_cumuluscore_settings row code to initbiz_cumuluscore_autoassignsettings in system_settings table.

Menu and MenuItem components removed

From version 2.0.0 we decided to use RainLab.Pages to build menus. It is a powerful, supported and extendable way to build menus.

Cumulus Plus users

If you are using the Cumulus Plus extension make sure you change permissions from module name to feature code in "permissions".