improved phpdoc for classes properties

Okipa · May 9, 2019 · ceecc4a · ceecc4a
1 parent 9afec12
commit ceecc4a
Show file tree

Hide file tree

Showing 6 changed files with 190 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -194,7 +194,7 @@ public function index(Request $request) {
 
 <h3 id="table-rowsNumber">->rowsNumber</h3>
 
-> Override the config default number of rows to display on the table.  
+> Override the config default number of rows displayed on the table.  
 > The default number of displayed rows is defined in the `config('laravel-table.value.rowsNumber')` config value.  
 > Set `false` to display all the models contained in database.
 

diff --git a/src/Column.php b/src/Column.php
@@ -8,21 +8,101 @@
 
 class Column
 {
+    /**
+     * The table instance the table column is associated to.
+     *
+     * @property \Okipa\LaravelTable\Table $table
+     */
     public $table;
+    /**
+     * The database table the table column is associated to.
+     *
+     * @property string $databaseDefaultTable
+     */
     public $databaseDefaultTable;
+    /**
+     * The database table the table column is associated to for the searching action.
+     *
+     * @property string $databaseSearchedTable
+     */
     public $databaseSearchedTable;
+    /**
+     * The database column the table column is associated to.
+     *
+     * @property string $databaseDefaultColumn
+     */
     public $databaseDefaultColumn;
+    /**
+     * The database column the table column is associated to for the searching action.
+     *
+     * @property string $databaseSearchedColumns
+     */
     public $databaseSearchedColumns;
+    /**
+     * The table column sortable status.
+     *
+     * @property bool $isSortable
+     */
     public $isSortable;
+    /**
+     * The table column custom title.
+     *
+     * @property string $title
+     */
     public $title;
+    /**
+     * The table column datetime format.
+     *
+     * @property string $dateTimeFormat
+     */
     public $dateTimeFormat;
+    /**
+     * The table column button classes.
+     *
+     * @property array $buttonClasses
+     */
     public $buttonClasses;
+    /**
+     * The table column string length limitation.
+     *
+     * @property int $stringLimit
+     */
     public $stringLimit;
+    /**
+     * The table column url.
+     *
+     * @property string $url
+     */
     public $url;
+    /**
+     * The table column custom value closure.
+     *
+     * @property Closure $valueClosure
+     */
     public $valueClosure;
+    /**
+     * The table column custom html output closure.
+     *
+     * @property Closure $htmlClosure
+     */
     public $htmlClosure;
+    /**
+     * The table column value prepended icon.
+     *
+     * @property string $icon
+     */
     public $icon;
+    /**
+     * The icon display status when no value is found.
+     *
+     * @property bool $displayIconWhenNoValue
+     */
     public $displayIconWhenNoValue;
+    /**
+     * The table column classes.
+     *
+     * @property array $classes
+     */
     public $classes;
 
     /**
@@ -87,13 +167,13 @@ protected function sortByDefault($sortDirection = 'asc')
     {
         if ($this->table->sortBy || $this->table->sortDir) {
             $errorMessage = 'The table is already sorted by the « ' . $this->table->sortBy
-                            . ' » database column. You only can sort a table column by default once.';
+                . ' » database column. You only can sort a table column by default once.';
             throw new ErrorException($errorMessage);
         }
         $this->table->sortBy = $this->databaseDefaultColumn;
         $acceptedDirections = ['asc', 'desc'];
         $errorMessage = 'Invalid « $sortDirection » second argument for « sortable() » method. Has to be « asc » or '
-                        . '« desc ». « ' . $sortDirection . ' » given.';
+            . '« desc ». « ' . $sortDirection . ' » given.';
         if (! in_array($sortDirection, $acceptedDirections)) {
             throw new InvalidArgumentException($errorMessage);
         }

diff --git a/src/Table.php b/src/Table.php
@@ -21,23 +21,113 @@ class Table implements Htmlable
     use ClassesCustomizations;
     use RoutesValidationChecks;
     use ColumnsValidationChecks;
+    /**
+     * The model used during the table generation.
+     *
+     * @property \Illuminate\Database\Eloquent\Model $model
+     */
     public $model;
+    /**
+     * The number of rows displayed on the table.
+     *
+     * @property int $rows
+     */
     public $rows;
+    /**
+     * The rows number selection activation status.
+     *
+     * @property bool $rowsNumberSelectionActivation
+     */
     public $rowsNumberSelectionActivation;
+    /**
+     * The sortable columns in the table.
+     *
+     * @property \Illuminate\Support\Collection $sortableColumns
+     */
     public $sortableColumns;
+    /**
+     * The database column name the table is sorted.
+     *
+     * @property string $sortBy
+     */
     public $sortBy;
+    /**
+     * The direction the table is sorted.
+     *
+     * @property string $sortDir
+     */
     public $sortDir;
+    /**
+     * The searched value in database.
+     *
+     * @property string $search
+     */
     public $search;
+    /**
+     * The searchable columns in the table.
+     *
+     * @property \Illuminate\Support\Collection $searchableColumns
+     */
     public $searchableColumns;
+    /**
+     * The request used by the table.
+     *
+     * @property \Illuminate\Http\Request $request
+     */
     public $request;
+    /**
+     * The routes used by the table.
+     *
+     * @property array $routes
+     */
     public $routes = [];
+    /**
+     * The table columns.
+     *
+     * @property \Illuminate\Support\Collection $columns
+     */
     public $columns;
+    /**
+     * The table additional query instructions closure.
+     *
+     * @property Closure $queryClosure
+     */
     public $queryClosure;
+    /**
+     * The table disabled rows.
+     *
+     * @property \Illuminate\Support\Collection $disableRows
+     */
     public $disableRows;
+    /**
+     * The table generated list to display.
+     *
+     * @property \Illuminate\Pagination\LengthAwarePaginator $list
+     */
     public $list;
+    /**
+     * The generated html code used for each line destroy confirmation closure.
+     *
+     * @property Closure $destroyConfirmationClosure
+     */
     public $destroyConfirmationClosure;
+    /**
+     * The values to append to the request treatments.
+     *
+     * @property array $appendedValues
+     */
     public $appendedValues = [];
+    /**
+     * The generated hidden fields to insert in the html form when values are appended to the request.
+     *
+     * @property array $appendedHiddenFields
+     */
     public $appendedHiddenFields = [];
+    /**
+     * The result lines to display at the bottom of the table.
+     *
+     * @property \Illuminate\Support\Collection $results
+     */
     public $results;
 
     /**
@@ -103,10 +193,10 @@ public function routes(array $routes): Table
     }
 
     /**
-     * Override the config default number of rows to display on the table.
+     * Override the config default number of rows displayed on the table.
      * The default number of displayed rows is defined in the config('laravel-table.value.rowsNumber') config value.
      *
-     * @param int|false $rows
+     * @param int|null $rows
      *
      * @return \Okipa\LaravelTable\Table
      */

diff --git a/src/Traits/ClassesCustomizations.php b/src/Traits/ClassesCustomizations.php
@@ -28,6 +28,7 @@ public function containerClasses(array $containerClasses): Table
     {
         $this->containerClasses = $containerClasses;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -43,6 +44,7 @@ public function tableClasses(array $tableClasses): Table
     {
         $this->tableClasses = $tableClasses;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -58,6 +60,7 @@ public function trClasses(array $trClasses): Table
     {
         $this->trClasses = $trClasses;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -73,6 +76,7 @@ public function thClasses(array $thClasses): Table
     {
         $this->thClasses = $thClasses;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -87,6 +91,7 @@ public function tdClasses(array $tdClasses): Table
     {
         $this->tdClasses = $tdClasses;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -101,6 +106,7 @@ public function resultClasses(array $resultClasses): Table
     {
         $this->resultClasses = $resultClasses;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -120,6 +126,7 @@ public function rowsConditionalClasses(Closure $rowClassesClosure, array $rowCla
             'classes' => $rowClasses,
         ]);
 
+        /** @var Table $this */
         return $this;
     }
 

diff --git a/src/Traits/ColumnsValidationChecks.php b/src/Traits/ColumnsValidationChecks.php
@@ -7,6 +7,7 @@
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Str;
 use Okipa\LaravelTable\Column;
 
 trait ColumnsValidationChecks
@@ -136,8 +137,8 @@ protected function tableData(Column $column, Builder $query): array
             $fromSqlStatement = last(explode(' from ', (string) $query->toSql()));
             preg_match_all('/["`]([a-zA-Z0-9_]*)["`] as ["`]([a-zA-Z0-9_]*)["`]/', $fromSqlStatement, $aliases);
             if (! empty(array_filter($aliases))) {
-                $position = array_keys(array_where(array_shift($aliases), function ($alias) use ($table) {
-                    return str_contains($alias, $table);
+                $position = array_keys(Arr::where(array_shift($aliases), function ($alias) use ($table) {
+                    return Str::contains($alias, $table);
                 }));
                 $alias = head($aliases)[head($position)];
                 $columns = Schema::getColumnListing($alias);

diff --git a/src/Traits/TemplatesCustomizations.php b/src/Traits/TemplatesCustomizations.php
@@ -24,6 +24,7 @@ public function tableTemplate(string $tableComponentPath): Table
     {
         $this->tableComponentPath = $tableComponentPath;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -39,6 +40,7 @@ public function theadTemplate(string $theadComponentPath): Table
     {
         $this->theadComponentPath = $theadComponentPath;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -54,6 +56,7 @@ public function tbodyTemplate(string $tbodyComponentPath): Table
     {
         $this->tbodyComponentPath = $tbodyComponentPath;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -69,6 +72,7 @@ public function resultsTemplate(string $resultsComponentPath): Table
     {
         $this->resultsComponentPath = $resultsComponentPath;
 
+        /** @var Table $this */
         return $this;
     }
 
@@ -84,6 +88,7 @@ public function tfootTemplate(string $tfootComponentPath): Table
     {
         $this->tfootComponentPath = $tfootComponentPath;
 
+        /** @var Table $this */
         return $this;
     }