Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix PHPDoc and comments in Models #6822

Merged
merged 4 commits into from
Nov 7, 2022
Merged

docs: fix PHPDoc and comments in Models #6822

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fb102fb
docs: fix @return
kenjis Nov 6, 2022
a2ad508
docs: update comments
kenjis Nov 6, 2022
8c78af1
docs: fix comment
kenjis Nov 6, 2022
64d751a
chore: set sqlsrv-5.10.1
kenjis Nov 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 52 additions & 50 deletions system/BaseModel.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
use CodeIgniter\Database\BaseResult;
use CodeIgniter\Database\Exceptions\DatabaseException;
use CodeIgniter\Database\Exceptions\DataException;
use CodeIgniter\Database\Query;
use CodeIgniter\Exceptions\ModelException;
use CodeIgniter\I18n\Time;
use CodeIgniter\Pager\Pager;
Expand Down Expand Up @@ -311,8 +312,8 @@ protected function initialize()
}

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

/**
* Fetches the column of database
* This methods works only with dbCalls
* Fetches the column of database.
* This method works only with dbCalls.
*
* @param string $columnName Column Name
*
Expand All @@ -335,7 +336,7 @@ abstract protected function doFindColumn(string $columnName);

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

/**
* Returns the first row of the result set.
* This methods works only with dbCalls
* This method works only with dbCalls.
*
* @return array|object|null
*/
abstract protected function doFirst();

/**
* Inserts data into the current database
* This method works only with dbCalls
* Inserts data into the current database.
* This method works only with dbCalls.
*
* @param array $data Data
*
Expand All @@ -364,7 +365,7 @@ abstract protected function doInsert(array $data);

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

/**
* Updates a single record in the database.
* This methods works only with dbCalls
* This method works only with dbCalls.
*
* @param array|int|string|null $id ID
* @param array|null $data Data
*/
abstract protected function doUpdate($id = null, $data = null): bool;

/**
* Compiles an update and runs the query
* This methods works only with dbCalls
* Compiles an update and runs the query.
* This method works only with dbCalls.
*
* @param array|null $set An associative array of update values
* @param string|null $index The where key
* @param int $batchSize The size of the batch to run
* @param bool $returnSQL True means SQL is returned, false will execute the query
*
* @return mixed Number of rows affected or FALSE on failure
* @return false|int|string[] Number of rows affected or FALSE on failure, SQL array when testMode
*
* @throws DatabaseException
*/
abstract protected function doUpdateBatch(?array $set = null, ?string $index = null, int $batchSize = 100, bool $returnSQL = false);

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

/**
* Permanently deletes all rows that have been marked as deleted
* through soft deletes (deleted = 1)
* This methods works only with dbCalls
* Permanently deletes all rows that have been marked as deleted.
* through soft deletes (deleted = 1).
* This method works only with dbCalls.
*
* @return bool|string Returns a string if in test mode.
*/
Expand All @@ -424,31 +425,31 @@ abstract protected function doPurgeDeleted();
/**
* Works with the find* methods to return only the rows that
* have been deleted.
* This methods works only with dbCalls
* This method works only with dbCalls.
*/
abstract protected function doOnlyDeleted();

/**
* Compiles a replace and runs the query
* This methods works only with dbCalls
* Compiles a replace and runs the query.
* This method works only with dbCalls.
*
* @param array|null $data Data
* @param bool $returnSQL Set to true to return Query String
*
* @return mixed
* @return BaseResult|false|Query|string
*/
abstract protected function doReplace(?array $data = null, bool $returnSQL = false);

/**
* Grabs the last error(s) that occurred from the Database connection.
* This methods works only with dbCalls
* This method works only with dbCalls.
*
* @return array|null
*/
abstract protected function doErrors();

/**
* Returns the id value for the data array or object
* Returns the id value for the data array or object.
*
* @param array|object $data Data
*
Expand All @@ -459,8 +460,8 @@ abstract protected function doErrors();
abstract protected function idValue($data);

/**
* Public getter to return the id value using the idValue() method
* For example with SQL this will return $data->$this->primaryKey
* Public getter to return the id value using the idValue() method.
* For example with SQL this will return $data->$this->primaryKey.
*
* @param array|object $data
*
Expand All @@ -475,18 +476,18 @@ public function getIdValue($data)

/**
* Override countAllResults to account for soft deleted accounts.
* This methods works only with dbCalls
* This method works only with dbCalls.
*
* @param bool $reset Reset
* @param bool $test Test
*
* @return mixed
* @return int|string
*/
abstract public function countAllResults(bool $reset = true, bool $test = false);

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

/**
* Fetches the row of database
* Fetches the row of database.
*
* @param array|int|string|null $id One primary key or an array of primary keys
*
Expand Down Expand Up @@ -538,7 +539,7 @@ public function find($id = null)
}

/**
* Fetches the column of database
* Fetches the column of database.
*
* @param string $columnName Column Name
*
Expand Down Expand Up @@ -667,8 +668,8 @@ public function save($data): bool
}

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

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

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

/**
* Compiles an update and runs the query
* Compiles an update and runs the query.
*
* @param array|null $set An associative array of update values
* @param string|null $index The where key
* @param int $batchSize The size of the batch to run
* @param bool $returnSQL True means SQL is returned, false will execute the query
*
* @return mixed Number of rows affected or FALSE on failure
* @return false|int|string[] Number of rows affected or FALSE on failure, SQL array when testMode
*
* @throws DatabaseException
* @throws ReflectionException
Expand Down Expand Up @@ -953,7 +954,7 @@ public function updateBatch(?array $set = null, ?string $index = null, int $batc
}

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

/**
* Permanently deletes all rows that have been marked as deleted
* through soft deletes (deleted = 1)
* through soft deletes (deleted = 1).
*
* @return mixed
* @return bool|string Returns a string if in test mode.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are annoying to support. I would like to see in v5 some kind of Database Proxy that passes requests through to the driver for most cases but "captures" the actual SQL query for Test Mode. I think that would be a much better approach than trying to adjust all our return types.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the return types are not good, should be bool only.

*/
public function purgeDeleted()
{
Expand Down Expand Up @@ -1038,12 +1039,12 @@ public function onlyDeleted()
}

/**
* Compiles a replace and runs the query
* Compiles a replace and runs the query.
*
* @param array|null $data Data
* @param bool $returnSQL Set to true to return Query String
*
* @return mixed
* @return BaseResult|false|Query|string
*/
public function replace(?array $data = null, bool $returnSQL = false)
{
Expand All @@ -1063,6 +1064,7 @@ public function replace(?array $data = null, bool $returnSQL = false)
* Grabs the last error(s) that occurred. If data was validated,
* it will first check for errors there, otherwise will try to
* grab the last error from the Database connection.
*
* The return array should be in the following format:
* ['source' => 'message']
*
Expand Down Expand Up @@ -1170,11 +1172,11 @@ protected function doProtectFields(array $data): array
}

/**
* Sets the date or current date if null value is passed
* Sets the date or current date if null value is passed.
*
* @param int|null $userData An optional PHP timestamp to be converted.
*
* @return mixed
* @return int|string
*
* @throws ModelException
*/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👇#6815

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I sent a PR #6825

Expand Down Expand Up @@ -1220,7 +1222,7 @@ protected function intToDate(int $value)
}

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

/**
* Returns the model's define validation messages so they
* Returns the model's define validation messages, so they
kenjis marked this conversation as resolved.
Show resolved Hide resolved
* can be used elsewhere, if needed.
*/
public function getValidationMessages(): array
Expand Down Expand Up @@ -1454,14 +1456,14 @@ public function allowCallbacks(bool $val = true)
*
* Each $eventData array MUST have a 'data' key with the relevant
* data for callback methods (like an array of key/value pairs to insert
* or update, an array of results, etc)
* or update, an array of results, etc.)
*
* If callbacks are not allowed then returns $eventData immediately.
*
* @param string $event Event
* @param array $eventData Event Data
*
* @return mixed
* @return array
*
* @throws DataException
*/
Expand Down Expand Up @@ -1513,14 +1515,14 @@ public function asObject(string $class = 'object')
}

/**
* Takes a class and returns an array of it's public and protected
* Takes a class and returns an array of its public and protected
* properties as an array suitable for use in creates and updates.
* This method uses objectToRawArray() internally and does conversion
* to string on all Time instances
*
* @param object|string $data Data
* @param bool $onlyChanged Only Changed Property
* @param bool $recursive If true, inner entities will be casted as array as well
* @param bool $recursive If true, inner entities will be cast as array as well
*
* @return array Array
*
Expand Down Expand Up @@ -1579,7 +1581,7 @@ protected function objectToRawArray($data, bool $onlyChanged = true, bool $recur
}

/**
* Transform data to array
* Transform data to array.
*
* @param array|object|null $data Data
* @param string $type Type of data (insert|update)
Expand Down
Loading