Merge pull request #471 from beyondcode/refactor/docblocks

[2.x] Docblocks

Author: rennokki

docs/advanced-usage/app-providers.md

@@ -25,10 +25,10 @@ interface AppManager
     public function findById($appId): ?App;
 
     /**  @return BeyondCode\LaravelWebSockets\Apps\App */
-    public function findByKey(string $appKey): ?App;
+    public function findByKey($appKey): ?App;
 
     /**  @return BeyondCode\LaravelWebSockets\Apps\App */
-    public function findBySecret(string $appSecret): ?App;
+    public function findBySecret($appSecret): ?App;
 }
 ```
 
@@ -56,12 +56,12 @@ class MyCustomAppManager implements AppManager
         return $this->normalize(Application::findById($appId)->toArray());
     }
 
-    public function findByKey(string $appKey) : ? App
+    public function findByKey($appKey) : ? App
     {
         return $this->normalize(Application::findByKey($appKey)->toArray());
     }
 
-    public function findBySecret(string $appSecret) : ? App
+    public function findBySecret($appSecret) : ? App
     {
         return $this->normalize(Application::findBySecret($appSecret)->toArray());
     }

src/Apps/App.php

@@ -36,22 +36,49 @@ class App
     /** @var array */
     public $allowedOrigins = [];
 
+    /**
+     * Find the app by id.
+     *
+     * @param  mixed  $appId
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
     public static function findById($appId)
     {
         return app(AppManager::class)->findById($appId);
     }
 
-    public static function findByKey(string $appKey): ?self
+    /**
+     * Find the app by app key.
+     *
+     * @param  mixed  $appId
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
+    public static function findByKey($appKey): ?self
     {
         return app(AppManager::class)->findByKey($appKey);
     }
 
-    public static function findBySecret(string $appSecret): ?self
+    /**
+     * Find the app by app secret.
+     *
+     * @param  mixed  $appId
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
+    public static function findBySecret($appSecret): ?self
     {
         return app(AppManager::class)->findBySecret($appSecret);
     }
 
-    public function __construct($appId, string $appKey, string $appSecret)
+    /**
+     * Initialize the Web Socket app instance.
+     *
+     * @param  mixed  $appId
+     * @param  mixed  $key
+     * @param  mixed  $secret
+     * @return void
+     * @throws \BeyondCode\LaravelWebSockets\Exceptions\InvalidApp
+     */
+    public function __construct($appId, $appKey, $appSecret)
     {
         if ($appKey === '') {
             throw InvalidApp::valueIsRequired('appKey', $appId);
@@ -62,54 +89,94 @@ public function __construct($appId, string $appKey, string $appSecret)
         }
 
         $this->id = $appId;
-
         $this->key = $appKey;
-
         $this->secret = $appSecret;
     }
 
+    /**
+     * Set the name of the app.
+     *
+     * @param  string  $appName
+     * @return $this
+     */
     public function setName(string $appName)
     {
         $this->name = $appName;
 
         return $this;
     }
 
+    /**
+     * Set the app host.
+     *
+     * @param  string  $host
+     * @return $this
+     */
     public function setHost(string $host)
     {
         $this->host = $host;
 
         return $this;
     }
 
+    /**
+     * Set path for the app.
+     *
+     * @param  string  $path
+     * @return $this
+     */
     public function setPath(string $path)
     {
         $this->path = $path;
 
         return $this;
     }
 
+    /**
+     * Enable client messages.
+     *
+     * @param  bool  $enabled
+     * @return $this
+     */
     public function enableClientMessages(bool $enabled = true)
     {
         $this->clientMessagesEnabled = $enabled;
 
         return $this;
     }
 
+    /**
+     * Set the maximum capacity for the app.
+     *
+     * @param  int|null  $capacity
+     * @return $this
+     */
     public function setCapacity(?int $capacity)
     {
         $this->capacity = $capacity;
 
         return $this;
     }
 
+    /**
+     * Enable statistics for the app.
+     *
+     * @param  bool  $enabled
+     * @return $this
+     */
     public function enableStatistics(bool $enabled = true)
     {
         $this->statisticsEnabled = $enabled;
 
         return $this;
     }
 
+    /**
+     * Add whitelisted origins.
+     *
+     * @param  array  $allowedOrigins
+     * @return $this
+     */
     public function setAllowedOrigins(array $allowedOrigins)
     {
         $this->allowedOrigins = $allowedOrigins;

src/Apps/AppManager.php

@@ -4,12 +4,34 @@
 
 interface AppManager
 {
-    /**  @return array[BeyondCode\LaravelWebSockets\Apps\App] */
+    /**
+     * Get all apps.
+     *
+     * @return array[\BeyondCode\LaravelWebSockets\Apps\App]
+     */
     public function all(): array;
 
+    /**
+     * Get app by id.
+     *
+     * @param  mixed  $appId
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
     public function findById($appId): ?App;
 
-    public function findByKey(string $appKey): ?App;
+    /**
+     * Get app by app key.
+     *
+     * @param  mixed  $appKey
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
+    public function findByKey($appKey): ?App;
 
-    public function findBySecret(string $appSecret): ?App;
+    /**
+     * Get app by secret.
+     *
+     * @param  mixed  $appSecret
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
+    public function findBySecret($appSecret): ?App;
 }

src/Apps/ConfigAppManager.php

@@ -2,19 +2,30 @@
 
 namespace BeyondCode\LaravelWebSockets\Apps;
 
-use Illuminate\Support\Collection;
-
 class ConfigAppManager implements AppManager
 {
-    /** @var Collection */
+    /**
+     * The list of apps.
+     *
+     * @var \Illuminate\Support\Collection
+     */
     protected $apps;
 
+    /**
+     * Initialize the class.
+     *
+     * @return void
+     */
     public function __construct()
     {
         $this->apps = collect(config('websockets.apps'));
     }
 
-    /**  @return array[\BeyondCode\LaravelWebSockets\Apps\App] */
+    /**
+     * Get all apps.
+     *
+     * @return array[\BeyondCode\LaravelWebSockets\Apps\App]
+     */
     public function all(): array
     {
         return $this->apps
@@ -24,6 +35,12 @@ public function all(): array
             ->toArray();
     }
 
+    /**
+     * Get app by id.
+     *
+     * @param  mixed  $appId
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
     public function findById($appId): ?App
     {
         $appAttributes = $this
@@ -33,7 +50,13 @@ public function findById($appId): ?App
         return $this->instantiate($appAttributes);
     }
 
-    public function findByKey(string $appKey): ?App
+    /**
+     * Get app by app key.
+     *
+     * @param  mixed  $appKey
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
+    public function findByKey($appKey): ?App
     {
         $appAttributes = $this
             ->apps
@@ -42,7 +65,13 @@ public function findByKey(string $appKey): ?App
         return $this->instantiate($appAttributes);
     }
 
-    public function findBySecret(string $appSecret): ?App
+    /**
+     * Get app by secret.
+     *
+     * @param  mixed  $appSecret
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
+    public function findBySecret($appSecret): ?App
     {
         $appAttributes = $this
             ->apps
@@ -51,6 +80,12 @@ public function findBySecret(string $appSecret): ?App
         return $this->instantiate($appAttributes);
     }
 
+    /**
+     * Map the app into an App instance.
+     *
+     * @param  array|null  $app
+     * @return \BeyondCode\LaravelWebSockets\Apps\App|null
+     */
     protected function instantiate(?array $appAttributes): ?App
     {
         if (! $appAttributes) {

src/Console/CleanStatistics.php

@@ -8,11 +8,27 @@
 
 class CleanStatistics extends Command
 {
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
     protected $signature = 'websockets:clean
-                            {appId? : (optional) The app id that will be cleaned.}';
-
+        {appId? : (optional) The app id that will be cleaned.}
+    ';
+
+    /**
+     * The console command description.
+     *
+     * @var string|null
+     */
     protected $description = 'Clean up old statistics from the websocket log.';
 
+    /**
+     * Run the command.
+     *
+     * @return void
+     */
     public function handle()
     {
         $this->comment('Cleaning WebSocket Statistics...');
@@ -23,16 +39,14 @@ public function handle()
 
         $cutOffDate = Carbon::now()->subDay($maxAgeInDays)->format('Y-m-d H:i:s');
 
-        $webSocketsStatisticsEntryModelClass = config('websockets.statistics.model');
+        $class = config('websockets.statistics.model');
 
-        $amountDeleted = $webSocketsStatisticsEntryModelClass::where('created_at', '<', $cutOffDate)
+        $amountDeleted = $class::where('created_at', '<', $cutOffDate)
             ->when(! is_null($appId), function (Builder $query) use ($appId) {
                 $query->where('app_id', $appId);
             })
             ->delete();
 
         $this->info("Deleted {$amountDeleted} record(s) from the WebSocket statistics.");
-
-        $this->comment('All done!');
     }
 }

src/Console/RestartWebSocketServer.php

@@ -10,10 +10,25 @@ class RestartWebSocketServer extends Command
 {
     use InteractsWithTime;
 
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
     protected $signature = 'websockets:restart';
 
+    /**
+     * The console command description.
+     *
+     * @var string|null
+     */
     protected $description = 'Restart the Laravel WebSocket Server';
 
+    /**
+     * Run the command.
+     *
+     * @return void
+     */
     public function handle()
     {
         Cache::forever('beyondcode:websockets:restart', $this->currentTime());