Package: reports

Source: api/packages/reports · imported version 0.1.49. The sections after the README are extracted from the code on every docs build.

README

Package for statistics & reports

Purpose

This package contains web API for retrieving statistical data about other LMS components (or event any arbitrary non-LMS Models for which Metrics and/or Reports are registered).

Installation

• composer require ulams/reports
• php artisan migrate
• php artisan db:seed --class="Ulams\Reports\Database\Seeders\ReportsPermissionSeeder"
• optional: php artisan vendor:publish --tag=reports to publish config file

Dependencies

• Ulams\Courses for all Courses related stats and metrics
• Ulams\Cart for all metrics related to calculating amounts of money spent

Usage

Configuration

By editing published config reports.php you can:

1. Change which metrics are available in API (by editing metrics)
2. Change settings for each Metric (by editing metric_configuration)
   1. limit defines how many data points will be calculated by default (if you don’t pass limit as query parameter); for example: TutorsPopularityMetric with limit set to 10 will return popularity of 10 most popular Tutors
   2. history is a boolean that defines if this metric should be automatically calculated and stored in database
   3. cron is cron config which determines how often automatic calculation of metrics happens
3. Change which stats are available in API (by editing stats) and to which Model they are mapped

Stats

Stats are used for calculating some statistical data about given single Model (for example Course or Topic). No historical data is stored, only current data is available.

Available stats

• Ulams\Reports\Stats\Course\AverageTime - average time spent on Course by users subscribed to it
• Ulams\Reports\Stats\Course\AverageTimePerTopic - average time spent on Course by users subscribed to it, grouped by topic
• Ulams\Reports\Stats\Course\MoneyEarned - sum of money earned by given Course
• Ulams\Reports\Stats\Course\PeopleBought - count of users that bought given Course
• Ulams\Reports\Stats\Course\PeopleFinished - count of how many users finished given Course
• Ulams\Reports\Stats\Course\PeopleStarted - count of how many users started learning given Course
• Ulams\Reports\Stats\Topic\AverageTime - average time spent on Topic by users subscribed to Course which this topic is part of

Creating your own stat

To create your own Stat, you need to create class implementing Ulams\Reports\Stats\StatContract. After creating a Stat you need to register it by adding it to stats array in config file.

Metrics

Metrics are used for reporting data accumulated over time. Historical data is stored for each day using scheduled job, and requesting a metric returns that historical data (that is, metric values stored at given date).

Available metrics

• Ulams\Reports\Metrics\CoursesMoneySpentMetric - calculates total money spent for every Course (historical data represents total money spent up to given date)
• Ulams\Reports\Metrics\CoursesPopularityMetric - calculates how many users were subscribed to every Course
• Ulams\Reports\Metrics\CoursesSecondsSpentMetric - calculates how much times users spent learning every Course
• Ulams\Reports\Metrics\TutorsPopularityMetric - calculates how many users were subscribed to courses created by given Tutor

Creating your own metric

To create your own Metric, you need to create class implementing Ulams\Reports\Metrics\Contracts\MetricContract. You can extend Ulams\Reports\Metrics\AbstractMetric to use default implementations of most of the methods declared in this interface. After creating a Metric you need to register it by adding it to metrics array in config file.

Endpoints

All the endpoints are defined in .

Metrics endpoints

1. GET /api/admin/reports/metrics returns list of metrics configured in reports.php config file
2. GET /api/admin/reports/report calculates data for chosen metric; you can pass following query parameters to this endpoint:
   1. metric={classname} is required; classname is one of the metrics returned in /api/admin/reports/metrics endpoit
   2. limit={int} is optional; determines the maximum number of data points that will be returned
   3. date={date} is optional; will try to load historical report data for given date or return 404 if there is no data available; without this param, endpoint will return today’s data

Stats endpoints

1. GET /api/admin/stats/available returns list of stats configured in reports.php config file
2. `GET /api/admin/stats/

Tests

Run ./vendor/bin/phpunit --filter='Ulams\\Reports\\Tests' to run tests.

Test details:

Events

No Events are defined in this package.

Listeners

No Listeners are defined in this package.

How to use this package on Frontend

Admin Panel

Reports dashboard

Course Stats

Permissions

Permissions are defined in Enum and seeded in Seeder.

Roadmap. Todo. Troubleshooting

• ???

More documentation in the package

• api/packages/reports/ADMIN.md
• api/packages/reports/docs/course.png
• api/packages/reports/docs/reports.png

API endpoints

Method	Path	Auth	Action
GET	/api/admin/reports/metrics	yes	ReportsController@metrics
GET	/api/admin/reports/report	yes	ReportsController@report
GET	/api/admin/reports/available-for-user	yes	ReportsController@availableForUser
GET	/api/admin/stats/available	yes	StatsController@available
GET	/api/admin/stats/course/{course_id}	yes	StatsController@course
GET	/api/admin/stats/course/{course_id}/export	yes	StatsController@courseExport
POST	/api/admin/stats/course/{course_id}/import	yes	StatsController@courseImport
GET	/api/admin/stats/cart	yes	StatsController@cart
GET	/api/admin/stats/date-range	yes	StatsController@dateRange
GET	/api/admin/stats/topic/{topic_id}	yes	StatsController@topic
GET	/api/admin/stats/topic/{topic_id}/export	yes	StatsController@topicExport

Permissions

Permission	Seeded for roles	Constant
report_list	admin	ReportsPermissionsEnum::DISPLAY_REPORTS

Settings

Registered with AdministrableConfig::registerConfig (editable in the admin panel under Configuration → Settings).

None.

Events

None.

Artisan commands

None.

Scheduled jobs

Kind	Target	Frequency
call	fn () => $this->calculateAndStore()	cron($this->cronExpression())

Environment variables read

None.