Deprecate unnecessary getter methods

devtheorem · Oct 6, 2024 · 22f683b · 22f683b
1 parent 09f1530
commit 22f683b
Show file tree

Hide file tree

Showing 21 changed files with 170 additions and 120 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [6.3.0] - 2024-10-05
+### Deprecated
+- Unnecessary getter methods (in `InsertResult`, `BulkInsertResult`, `SqlParams`, and `SqlException`).
 
 ## [6.2.0] - 2022-03-14
 ### Added
@@ -291,7 +293,7 @@ insert a single row.
 ## [1.0.0] - 2014-02-20
 - Initial release
 
-[Unreleased]: https://github.com/theodorejb/peachy-sql/compare/v6.2.0...HEAD
+[6.3.0]: https://github.com/theodorejb/peachy-sql/compare/v6.2.0...v6.3.0
 [6.2.0]: https://github.com/theodorejb/peachy-sql/compare/v6.1.0...v6.2.0
 [6.1.0]: https://github.com/theodorejb/peachy-sql/compare/v6.0.3...v6.1.0
 [6.0.3]: https://github.com/theodorejb/peachy-sql/compare/v6.0.2...v6.0.3

diff --git a/README.md b/README.md
@@ -27,7 +27,7 @@ $peachySql = new PeachySQL\SqlServer($sqlSrvConn);
 ```
 
 After instantiation, arbitrary statements can be prepared by passing a
-SQL string and array of bound parameters to the `prepare` method:
+SQL string and array of bound parameters to the `prepare()` method:
 
 ```php
 $sql = "UPDATE Users SET fname = ? WHERE user_id = ?";
@@ -46,7 +46,7 @@ $stmt->close();
 ```
 
 Most of the time prepared statements only need to be executed a single time.
-To make this easier, PeachySQL provides a `query` method which automatically
+To make this easier, PeachySQL provides a `query()` method which automatically
 prepares, executes, and closes a statement after results are retrieved:
 
 ```php
@@ -55,20 +55,20 @@ $result = $peachySql->query($sql, ['theo%', 'b%']);
 echo json_encode($result->getAll());
 ```
 
-Both `prepare` and `query` return a `Statement` object with the following methods:
+Both `prepare()` and `query()` return a `Statement` object with the following methods:
 
-| Method        | Behavior                                                                                                                                                                    |
-|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `execute`     | Executes the prepared statement (automatically called when using `query`).                                                                                                  |
-| `getIterator` | Returns a [Generator](http://php.net/manual/en/language.generators.overview.php) object which can be used to iterate over large result sets without caching them in memory. |
-| `getAll`      | Returns all selected rows as an array of associative arrays.                                                                                                                |
-| `getFirst`    | Returns the first selected row as an associative array (or `null` if no rows were selected).                                                                                |
-| `getAffected` | Returns the number of rows affected by the query.                                                                                                                           |
-| `close`       | Closes the prepared statement and frees its resources (automatically called when using `query`).                                                                            |
+| Method          | Behavior                                                                                                         |
+|-----------------|------------------------------------------------------------------------------------------------------------------|
+| `execute()`     | Executes the prepared statement (automatically called when using `query()`).                                     |
+| `getIterator()` | Returns a `Generator` object which can be used to iterate over large result sets without caching them in memory. |
+| `getAll()`      | Returns all selected rows as an array of associative arrays.                                                     |
+| `getFirst()`    | Returns the first selected row as an associative array (or `null` if no rows were selected).                     |
+| `getAffected()` | Returns the number of rows affected by the query.                                                                |
+| `close()`       | Closes the prepared statement and frees its resources (automatically called when using `query()`).               |
 
-If using MySQL, the `Mysql\Statement` object additionally includes a `getInsertId` method.
+If using MySQL, the `Mysql\Statement` object additionally includes a `getInsertId()` method.
 
-Internally, `getAll` and `getFirst` are implemented using `getIterator`.
+Internally, `getAll()` and `getFirst()` are implemented using `getIterator()`.
 As such they can only be called once for a given statement.
 
 ### Shorthand methods
@@ -81,15 +81,15 @@ always use bound parameters for values, and column names are automatically escap
 
 #### select / selectFrom
 
-The `selectFrom` method takes a single string argument containing a SQL SELECT query.
+The `selectFrom()` method takes a single string argument containing a SQL SELECT query.
 It returns an object with three chainable methods:
 
-1. `where`
-2. `orderBy`
-3. `offset`
+1. `where()`
+2. `orderBy()`
+3. `offset()`
 
-Additionally, the object has a `getSqlParams` method which builds the select query,
-and a `query` method which executes the query and returns a `Statement` object.
+Additionally, the object has a `getSqlParams()` method which builds the select query,
+and a `query()` method which executes the query and returns a `Statement` object.
 
 ```php
 // select all columns and rows in a table, ordered by last name and then first name
@@ -105,8 +105,8 @@ $rows = $peachySql->selectFrom("SELECT * FROM Users u INNER JOIN Customers c ON
     ->query()->getIterator();
 ```
 
-The `select` method works the same as `selectFrom`, but takes a `SqlParams` object
-rather than a string and supports bound params in the select query:
+The `select()` method works the same as `selectFrom()`, but takes a `SqlParams`
+object rather than a string and supports bound params in the select query:
 
 ```php
 use PeachySQL\QueryBuilder\SqlParams;
@@ -123,15 +123,16 @@ $sql = "
     FROM Users u
     INNER JOIN UserVisits uv ON uv.user_id = u.user_id";
 
-$date = new DateTime('2 months ago');
-$rows = $peachySql->select(new SqlParams($sql, $date->format('Y-m-d')))
+$date = (new DateTime('2 months ago'))->format('Y-m-d');
+
+$rows = $peachySql->select(new SqlParams($sql, [$date]))
     ->where(['u.status' => 'verified'])
     ->query()->getIterator();
 ```
 
 ##### Where clause generation
 
-In addition to passing basic column => value arrays to the `where` method, you can
+In addition to passing basic column => value arrays to the `where()` method, you can
 specify more complex conditions by using arrays as values. For example, passing
 `['col' => ['lt' => 15, 'gt' => 5]]` would generate the condition `WHERE col < 15 AND col > 5`.
 
@@ -157,22 +158,22 @@ IN(...) or NOT IN(...) condition, respectively. Passing a list with the `lk`, `n
 
 #### insertRow
 
-The `insertRow` method allows a single row to be inserted from an associative array.
-It returns an `InsertResult` object with `getId` and `getAffected` methods.
+The `insertRow()` method allows a single row to be inserted from an associative array.
+It returns an `InsertResult` object with readonly `id` and `affected` properties.
 
 ```php
 $userData = [
     'fname' => 'Donald',
     'lname' => 'Chamberlin'
 ];
 
-$id = $peachySql->insertRow('Users', $userData)->getId();
+$id = $peachySql->insertRow('Users', $userData)->id;
 ```
 
 #### insertRows
 
-The `insertRows` method makes it possible to bulk-insert multiple rows from an array.
-It returns a `BulkInsertResult` object with `getIds`, `getAffected`, and `getQueryCount` methods.
+The `insertRows()` method makes it possible to bulk-insert multiple rows from an array.
+It returns a `BulkInsertResult` object with readonly `ids`, `affected`, and `queryCount` properties.
 
 ```php
 $userData = [
@@ -191,32 +192,32 @@ $userData = [
 ];
 
 $result = $peachySql->insertRows('Users', $userData);
-$ids = $result->getIds(); // e.g. [64, 65, 66]
-$affected = $result->getAffected(); // 3
-$queries = $result->getQueryCount(); // 1
+$ids = $result->ids; // e.g. [64, 65, 66]
+$affected = $result->affected; // 3
+$queries = $result->queryCount; // 1
 ```
 
-An optional third parameter can be passed to `insertRows` to override the default
+An optional third parameter can be passed to `insertRows()` to override the default
 identity increment value:
 
 ```php
 $result = $peachySql->insertRows('Users', $userData, 2);
-$ids = $result->getIds(); // e.g. [64, 66, 68]
+$ids = $result->ids; // e.g. [64, 66, 68]
 ```
 
 Note: SQL Server allows a maximum of 1,000 rows to be inserted at a time, and limits
 individual queries to 2,099 or fewer bound parameters. MySQL supports a maximum of
 65,536 bound parameters per query. These limits can be easily reached when attempting
 to bulk-insert hundreds or thousands of rows at a time. To avoid these limits, the
-`insertRows` method automatically splits large queries into batches to efficiently
-handle any number of rows (`getQueryCount` returns the number of required batches).
+`insertRows()` method automatically splits large queries into batches to efficiently
+handle any number of rows (`queryCount` contains the number of required batches).
 
 #### updateRows and deleteFrom
 
-The `updateRows` method takes three arguments: a table name, an associative array of
+The `updateRows()` method takes three arguments: a table name, an associative array of
 columns/values to update, and a WHERE array to filter which rows are updated.
 
-The `deleteFrom` method takes a table name and a WHERE array to filter the rows to delete.
+The `deleteFrom()` method takes a table name and a WHERE array to filter the rows to delete.
 
 Both methods return the number of affected rows.
 
@@ -231,14 +232,14 @@ $userTable->deleteFrom('Users', ['user_id' => [1, 2, 3]]);
 
 ### Transactions
 
-Call the `begin` method to start a transaction. `prepare`, `execute`, `query`
+Call the `begin()` method to start a transaction. `prepare()`, `execute()`, `query()`
 and any of the shorthand methods can then be called as needed, before committing
-or rolling back the transaction with `commit` or `rollback`.
+or rolling back the transaction with `commit()` or `rollback()`.
 
 ## Author
 
 Theodore Brown  
-<http://theodorejb.me>
+<https://theodorejb.me>
 
 ## License
 

diff --git a/lib/BaseStatement.php b/lib/BaseStatement.php
@@ -10,11 +10,13 @@
 abstract class BaseStatement
 {
     protected int $affected = 0;
+    /**
+     * True if the statement was created using `prepare()`
+     */
     protected bool $usedPrepare;
     protected string $query;
     protected array $params;
 
-    // $usedPrepare should be true if the statement was created using `prepare`
     public function __construct(bool $usedPrepare, string $query, array $params)
     {
         $this->usedPrepare = $usedPrepare;

diff --git a/lib/BulkInsertResult.php b/lib/BulkInsertResult.php
@@ -6,13 +6,25 @@
 
 /**
  * Object returned when performing bulk insert queries
+ * @readonly
  */
 class BulkInsertResult
 {
-    /** @var list<int> */
-    private array $ids;
-    private int $affected;
-    private int $queryCount;
+    /**
+     * The IDs of the inserted rows
+     * @var list<int>
+     */
+    public array $ids;
+
+    /**
+     * The number of affected rows
+     */
+    public int $affected;
+
+    /**
+     * The number of individual queries used to perform the bulk insert
+     */
+    public int $queryCount;
 
     /**
      * @param list<int> $ids
@@ -26,7 +38,9 @@ public function __construct(array $ids, int $affected, int $queryCount = 1)
 
     /**
      * Returns the IDs of the inserted rows
+     * @deprecated Use readonly property instead
      * @return list<int>
+     * @api
      */
     public function getIds(): array
     {
@@ -35,6 +49,8 @@ public function getIds(): array
 
     /**
      * Returns the number of affected rows
+     * @deprecated Use readonly property instead
+     * @api
      */
     public function getAffected(): int
     {
@@ -43,6 +59,8 @@ public function getAffected(): int
 
     /**
      * Returns the number of individual queries used to perform the bulk insert
+     * @deprecated Use readonly property instead
+     * @api
      */
     public function getQueryCount(): int
     {

diff --git a/lib/InsertResult.php b/lib/InsertResult.php
@@ -6,11 +6,19 @@
 
 /**
  * Object returned when inserting a single row
+ * @readonly
  */
 class InsertResult
 {
-    private int $id;
-    private int $affected;
+    /**
+     * The ID of the inserted row (0 if the row doesn't have an auto-incremented ID)
+     */
+    public int $id;
+
+    /**
+     * The number of affected rows
+     */
+    public int $affected;
 
     public function __construct(int $id, int $affected)
     {
@@ -21,6 +29,8 @@ public function __construct(int $id, int $affected)
     /**
      * Returns the ID of the inserted row
      * @throws \Exception if the row doesn't have an auto-incremented ID
+     * @deprecated Use readonly property instead
+     * @api
      */
     public function getId(): int
     {
@@ -33,6 +43,8 @@ public function getId(): int
 
     /**
      * Returns the number of affected rows
+     * @deprecated Use readonly property instead
+     * @api
      */
     public function getAffected(): int
     {

diff --git a/lib/Mysql.php b/lib/Mysql.php
@@ -123,7 +123,7 @@ public function query(string $sql, array $params = []): Statement
     protected function insertBatch(string $table, array $colVals, int $identityIncrement = 1): BulkInsertResult
     {
         $sqlParams = (new Insert($this->options))->buildQuery($table, $colVals);
-        $result = $this->query($sqlParams->getSql(), $sqlParams->getParams());
+        $result = $this->query($sqlParams->sql, $sqlParams->params);
         $firstId = $result->getInsertId(); // ID of first inserted row, or zero if no insert ID
 
         if ($firstId) {
@@ -138,7 +138,7 @@ protected function insertBatch(string $table, array $colVals, int $identityIncre
 
     /**
      * To bind parameters in mysqli, the type of each parameter must be specified.
-     * See http://php.net/manual/en/mysqli-stmt.bind-param.php.
+     * See https://www.php.net/manual/en/mysqli-stmt.bind-param.php.
      * Returns a string containing the type character for each parameter.
      */
     private static function getMysqlParamTypes(array $params): string

diff --git a/lib/PeachySql.php b/lib/PeachySql.php
@@ -72,9 +72,8 @@ public function select(SqlParams $query): QueryableSelector
     public function insertRow(string $table, array $colVals): InsertResult
     {
         $result = $this->insertBatch($table, [$colVals]);
-        $ids = $result->getIds();
-        $id = empty($ids) ? 0 : $ids[0];
-        return new InsertResult($id, $result->getAffected());
+        $ids = $result->ids;
+        return new InsertResult($ids ? $ids[0] : 0, $result->affected);
     }
 
     /**
@@ -90,8 +89,8 @@ public function insertRows(string $table, array $colVals, int $identityIncrement
 
         foreach ($batches as $batch) {
             $result = $this->insertBatch($table, $batch, $identityIncrement);
-            $ids = array_merge($ids, $result->getIds());
-            $affected += $result->getAffected();
+            $ids = array_merge($ids, $result->ids);
+            $affected += $result->affected;
         }
 
         return new BulkInsertResult($ids, $affected, count($batches));
@@ -106,7 +105,7 @@ public function updateRows(string $table, array $set, array $where): int
     {
         $update = new Update($this->options);
         $sqlParams = $update->buildQuery($table, $set, $where);
-        return $this->query($sqlParams->getSql(), $sqlParams->getParams())->getAffected();
+        return $this->query($sqlParams->sql, $sqlParams->params)->getAffected();
     }
 
     /**
@@ -118,6 +117,6 @@ public function deleteFrom(string $table, array $where): int
     {
         $delete = new Delete($this->options);
         $sqlParams = $delete->buildQuery($table, $where);
-        return $this->query($sqlParams->getSql(), $sqlParams->getParams())->getAffected();
+        return $this->query($sqlParams->sql, $sqlParams->params)->getAffected();
     }
 }
diff --git a/lib/QueryBuilder/Delete.php b/lib/QueryBuilder/Delete.php
@@ -17,7 +17,7 @@ class Delete extends Query
     public function buildQuery(string $table, array $where): SqlParams
     {
         $whereClause = $this->buildWhereClause($where);
-        $sql = "DELETE FROM {$table}" . $whereClause->getSql();
-        return new SqlParams($sql, $whereClause->getParams());
+        $sql = "DELETE FROM {$table}" . $whereClause->sql;
+        return new SqlParams($sql, $whereClause->params);
     }
 }