diff --git a/app/Console/Commands/SpeedtestCommand.php b/app/Console/Commands/SpeedtestCommand.php index d0015d73..e0aaea56 100644 --- a/app/Console/Commands/SpeedtestCommand.php +++ b/app/Console/Commands/SpeedtestCommand.php @@ -32,9 +32,9 @@ class SpeedtestCommand extends Command } /** - * Execute the console command. + * Runs a speedtest synchroonously and displays the results.. * - * @return mixed + * @return null */ public function handle() { diff --git a/app/Console/Commands/SpeedtestLatestCommand.php b/app/Console/Commands/SpeedtestLatestCommand.php index 0f3b2587..c96eacc6 100644 --- a/app/Console/Commands/SpeedtestLatestCommand.php +++ b/app/Console/Commands/SpeedtestLatestCommand.php @@ -33,9 +33,9 @@ class SpeedtestLatestCommand extends Command } /** - * Execute the console command. + * Prints the latest speedtest values. * - * @return mixed + * @return null */ public function handle() { diff --git a/app/Helpers/BackupHelper.php b/app/Helpers/BackupHelper.php index b62beaee..49708421 100644 --- a/app/Helpers/BackupHelper.php +++ b/app/Helpers/BackupHelper.php @@ -9,7 +9,14 @@ use Illuminate\Support\Facades\Log; use Illuminate\Support\Facades\Storage; class BackupHelper { - public static function backup($format = 'json') + + /** + * Generates a backup of all speedtests. + * + * @param string $format json|csv + * @return string $name Returns the filename of the backup. + */ + public static function backup(String $format = 'json') { $timestamp = new DateTime(); $timestamp = $timestamp->format('Y-m-d_H:i:s'); @@ -43,6 +50,13 @@ class BackupHelper { return $name; } + /** + * Restore data from a backup in CSV or JSON format + * + * @param array|string $array Backup data + * @param string $format json|csv + * @return boolean + */ public static function restore($array, $format) { if($format == 'json') { diff --git a/app/Helpers/SettingsHelper.php b/app/Helpers/SettingsHelper.php index ad79d859..3c3df623 100644 --- a/app/Helpers/SettingsHelper.php +++ b/app/Helpers/SettingsHelper.php @@ -5,6 +5,13 @@ namespace App\Helpers; use App\Setting; class SettingsHelper { + + /** + * Get a Setting object by name + * + * @param String $name The name field in the setting table + * @return \App\Setting|boolean $name The Setting object. Returns false if no mathcing obj. + */ public static function get(String $name) { $name = Setting::where('name', $name)->get(); @@ -19,6 +26,13 @@ class SettingsHelper { } } + /** + * Create / update value for Setting object. + * + * @param String $name Name of setting + * @param String $value Value of setting + * @return \App\Setting + */ public static function set(String $name, String $value) { $setting = SettingsHelper::get($name); @@ -36,6 +50,11 @@ class SettingsHelper { return $setting; } + /** + * Get the app's base path + * + * @return string + */ public static function getBase() { $base = env('BASE_PATH', '/'); diff --git a/app/Helpers/SpeedtestHelper.php b/app/Helpers/SpeedtestHelper.php index 5a1f18a2..0697148b 100644 --- a/app/Helpers/SpeedtestHelper.php +++ b/app/Helpers/SpeedtestHelper.php @@ -13,6 +13,13 @@ use JsonException; use SimpleXMLElement; class SpeedtestHelper { + + /** + * Runs/processes speedtest output to created a Speedtest object + * + * @param boolean|string $output If false, new speedtest runs. If anything else, will try to parse as JSON for speedtest results. + * @return \App\Speedtest|boolean + */ public static function runSpeedtest($output = false) { if($output === false) { @@ -36,6 +43,11 @@ class SpeedtestHelper { return (isset($test)) ? $test : false; } + /** + * Gets the output of executing speedtest binary. + * + * @return boolean|string + */ public static function output() { $server = SettingsHelper::get('server')['value']; @@ -54,10 +66,21 @@ class SpeedtestHelper { return shell_exec($binPath . ' -f json'); } + /** + * Converts bytes/s to Mbps + * + * @param int|float $bytes + * @return int|float + */ public static function convert($bytes) { return ( $bytes * 8 ) / 1000000; } + /** + * Returns the latest speedtest object. + * + * @return boolean|\App\Speedtest + */ public static function latest() { $data = Speedtest::latest()->get(); @@ -69,6 +92,12 @@ class SpeedtestHelper { return $data->first(); } + /** + * Parses network speeds and return converted to Mbps + * + * @param array $input + * @return array + */ public static function parseUnits($input) { $input = explode(' ', $input); diff --git a/app/Helpers/UpdateHelper.php b/app/Helpers/UpdateHelper.php index 1a39b23d..d14cc551 100644 --- a/app/Helpers/UpdateHelper.php +++ b/app/Helpers/UpdateHelper.php @@ -10,10 +10,39 @@ use RecursiveIteratorIterator; use ZipArchive; class UpdateHelper { + /** + * URL of updates + * + * @var string + */ public $url; + + /** + * Current app version number + * + * @var string + */ public $currentVersion; + + /** + * Username of GitHub repo + * + * @var string + */ public $user; + + /** + * Name of GitHub repo + * + * @var string + */ public $repo; + + /** + * Branch of GitHub repo + * + * @var string + */ public $branch; function __construct() { @@ -25,6 +54,11 @@ class UpdateHelper { $this->download = null; } + /** + * Returns data on new version available + * + * @return boolean|array false|[ version, changelog ] + */ public function check() { Log::info('Checking for new version'); @@ -50,6 +84,11 @@ class UpdateHelper { } } + /** + * Gets the latest version number from GitHub + * + * @return array [ repo, branch, version ] + */ public function checkLatestVersion() { $url = 'https://raw.githubusercontent.com/' @@ -78,6 +117,11 @@ class UpdateHelper { ]; } + /** + * Gets the latest changelog from GitHub + * + * @return array + */ public function getChangelog() { $url = 'https://raw.githubusercontent.com/' @@ -97,6 +141,11 @@ class UpdateHelper { return $changelog; } + /** + * Downloads the latest version from GitHub + * + * @return boolean|Exception + */ public function downloadLatest() { Log::info('Downloading the latest version from GitHub'); @@ -121,6 +170,11 @@ class UpdateHelper { } } + /** + * Extracts zip archive from update + * + * @return boolean + */ public function extractFiles() { Log::info('Extracting the update'); @@ -137,6 +191,11 @@ class UpdateHelper { } } + /** + * Replace existing files with newly downloaded files + * + * @return void + */ public function updateFiles() { Log::info('Applying update'); @@ -151,6 +210,14 @@ class UpdateHelper { Log::info('Successfully applied update'); } + /** + * Deletes default templates from updated files. + * This is for things like .env so that user specified files are not + * overwritten. + * + * @param string $path + * @return void + */ private function deleteExcluded($path) { Log::info('Deleting excluded items from update directory'); @@ -172,6 +239,11 @@ class UpdateHelper { Log::info('Excluded items deleted from update directory'); } + /** + * Creates a ZIP backup of current installation + * + * @return void + */ private function backupCurrent() { Log::info('Backing up current installation'); @@ -209,6 +281,11 @@ class UpdateHelper { Log::info('Backup created at: ' . $backupZip); } + /** + * Move updated files into server dir. + * + * @return void + */ private function moveFiles() { $new = array_filter(glob('/tmp/'.$this->repo.'-update/*'), 'is_dir'); @@ -242,6 +319,11 @@ class UpdateHelper { } + /** + * Make a copy of excluded, user customised files + * + * @return void + */ private function tempStoreExcludedFiles() { Log::info('Temporarily moving exluded files from root directory'); @@ -263,6 +345,11 @@ class UpdateHelper { } } + /** + * Restore user cusotmised files from the copy + * + * @return void + */ private function restoreExcludedFiles() { Log::info('Restoring exluded files to root directory'); @@ -284,6 +371,11 @@ class UpdateHelper { } } + /** + * Delete update files from download dir. + * + * @return void + */ private function clearup() { try { diff --git a/app/Http/Controllers/BackupController.php b/app/Http/Controllers/BackupController.php index 634a6c80..0354151e 100644 --- a/app/Http/Controllers/BackupController.php +++ b/app/Http/Controllers/BackupController.php @@ -10,6 +10,13 @@ use Illuminate\Support\Facades\Validator; class BackupController extends Controller { + + /** + * Get backup of speedtests + * + * @param Request $request + * @return file + */ public function backup(Request $request) { $validator = Validator::make($request->all(), [ 'format' => 'in:json,csv' ]); @@ -25,6 +32,12 @@ class BackupController extends Controller return Storage::disk('local')->download($filename); } + /** + * Retore from a backup + * + * @param Request $request + * @return Response + */ public function restore(Request $request) { $rule = [ diff --git a/app/Http/Controllers/SettingsController.php b/app/Http/Controllers/SettingsController.php index 5c010eae..b6bb4234 100644 --- a/app/Http/Controllers/SettingsController.php +++ b/app/Http/Controllers/SettingsController.php @@ -10,16 +10,34 @@ use Illuminate\Support\Facades\Validator; class SettingsController extends Controller { + + /** + * Return all settings + * + * @return array + */ public function index() { return Setting::get()->keyBy('name'); } + /** + * Get setting by id + * + * @param Setting $setting + * @return Setting + */ public function get(Setting $setting) { return $setting; } + /** + * Store/update a setting + * + * @param Request $request + * @return Response + */ public function store(Request $request) { $rule = [ @@ -49,6 +67,11 @@ class SettingsController extends Controller ], 200); } + /** + * Returns instance config + * + * @return array + */ public function config() { diff --git a/app/Http/Controllers/SpeedtestController.php b/app/Http/Controllers/SpeedtestController.php index e63f782e..41bab815 100644 --- a/app/Http/Controllers/SpeedtestController.php +++ b/app/Http/Controllers/SpeedtestController.php @@ -13,6 +13,12 @@ use Illuminate\Support\Facades\Validator; class SpeedtestController extends Controller { + + /** + * Returns paginated list of speedtests + * + * @return Response + */ public function index() { $data = Speedtest::orderBy('created_at', 'desc') @@ -24,6 +30,12 @@ class SpeedtestController extends Controller ], 200); } + /** + * Returns speedtest going back 'x' days + * + * @param int $days + * @return void + */ public function time($days) { $rule = [ @@ -50,6 +62,11 @@ class SpeedtestController extends Controller ], 200); } + /** + * Return latest speedtest + * + * @return Response + */ public function latest() { $data = SpeedtestHelper::latest(); @@ -73,6 +90,11 @@ class SpeedtestController extends Controller } } + /** + * Queue a new speedtest + * + * @return Response + */ public function run() { try { diff --git a/app/Http/Controllers/UpdateController.php b/app/Http/Controllers/UpdateController.php index b5c6ad4f..ed8bbe31 100644 --- a/app/Http/Controllers/UpdateController.php +++ b/app/Http/Controllers/UpdateController.php @@ -8,6 +8,12 @@ use Illuminate\Http\Request; class UpdateController extends Controller { + + /** + * Check for new update + * + * @return Response + */ public function checkForUpdate() { return response()->json([ @@ -16,6 +22,11 @@ class UpdateController extends Controller ], 200); } + /** + * Download new update + * + * @return Response + */ public function downloadUpdate() { $dl = Updater::downloadLatest(); @@ -33,6 +44,11 @@ class UpdateController extends Controller } } + /** + * Trigger update extraction + * + * @return Response + */ public function extractUpdate() { $ex = Updater::extractFiles(); @@ -50,6 +66,11 @@ class UpdateController extends Controller } } + /** + * Trigger update file move + * + * @return Response + */ public function moveUpdate() { $cp = Updater::updateFiles(); @@ -60,6 +81,11 @@ class UpdateController extends Controller ], 200); } + /** + * Get local changelog + * + * @return Response + */ public function changelog() { $url = base_path() . '/changelog.json'; diff --git a/app/Jobs/SpeedtestJob.php b/app/Jobs/SpeedtestJob.php index 0682f61b..ecae55ef 100644 --- a/app/Jobs/SpeedtestJob.php +++ b/app/Jobs/SpeedtestJob.php @@ -25,9 +25,9 @@ class SpeedtestJob implements ShouldQueue } /** - * Execute the job. + * Runs a speedtest * - * @return void + * @return \App\Speedtest */ public function handle() { diff --git a/app/Listeners/SpeedtestCompleteListener.php b/app/Listeners/SpeedtestCompleteListener.php index fe7a1728..6155c4b0 100644 --- a/app/Listeners/SpeedtestCompleteListener.php +++ b/app/Listeners/SpeedtestCompleteListener.php @@ -22,7 +22,7 @@ class SpeedtestCompleteListener } /** - * Handle the event. + * Handle what to do after speedtest completes * * @param object $event * @return void diff --git a/app/Notifications/SpeedtestComplete.php b/app/Notifications/SpeedtestComplete.php index 4771d35e..a4e542b9 100644 --- a/app/Notifications/SpeedtestComplete.php +++ b/app/Notifications/SpeedtestComplete.php @@ -34,6 +34,12 @@ class SpeedtestComplete extends Notification return ['slack']; } + /** + * Format slack notification + * + * @param mixed $notifiable + * @return SlackMessage + */ public function toSlack($notifiable) { $speedtest = $this->speedtest; diff --git a/app/Rules/Cron.php b/app/Rules/Cron.php index 6de599aa..f7547a57 100644 --- a/app/Rules/Cron.php +++ b/app/Rules/Cron.php @@ -18,7 +18,7 @@ class Cron implements Rule } /** - * Determine if the validation rule passes. + * Determine if the value is a valid CRON expression * * @param string $attribute * @param mixed $value diff --git a/app/User.php b/app/User.php index ee0e14cc..c9ad0f1c 100644 --- a/app/User.php +++ b/app/User.php @@ -75,6 +75,11 @@ class User extends Authenticatable implements JWTSubject return $this->hasOne('\App\Auth\EmailVerification'); } + /** + * Returns a user's login sessions + * + * @return array + */ public function sessions() { return $this->hasMany('\App\Auth\LoginSession');