Expand documentation for the delete method with usage examples and restrictions

Author: shvlv

README.md

@@ -874,12 +874,74 @@ DB::table('table_name')
 
 The `QueryBuilder::delete` method may be used to delete records from the table.
 
+Unlike WordPress's `$wpdb->delete()` method, this implementation generates and executes a DELETE SQL statement directly, which allows for advanced features like ORDER BY and LIMIT.
+
+#### Basic delete with WHERE
+
 ```php
 DB::table('posts')
     ->where('post_author', 1)
     ->delete();
 ```
 
+#### Delete with LIMIT
+
+Limit the number of rows to delete:
+
+```php
+// Delete only the first 10 draft posts
+DB::table('posts')
+    ->where('post_status', 'draft')
+    ->limit(10)
+    ->delete();
+```
+
+#### Delete with ORDER BY and LIMIT
+
+Control which rows are deleted when using LIMIT:
+
+```php
+// Delete the 100 oldest posts in trash
+DB::table('posts')
+    ->where('post_status', 'trash')
+    ->orderBy('post_date', 'ASC')
+    ->limit(100)
+    ->delete();
+```
+
+#### Delete with LIKE patterns
+
+Use pattern matching to delete rows:
+
+```php
+// Delete all posts with titles starting with "Draft:"
+DB::table('posts')
+    ->whereLike('post_title', 'Draft:%')
+    ->delete();
+```
+
+#### Delete with complex WHERE conditions
+
+Combine multiple WHERE clauses for precise deletion:
+
+```php
+// Delete auto-draft pages with IDs between 1 and 1000
+DB::table('posts')
+    ->where('post_type', 'page')
+    ->where('post_status', 'auto-draft')
+    ->whereBetween('ID', 1, 1000)
+    ->delete();
+
+// Delete posts using whereIn
+DB::table('posts')
+    ->whereIn('ID', [5, 10, 15, 20])
+    ->delete();
+```
+
+**Important restrictions:**
+- Table aliases in the FROM clause may not be supported on older database versions (MySQL < 8.0.24, MariaDB < 11.6). Avoid using table aliases when calling `delete()`.
+- JOINs are not supported in DELETE statements with this implementation.
+
 
 ### Get
 

src/DB/QueryBuilder/Concerns/CRUD.php

@@ -75,10 +75,53 @@ public function upsert( $data, $match = [], $format = null ) {
 	}
 
 	/**
+	 * Delete rows from the database.
+	 *
+	 * Unlike WordPress's $wpdb->delete() method, this implementation generates and executes
+	 * a DELETE SQL statement directly, which allows for advanced features like ORDER BY and LIMIT.
+	 *
+	 * Supports:
+	 * - WHERE clauses (including whereLike, whereIn, whereBetween, etc.)
+	 * - ORDER BY for controlling which rows are deleted first
+	 * - LIMIT to restrict the number of rows deleted
+	 * - Complex WHERE conditions (AND, OR, nested queries)
+	 *
+	 * Usage examples:
+	 * ```php
+	 * // Simple delete with WHERE
+	 * DB::table('posts')->where('post_status', 'draft')->delete();
+	 *
+	 * // Delete with LIMIT (delete only 10 rows)
+	 * DB::table('posts')->where('post_type', 'temp')->limit(10)->delete();
+	 *
+	 * // Delete oldest posts first using ORDER BY and LIMIT
+	 * DB::table('posts')
+	 *     ->where('post_status', 'trash')
+	 *     ->orderBy('post_date', 'ASC')
+	 *     ->limit(100)
+	 *     ->delete();
+	 *
+	 * // Delete with LIKE pattern
+	 * DB::table('posts')->whereLike('post_title', 'Draft:%')->delete();
+	 *
+	 * // Delete with multiple conditions
+	 * DB::table('posts')
+	 *     ->where('post_type', 'page')
+	 *     ->where('post_status', 'auto-draft')
+	 *     ->whereBetween('ID', 1, 1000)
+	 *     ->delete();
+	 * ```
+	 *
+	 * Restrictions:
+	 * - Table aliases in the FROM clause may not be supported on older database versions
+	 *   (MySQL < 8.0.24, MariaDB < 11.6). Avoid using table aliases with delete().
+	 * - JOINs are not supported in DELETE statements with this implementation
+	 *
 	 * @since 1.0.0
 	 *
-	 * @return false|int
+	 * @return false|int Number of rows deleted, or false on error.
 	 *
+	 * @see QueryBuilder::deleteSQL() for the SQL generation logic
 	 */
 	public function delete() {
 		return DB::query( $this->deleteSQL() );

src/DB/QueryBuilder/QueryBuilder.php

@@ -84,7 +84,7 @@ public function deleteSQL() {
 	 *
 	 * @return string SQL query.
 	 */
-	private function buildSQL( $sql ){
+	private function buildSQL( $sql ) {
 		return str_replace(
 			[ '   ', '  ' ],
 			' ',