Skip to content

Commit ae80474

Browse files
authored
Merge pull request #6822 from kenjis/fix-phpdocs-models
docs: fix PHPDoc and comments in Models
2 parents 4a748b9 + 64d751a commit ae80474

File tree

3 files changed

+58
-56
lines changed

3 files changed

+58
-56
lines changed

.github/workflows/test-phpunit.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ jobs:
125125
with:
126126
php-version: ${{ matrix.php-versions }}
127127
tools: composer, pecl
128-
extensions: imagick, sqlsrv, gd, sqlite3, redis, memcached, oci8, pgsql
128+
extensions: imagick, sqlsrv-5.10.1, gd, sqlite3, redis, memcached, oci8, pgsql
129129
coverage: ${{ env.COVERAGE_DRIVER }}
130130
env:
131131
update: true

system/BaseModel.php

Lines changed: 52 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
use CodeIgniter\Database\BaseResult;
1717
use CodeIgniter\Database\Exceptions\DatabaseException;
1818
use CodeIgniter\Database\Exceptions\DataException;
19+
use CodeIgniter\Database\Query;
1920
use CodeIgniter\Exceptions\ModelException;
2021
use CodeIgniter\I18n\Time;
2122
use CodeIgniter\Pager\Pager;
@@ -311,8 +312,8 @@ protected function initialize()
311312
}
312313

313314
/**
314-
* Fetches the row of database
315-
* This methods works only with dbCalls
315+
* Fetches the row of database.
316+
* This method works only with dbCalls.
316317
*
317318
* @param bool $singleton Single or multiple results
318319
* @param array|int|string|null $id One primary key or an array of primary keys
@@ -322,8 +323,8 @@ protected function initialize()
322323
abstract protected function doFind(bool $singleton, $id = null);
323324

324325
/**
325-
* Fetches the column of database
326-
* This methods works only with dbCalls
326+
* Fetches the column of database.
327+
* This method works only with dbCalls.
327328
*
328329
* @param string $columnName Column Name
329330
*
@@ -335,7 +336,7 @@ abstract protected function doFindColumn(string $columnName);
335336

336337
/**
337338
* Fetches all results, while optionally limiting them.
338-
* This methods works only with dbCalls
339+
* This method works only with dbCalls.
339340
*
340341
* @param int $limit Limit
341342
* @param int $offset Offset
@@ -346,15 +347,15 @@ abstract protected function doFindAll(int $limit = 0, int $offset = 0);
346347

347348
/**
348349
* Returns the first row of the result set.
349-
* This methods works only with dbCalls
350+
* This method works only with dbCalls.
350351
*
351352
* @return array|object|null
352353
*/
353354
abstract protected function doFirst();
354355

355356
/**
356-
* Inserts data into the current database
357-
* This method works only with dbCalls
357+
* Inserts data into the current database.
358+
* This method works only with dbCalls.
358359
*
359360
* @param array $data Data
360361
*
@@ -364,7 +365,7 @@ abstract protected function doInsert(array $data);
364365

365366
/**
366367
* Compiles batch insert and runs the queries, validating each row prior.
367-
* This methods works only with dbCalls
368+
* This method works only with dbCalls.
368369
*
369370
* @param array|null $set An associative array of insert values
370371
* @param bool|null $escape Whether to escape values
@@ -377,31 +378,31 @@ abstract protected function doInsertBatch(?array $set = null, ?bool $escape = nu
377378

378379
/**
379380
* Updates a single record in the database.
380-
* This methods works only with dbCalls
381+
* This method works only with dbCalls.
381382
*
382383
* @param array|int|string|null $id ID
383384
* @param array|null $data Data
384385
*/
385386
abstract protected function doUpdate($id = null, $data = null): bool;
386387

387388
/**
388-
* Compiles an update and runs the query
389-
* This methods works only with dbCalls
389+
* Compiles an update and runs the query.
390+
* This method works only with dbCalls.
390391
*
391392
* @param array|null $set An associative array of update values
392393
* @param string|null $index The where key
393394
* @param int $batchSize The size of the batch to run
394395
* @param bool $returnSQL True means SQL is returned, false will execute the query
395396
*
396-
* @return mixed Number of rows affected or FALSE on failure
397+
* @return false|int|string[] Number of rows affected or FALSE on failure, SQL array when testMode
397398
*
398399
* @throws DatabaseException
399400
*/
400401
abstract protected function doUpdateBatch(?array $set = null, ?string $index = null, int $batchSize = 100, bool $returnSQL = false);
401402

402403
/**
403-
* Deletes a single record from the database where $id matches
404-
* This methods works only with dbCalls
404+
* Deletes a single record from the database where $id matches.
405+
* This method works only with dbCalls.
405406
*
406407
* @param array|int|string|null $id The rows primary key(s)
407408
* @param bool $purge Allows overriding the soft deletes setting.
@@ -413,9 +414,9 @@ abstract protected function doUpdateBatch(?array $set = null, ?string $index = n
413414
abstract protected function doDelete($id = null, bool $purge = false);
414415

415416
/**
416-
* Permanently deletes all rows that have been marked as deleted
417-
* through soft deletes (deleted = 1)
418-
* This methods works only with dbCalls
417+
* Permanently deletes all rows that have been marked as deleted.
418+
* through soft deletes (deleted = 1).
419+
* This method works only with dbCalls.
419420
*
420421
* @return bool|string Returns a string if in test mode.
421422
*/
@@ -424,31 +425,31 @@ abstract protected function doPurgeDeleted();
424425
/**
425426
* Works with the find* methods to return only the rows that
426427
* have been deleted.
427-
* This methods works only with dbCalls
428+
* This method works only with dbCalls.
428429
*/
429430
abstract protected function doOnlyDeleted();
430431

431432
/**
432-
* Compiles a replace and runs the query
433-
* This methods works only with dbCalls
433+
* Compiles a replace and runs the query.
434+
* This method works only with dbCalls.
434435
*
435436
* @param array|null $data Data
436437
* @param bool $returnSQL Set to true to return Query String
437438
*
438-
* @return mixed
439+
* @return BaseResult|false|Query|string
439440
*/
440441
abstract protected function doReplace(?array $data = null, bool $returnSQL = false);
441442

442443
/**
443444
* Grabs the last error(s) that occurred from the Database connection.
444-
* This methods works only with dbCalls
445+
* This method works only with dbCalls.
445446
*
446447
* @return array|null
447448
*/
448449
abstract protected function doErrors();
449450

450451
/**
451-
* Returns the id value for the data array or object
452+
* Returns the id value for the data array or object.
452453
*
453454
* @param array|object $data Data
454455
*
@@ -459,8 +460,8 @@ abstract protected function doErrors();
459460
abstract protected function idValue($data);
460461

461462
/**
462-
* Public getter to return the id value using the idValue() method
463-
* For example with SQL this will return $data->$this->primaryKey
463+
* Public getter to return the id value using the idValue() method.
464+
* For example with SQL this will return $data->$this->primaryKey.
464465
*
465466
* @param array|object $data
466467
*
@@ -475,18 +476,18 @@ public function getIdValue($data)
475476

476477
/**
477478
* Override countAllResults to account for soft deleted accounts.
478-
* This methods works only with dbCalls
479+
* This method works only with dbCalls.
479480
*
480481
* @param bool $reset Reset
481482
* @param bool $test Test
482483
*
483-
* @return mixed
484+
* @return int|string
484485
*/
485486
abstract public function countAllResults(bool $reset = true, bool $test = false);
486487

487488
/**
488489
* Loops over records in batches, allowing you to operate on them.
489-
* This methods works only with dbCalls
490+
* This method works only with dbCalls.
490491
*
491492
* @param int $size Size
492493
* @param Closure $userFunc Callback Function
@@ -496,7 +497,7 @@ abstract public function countAllResults(bool $reset = true, bool $test = false)
496497
abstract public function chunk(int $size, Closure $userFunc);
497498

498499
/**
499-
* Fetches the row of database
500+
* Fetches the row of database.
500501
*
501502
* @param array|int|string|null $id One primary key or an array of primary keys
502503
*
@@ -538,7 +539,7 @@ public function find($id = null)
538539
}
539540

540541
/**
541-
* Fetches the column of database
542+
* Fetches the column of database.
542543
*
543544
* @param string $columnName Column Name
544545
*
@@ -667,8 +668,8 @@ public function save($data): bool
667668
}
668669

669670
/**
670-
* This method is called on save to determine if entry have to be updated
671-
* If this method return false insert operation will be executed
671+
* This method is called on save to determine if entry have to be updated.
672+
* If this method returns false insert operation will be executed
672673
*
673674
* @param array|object $data Data
674675
*/
@@ -719,7 +720,7 @@ public function insert($data = null, bool $returnID = true)
719720
// Restore $cleanValidationRules
720721
$this->cleanValidationRules = $cleanValidationRules;
721722

722-
// Must be called first so we don't
723+
// Must be called first, so we don't
723724
// strip out created_at values.
724725
$data = $this->doProtectFields($data);
725726

@@ -896,14 +897,14 @@ public function update($id = null, $data = null): bool
896897
}
897898

898899
/**
899-
* Compiles an update and runs the query
900+
* Compiles an update and runs the query.
900901
*
901902
* @param array|null $set An associative array of update values
902903
* @param string|null $index The where key
903904
* @param int $batchSize The size of the batch to run
904905
* @param bool $returnSQL True means SQL is returned, false will execute the query
905906
*
906-
* @return mixed Number of rows affected or FALSE on failure
907+
* @return false|int|string[] Number of rows affected or FALSE on failure, SQL array when testMode
907908
*
908909
* @throws DatabaseException
909910
* @throws ReflectionException
@@ -953,7 +954,7 @@ public function updateBatch(?array $set = null, ?string $index = null, int $batc
953954
}
954955

955956
/**
956-
* Deletes a single record from the database where $id matches
957+
* Deletes a single record from the database where $id matches.
957958
*
958959
* @param array|int|string|null $id The rows primary key(s)
959960
* @param bool $purge Allows overriding the soft deletes setting.
@@ -995,9 +996,9 @@ public function delete($id = null, bool $purge = false)
995996

996997
/**
997998
* Permanently deletes all rows that have been marked as deleted
998-
* through soft deletes (deleted = 1)
999+
* through soft deletes (deleted = 1).
9991000
*
1000-
* @return mixed
1001+
* @return bool|string Returns a string if in test mode.
10011002
*/
10021003
public function purgeDeleted()
10031004
{
@@ -1038,12 +1039,12 @@ public function onlyDeleted()
10381039
}
10391040

10401041
/**
1041-
* Compiles a replace and runs the query
1042+
* Compiles a replace and runs the query.
10421043
*
10431044
* @param array|null $data Data
10441045
* @param bool $returnSQL Set to true to return Query String
10451046
*
1046-
* @return mixed
1047+
* @return BaseResult|false|Query|string
10471048
*/
10481049
public function replace(?array $data = null, bool $returnSQL = false)
10491050
{
@@ -1063,6 +1064,7 @@ public function replace(?array $data = null, bool $returnSQL = false)
10631064
* Grabs the last error(s) that occurred. If data was validated,
10641065
* it will first check for errors there, otherwise will try to
10651066
* grab the last error from the Database connection.
1067+
*
10661068
* The return array should be in the following format:
10671069
* ['source' => 'message']
10681070
*
@@ -1170,11 +1172,11 @@ protected function doProtectFields(array $data): array
11701172
}
11711173

11721174
/**
1173-
* Sets the date or current date if null value is passed
1175+
* Sets the date or current date if null value is passed.
11741176
*
11751177
* @param int|null $userData An optional PHP timestamp to be converted.
11761178
*
1177-
* @return mixed
1179+
* @return int|string
11781180
*
11791181
* @throws ModelException
11801182
*/
@@ -1220,7 +1222,7 @@ protected function intToDate(int $value)
12201222
}
12211223

12221224
/**
1223-
* Converts Time value to string using $this->dateFormat
1225+
* Converts Time value to string using $this->dateFormat.
12241226
*
12251227
* The available time formats are:
12261228
* - 'int' - Stores the date as an integer timestamp
@@ -1397,7 +1399,7 @@ public function getValidationRules(array $options = []): array
13971399
}
13981400

13991401
/**
1400-
* Returns the model's define validation messages so they
1402+
* Returns the model's validation messages, so they
14011403
* can be used elsewhere, if needed.
14021404
*/
14031405
public function getValidationMessages(): array
@@ -1454,14 +1456,14 @@ public function allowCallbacks(bool $val = true)
14541456
*
14551457
* Each $eventData array MUST have a 'data' key with the relevant
14561458
* data for callback methods (like an array of key/value pairs to insert
1457-
* or update, an array of results, etc)
1459+
* or update, an array of results, etc.)
14581460
*
14591461
* If callbacks are not allowed then returns $eventData immediately.
14601462
*
14611463
* @param string $event Event
14621464
* @param array $eventData Event Data
14631465
*
1464-
* @return mixed
1466+
* @return array
14651467
*
14661468
* @throws DataException
14671469
*/
@@ -1513,14 +1515,14 @@ public function asObject(string $class = 'object')
15131515
}
15141516

15151517
/**
1516-
* Takes a class and returns an array of it's public and protected
1518+
* Takes a class and returns an array of its public and protected
15171519
* properties as an array suitable for use in creates and updates.
15181520
* This method uses objectToRawArray() internally and does conversion
15191521
* to string on all Time instances
15201522
*
15211523
* @param object|string $data Data
15221524
* @param bool $onlyChanged Only Changed Property
1523-
* @param bool $recursive If true, inner entities will be casted as array as well
1525+
* @param bool $recursive If true, inner entities will be cast as array as well
15241526
*
15251527
* @return array Array
15261528
*
@@ -1579,7 +1581,7 @@ protected function objectToRawArray($data, bool $onlyChanged = true, bool $recur
15791581
}
15801582

15811583
/**
1582-
* Transform data to array
1584+
* Transform data to array.
15831585
*
15841586
* @param array|object|null $data Data
15851587
* @param string $type Type of data (insert|update)

0 commit comments

Comments
 (0)