Merge pull request #211 from cachethq/models

Cleaned Up The Models And Repositories

app/models/Component.php

@@ -2,14 +2,21 @@
 
 use CachetHQ\Cachet\Transformers\ComponentTransformer;
 use Dingo\Api\Transformer\TransformableInterface;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\SoftDeletingTrait;
+use Illuminate\Support\Facades\Lang;
 use Watson\Validating\ValidatingTrait;
 
 class Component extends Model implements TransformableInterface
 {
     use SoftDeletingTrait, ValidatingTrait;
 
+    /**
+     * The validation rules.
+     *
+     * @var string[]
+     */
     protected $rules = [
         'user_id' => 'integer|required',
         'name'    => 'required',
@@ -17,12 +24,17 @@ class Component extends Model implements TransformableInterface
         'link'    => 'url',
     ];
 
+    /**
+     * The fillable properties.
+     *
+     * @var string[]
+     */
     protected $fillable = ['name', 'description', 'status', 'user_id', 'tags', 'link', 'order'];
 
     /**
      * Lookup all of the incidents reported on the component.
      *
-     * @return \Illuminate\Database\Eloquent\Relations
+     * @return \Illuminate\Database\Eloquent\Relations\HasMany
      */
     public function incidents()
     {
@@ -37,7 +49,7 @@ class Component extends Model implements TransformableInterface
      *
      * @return \Illuminate\Database\Eloquent\Builder
      */
-    public function scopeStatus($query, $status)
+    public function scopeStatus(Builder $query, $status)
     {
         return $query->where('status', $status);
     }
@@ -50,7 +62,7 @@ class Component extends Model implements TransformableInterface
      *
      * @return \Illuminate\Database\Eloquent\Builder
      */
-    public function scopeNotStatus($query, $status)
+    public function scopeNotStatus(Builder $query, $status)
     {
         return $query->where('status', '<>', $status);
     }

app/models/Incident.php

@@ -11,6 +11,11 @@ class Incident extends Model implements TransformableInterface
 {
     use SoftDeletingTrait, ValidatingTrait;
 
+    /**
+     * The validation rules.
+     *
+     * @var string[]
+     */
     protected $rules = [
         'user_id'      => 'required|integer',
         'component_id' => 'integer',
@@ -19,8 +24,18 @@ class Incident extends Model implements TransformableInterface
         'message'      => 'required',
     ];
 
+    /**
+     * The fillable properties.
+     *
+     * @var string[]
+     */
     protected $fillable = ['user_id', 'component_id', 'name', 'status', 'message'];
 
+    /**
+     * The accessors to append to the model's serialized form.
+     *
+     * @var string[]
+     */
     protected $appends = ['humanStatus'];
 
     /**
@@ -53,10 +68,14 @@ class Incident extends Model implements TransformableInterface
     public function getIconAttribute()
     {
         switch ($this->status) {
-            case 1: return 'ion ion-flag';
-            case 2: return 'ion ion-alert';
-            case 3: return 'ion ion-eye';
-            case 4: return 'ion ion-checkmark';
+            case 1:
+                return 'ion ion-flag';
+            case 2:
+                return 'ion ion-alert';
+            case 3:
+                return 'ion ion-eye';
+            case 4:
+                return 'ion ion-checkmark';
         }
     }
 

app/models/IncidentTemplate.php

@@ -7,11 +7,21 @@ class IncidentTemplate extends Model
 {
     use ValidatingTrait;
 
+    /**
+     * The validation rules.
+     *
+     * @var string[]
+     */
     protected $rules = [
         'name'     => 'alpha|required',
         'template' => 'required',
     ];
 
+    /**
+     * The fillable properties.
+     *
+     * @var string[]
+     */
     protected $fillable = ['name', 'template'];
 
     /**

app/models/Metric.php

@@ -9,18 +9,28 @@ class Metric extends Model implements TransformableInterface
 {
     use ValidatingTrait;
 
+    /**
+     * The validation rules.
+     *
+     * @var string[]
+     */
     protected $rules = [
         'name'          => 'required',
         'suffix'        => 'required',
         'display_chart' => 'boolean',
     ];
 
+    /**
+     * The fillable properties.
+     *
+     * @var string[]
+     */
     protected $fillable = ['name', 'suffix', 'description', 'display_chart'];
 
     /**
      * Metrics contain many metric points.
      *
-     * @return \Illuminate\Database\Eloquent\Builder
+     * @return \Illuminate\Database\Eloquent\Relations\HasMany
      */
     public function points()
     {

app/models/Service.php

@@ -7,6 +7,11 @@ class Service extends Model
 {
     use ValidatingTrait;
 
+    /**
+     * The validation rules.
+     *
+     * @var string[]
+     */
     protected $rules = [
         'type'       => 'alpha_dash|required',
         'active'     => 'required|in:0,1',

app/models/Setting.php

@@ -4,6 +4,11 @@ use Illuminate\Database\Eloquent\Model;
 
 class Setting extends Model
 {
+    /**
+     * The fillable properties.
+     *
+     * @var string[]
+     */
     protected $fillable = ['name', 'value'];
 
     /**
@@ -12,41 +17,25 @@ class Setting extends Model
      * @param string $settingName
      * @param bool   $checkEnv
      *
-     * @return string
+     * @return string|null
      */
     public static function get($settingName, $checkEnv = true)
     {
-        // Default setting value.
         $setting = null;
 
-        // First try finding the setting in the database.
         try {
             $setting = self::whereName($settingName)->first()->value;
         } catch (ErrorException $e) {
-            // If we don't have a setting, check the env (fallback for original version)
             if ($checkEnv) {
-                if (!($setting = getenv(strtoupper($settingName)))) {
-                    return $setting;
+                $env = getenv(strtoupper($settingName));
+                if (!$env) {
+                    return $env;
                 }
-            } else {
-                return $setting;
             }
+
+            return $setting;
         }
 
         return $setting;
     }
-
-    /**
-     * Throws an Exception.
-     *
-     * @param string $setting
-     *
-     * @throws \Exception
-     *
-     * @return void
-     */
-    public static function unknownSettingException($setting)
-    {
-        throw new Exception(sprintf('Unknown setting %s', $setting));
-    }
 }

app/models/Subscriber.php

@@ -8,9 +8,19 @@ class Subscriber extends Model
 {
     use SoftDeletingTrait, ValidatingTrait;
 
+    /**
+     * The validation rules.
+     *
+     * @var string[]
+     */
     protected $rules = [
         'email' => 'required|email',
     ];
 
+    /**
+     * The fillable properties.
+     *
+     * @var string[]
+     */
     protected $fillable = ['email'];
 }

app/models/User.php

@@ -19,14 +19,16 @@ class User extends Model implements UserInterface, RemindableInterface
     protected $table = 'users';
 
     /**
-     * The attributes excluded from the model's JSON form.
+     * The hidden properties.
+     *
+     * These are excluded when we are serializing the model.
      *
      * @var array
      */
     protected $hidden = ['password', 'remember_token'];
 
     /**
-     * Items which cannot be mass assigned.
+     * The properties that cannot be mass assigned.
      *
      * @var array
      */
@@ -37,11 +39,13 @@ class User extends Model implements UserInterface, RemindableInterface
      *
      * @param string $password
      *
-     * @return void
+     * @return $this
      */
     public function setPasswordAttribute($password)
     {
         $this->attributes['password'] = Hash::make($password);
+
+        return $this;
     }
 
     /**

app/models/WebHook.php

@@ -2,11 +2,11 @@
 
 use GuzzleHttp\Client;
 use GuzzleHttp\Exception\ClientException;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 
 class WebHook extends Model
 {
-    // Request Methods.
     const HEAD = 0;
     const GET = 1;
     const POST = 2;
@@ -31,7 +31,7 @@ class WebHook extends Model
      *
      * @return \Illuminate\Database\Eloquent\Builder
      */
-    public function scopeActive($query)
+    public function scopeActive(Builder $query)
     {
         return $query->where('active', 1);
     }
@@ -94,7 +94,7 @@ class WebHook extends Model
      *
      * @throws \Exception
      *
-     * @return string HEAD, GET, POST, DELETE, PATCH, PUT etc
+     * @return string
      */
     public function getRequestMethodAttribute()
     {

src/Repositories/Component/ComponentRepository.php

@@ -4,11 +4,43 @@ namespace CachetHQ\Cachet\Repositories\Component;
 
 interface ComponentRepository
 {
+    /**
+     * Returns all models.
+     *
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
     public function all();
 
-    public function create($id, array $array);
+    /**
+     * Create a new model.
+     *
+     * @param int   $userId
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function create($userId, array $data);
 
+    /**
+     * Finds a model by id.
+     *
+     * @param int $id
+     *
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
     public function findOrFail($id);
 
-    public function with($id, array $with);
+    /**
+     * Returns an object with related relationships.
+     *
+     * @param int      $id
+     * @param string[] $with
+     *
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function with($id, array $with = []);
 }

src/Repositories/Component/EloquentComponentRepository.php

@@ -7,17 +7,37 @@ use Component;
 
 class EloquentComponentRepository extends EloquentRepository implements ComponentRepository
 {
+    /**
+     * The eloquent model instance.
+     *
+     * @var \Component
+     */
     protected $model;
 
+    /**
+     * Create a new eloquent component repository instance.
+     *
+     * @param \Component $model
+     *
+     * @return void
+     */
     public function __construct(Component $model)
     {
         $this->model = $model;
     }
 
-    public function create($user_id, array $array)
+    /**
+     * Create a new model.
+     *
+     * @param int   $userId
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function create($userId, array $data)
     {
-        $component = new $this->model($array);
-        $component->user_id = $user_id;
+        $component = new $this->model($data);
+        $component->user_id = $userId;
 
         $this->validate($component);
 

src/Repositories/EloquentRepository.php

@@ -2,7 +2,7 @@
 
 namespace CachetHQ\Cachet\Repositories;
 
-use Exception;
+use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 
 abstract class EloquentRepository
@@ -10,7 +10,7 @@ abstract class EloquentRepository
     /**
      * Returns all models.
      *
-     * @return object
+     * @return \Illuminate\Database\Eloquent\Collection
      */
     public function all()
     {
@@ -20,10 +20,12 @@ abstract class EloquentRepository
     /**
      * Returns an object with related relationships.
      *
-     * @param id    $id
-     * @param array $with Array of model relationships
+     * @param int      $id
+     * @param string[] $with
      *
-     * @return object|ModelNotFoundException
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     *
+     * @return \Illuminate\Database\Eloquent\Model
      */
     public function with($id, array $with = [])
     {
@@ -50,7 +52,7 @@ abstract class EloquentRepository
      *
      * @param int $id
      *
-     * @return object
+     * @return \Illuminate\Database\Eloquent\Model
      */
     public function find($id)
     {
@@ -58,11 +60,13 @@ abstract class EloquentRepository
     }
 
     /**
-     * Finds a model by ID.
+     * Finds a model by id.
      *
      * @param int $id
      *
-     * @return object|ModelNotFoundException
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     *
+     * @return \Illuminate\Database\Eloquent\Model
      */
     public function findOrFail($id)
     {
@@ -76,38 +80,44 @@ abstract class EloquentRepository
      * @param string $value
      * @param array  $columns
      *
-     * @return object|ModelNotFoundException
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     *
+     * @return \Illuminate\Database\Eloquent\Model
      */
     public function findByOrFail($key, $value, $columns = ['*'])
     {
-        if (! is_null($item = $this->model->where($key, $value)->first($columns))) {
-            return $item;
+        $model = $this->model->where($key, $value)->first($columns);
+
+        if ($model === null) {
+            throw new ModelNotFoundException();
         }
 
-        throw new ModelNotFoundException();
+        return $model;
     }
 
     /**
      * Counts the number of rows returned.
      *
-     * @param string $key
-     * @param string $value
+     * @param string|null $key
+     * @param string|null $value
      *
      * @return int
      */
     public function count($key = null, $value = null)
     {
-        if (is_null($key) || is_null($value)) {
-            return $this->model->where($key, $value)->count();
+        if ($key === null || $value === null) {
+            return $this->model->count();
         }
 
-        return $this->model->count();
+        return $this->model->where($key, $value)->count();
     }
 
     /**
-     * Deletes a model by ID.
+     * Deletes a model by id.
      *
-     * @param inetegr $id
+     * @param int $id
+     *
+     * @return void
      */
     public function destroy($id)
     {
@@ -117,14 +127,16 @@ abstract class EloquentRepository
     /**
      * Validate a given model with Watson validation.
      *
-     * @param object $model
+     * @param \Illuminate\Database\Eloquent\Model $model
      *
-     * @return Exception
+     * @throws \CachetHQ\Cachet\Repositories\InvalidModelValidationException
+     *
+     * @return $this
      */
-    public function validate($model)
+    public function validate(Model $model)
     {
         if ($model->isInvalid()) {
-            throw new Exception('Invalid model validation');
+            throw new InvalidModelValidationException('Validation failed on the model.');
         }
 
         return $this;
@@ -133,15 +145,17 @@ abstract class EloquentRepository
     /**
      * Validate whether a model has a correct relationship.
      *
-     * @param object $model
-     * @param string $relationship Name of the relationship to validate against
+     * @param \Illuminate\Database\Eloquent\Model $model
+     * @param string                              $relationship
      *
-     * @return Exception
+     * @throws \CachetHQ\Cachet\Repositories\InvalidRelationshipException
+     *
+     * @return $this
      */
-    public function hasRelationship($model, $relationship)
+    public function hasRelationship(Model $model, $relationship)
     {
-        if (! $model->$relationship) {
-            throw new Exception('Invalid relationship exception');
+        if ($model->$relationship === null) {
+            throw new InvalidRelationshipException('The relationship was not valid.');
         }
 
         return $this;

src/Repositories/Incident/EloquentIncidentRepository.php

@@ -7,20 +7,40 @@ use Incident;
 
 class EloquentIncidentRepository extends EloquentRepository implements IncidentRepository
 {
+    /**
+     * The eloquent model instance.
+     *
+     * @var \Incident
+     */
     protected $model;
 
+    /**
+     * Create a new eloquent incident repository instance.
+     *
+     * @param \Incident $model
+     *
+     * @return void
+     */
     public function __construct(Incident $model)
     {
         $this->model = $model;
     }
 
-    public function create($user_id, array $array)
+    /**
+     * Create a new model.
+     *
+     * @param int   $userId
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function create($userId, array $data)
     {
-        $incident = new $this->model($array);
-        $incident->user_id = $user_id;
+        $incident = new $this->model($data);
+        $incident->user_id = $userId;
         $this->validate($incident);
 
-        if (isset($array['component_id'])) {
+        if (isset($data['component_id'])) {
             $this->hasRelationship($incident, 'component');
         }
 
@@ -29,17 +49,25 @@ class EloquentIncidentRepository extends EloquentRepository implements IncidentR
         return $incident;
     }
 
-    public function update($id, array $array)
+    /**
+     * Update a model by id.
+     *
+     * @param int   $id
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function update($id, array $data)
     {
         $incident = $this->model->findOrFail($id);
-        $incident->fill($array);
+        $incident->fill($data);
         $this->validate($incident);
 
-        if (isset($array['component_id'])) {
+        if (isset($data['component_id'])) {
             $this->hasRelationship($incident, 'component');
         }
 
-        $incident->update($array);
+        $incident->update($data);
 
         return $incident;
     }

src/Repositories/Incident/IncidentRepository.php

@@ -4,11 +4,41 @@ namespace CachetHQ\Cachet\Repositories\Incident;
 
 interface IncidentRepository
 {
+    /**
+     * Returns all models.
+     *
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
     public function all();
 
-    public function create($id, array $array);
+    /**
+     * Create a new model.
+     *
+     * @param int   $userId
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function create($userId, array $data);
 
+    /**
+     * Finds a model by id.
+     *
+     * @param int $id
+     *
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
     public function findOrFail($id);
 
-    public function update($id, array $with);
+    /**
+     * Update a model by id.
+     *
+     * @param int   $id
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function update($id, array $data);
 }

src/Repositories/InvalidModelValidationException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace CachetHQ\Cachet\Repositories;
+
+use Exception;
+
+class InvalidModelValidationException extends Exception
+{
+    //
+}

src/Repositories/InvalidRelationshipException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace CachetHQ\Cachet\Repositories;
+
+use Exception;
+
+class InvalidRelationshipException extends Exception
+{
+    //
+}

src/Repositories/Metric/EloquentMetricRepository.php

@@ -7,16 +7,35 @@ use Metric;
 
 class EloquentMetricRepository extends EloquentRepository implements MetricRepository
 {
+    /**
+     * The eloquent model instance.
+     *
+     * @var \Metric
+     */
     protected $model;
 
+    /**
+     * Create a new eloquent metric repository instance.
+     *
+     * @param \Metric $model
+     *
+     * @return void
+     */
     public function __construct(Metric $model)
     {
         $this->model = $model;
     }
 
-    public function create(array $array)
+    /**
+     * Create a new model.
+     *
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function create(array $data)
     {
-        $metric = new $this->model($array);
+        $metric = new $this->model($data);
 
         $this->validate($metric);
 
@@ -25,14 +44,22 @@ class EloquentMetricRepository extends EloquentRepository implements MetricRepos
         return $metric;
     }
 
-    public function update($id, array $array)
+    /**
+     * Update a model by id.
+     *
+     * @param int   $id
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function update($id, array $data)
     {
         $metric = $this->model->findOrFail($id);
-        $metric->fill($array);
+        $metric->fill($data);
 
         $this->validate($metric);
 
-        $metric->update($array);
+        $metric->update($data);
 
         return $metric;
     }

src/Repositories/Metric/MetricRepository.php

@@ -4,11 +4,40 @@ namespace CachetHQ\Cachet\Repositories\Metric;
 
 interface MetricRepository
 {
+    /**
+     * Returns all models.
+     *
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
     public function all();
 
-    public function create(array $array);
+    /**
+     * Create a new model.
+     *
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function create(array $data);
 
+    /**
+     * Finds a model by id.
+     *
+     * @param int $id
+     *
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
     public function findOrFail($id);
 
-    public function update($id, array $with);
+    /**
+     * Update a model by id.
+     *
+     * @param int   $id
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function update($id, array $data);
 }

src/Repositories/MetricPoint/EloquentMetricPointRepository.php

@@ -7,16 +7,35 @@ use MetricPoint;
 
 class EloquentMetricPointRepository extends EloquentRepository implements MetricPointRepository
 {
+    /**
+     * The eloquent model instance.
+     *
+     * @var \MetricPoint
+     */
     protected $model;
 
+    /**
+     * Create a new eloquent metric point repository instance.
+     *
+     * @param \MetricPoint $model
+     *
+     * @return void
+     */
     public function __construct(MetricPoint $model)
     {
         $this->model = $model;
     }
 
-    public function create(array $array)
+    /**
+     * Create a new model.
+     *
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function create(array $data)
     {
-        $metric = new $this->model($array);
+        $metric = new $this->model($data);
 
         $this->validate($metric);
 
@@ -25,14 +44,22 @@ class EloquentMetricPointRepository extends EloquentRepository implements Metric
         return $metric;
     }
 
-    public function update($id, array $array)
+    /**
+     * Update a model by id.
+     *
+     * @param int   $id
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function update($id, array $data)
     {
         $metric = $this->model->findOrFail($id);
-        $metric->fill($array);
+        $metric->fill($data);
 
         $this->validate($metric);
 
-        $metric->update($array);
+        $metric->update($data);
 
         return $metric;
     }

src/Repositories/MetricPoint/MetricPointRepository.php

@@ -4,11 +4,40 @@ namespace CachetHQ\Cachet\Repositories\MetricPoint;
 
 interface MetricPointRepository
 {
+    /**
+     * Returns all models.
+     *
+     * @return \Illuminate\Database\Eloquent\Collection
+     */
     public function all();
 
-    public function create(array $array);
+    /**
+     * Create a new model.
+     *
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function create(array $data);
 
+    /**
+     * Finds a model by id.
+     *
+     * @param int $id
+     *
+     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
     public function findOrFail($id);
 
-    public function update($id, array $with);
+    /**
+     * Update a model by id.
+     *
+     * @param int   $id
+     * @param array $data
+     *
+     * @return \Illuminate\Database\Eloquent\Model
+     */
+    public function update($id, array $data);
 }