Merge pull request #8277 from kenjis/docs-add-db-utils-missing-methods

docs: add DBUtils missing methods

Author: kenjis

user_guide_src/source/database/utilities.rst

@@ -30,6 +30,73 @@ parameter.
 Using the Database Utilities
 ****************************
 
+Retrieve List of Database Names
+================================
+
+Returns an array of database names:
+
+.. literalinclude:: utilities/004.php
+    :lines: 2-
+
+Determine If a Database Exists
+==============================
+
+Sometimes it's helpful to know whether a particular database exists.
+Returns a boolean ``true``/``false``. Usage example:
+
+.. literalinclude:: utilities/005.php
+    :lines: 2-
+
+.. note:: Replace ``database_name`` with the name of the database you are
+    looking for. This method is case sensitive.
+
+Optimize a Table
+================
+
+Permits you to optimize a table using the table name specified in the
+first parameter. Returns ``true``/``false`` based on success or failure:
+
+.. literalinclude:: utilities/006.php
+    :lines: 2-
+
+.. note:: Not all database platforms support table optimization. It is
+    mostly for use with MySQL.
+
+Optimize a Database
+===================
+
+Permits you to optimize the database your DB class is currently
+connected to. Returns an array containing the DB status messages or
+``false`` on failure:
+
+.. literalinclude:: utilities/008.php
+    :lines: 2-
+
+.. note:: Not all database platforms support database optimization. It
+    it is mostly for use with MySQL.
+
+Export a Query Result as a CSV File
+===================================
+
+Permits you to generate a CSV file from a query result. The first
+parameter of the method must contain the result object from your
+query. Example:
+
+.. literalinclude:: utilities/009.php
+    :lines: 2-
+
+The second, third, and fourth parameters allow you to set the delimiter
+newline, and enclosure characters respectively. By default commas are
+used as the delimiter, ``"\n"`` is used as a new line, and a double-quote
+is used as the enclosure. Example:
+
+.. literalinclude:: utilities/010.php
+    :lines: 2-
+
+.. important:: This method will NOT write the CSV file for you. It
+    simply creates the CSV layout. If you need to write the file
+    use the :php:func:`write_file()` helper.
+
 Export a Query Result as an XML Document
 ========================================
 

user_guide_src/source/database/utilities/004.php

@@ -0,0 +1,9 @@
+<?php
+
+$dbutil = \Config\Database::utils();
+
+$dbs = $dbutil->listDatabases();
+
+foreach ($dbs as $db) {
+    echo $db;
+}

user_guide_src/source/database/utilities/005.php

@@ -0,0 +1,7 @@
+<?php
+
+$dbutil = \Config\Database::utils();
+
+if ($dbutil->databaseExists('database_name')) {
+    // some code...
+}

user_guide_src/source/database/utilities/006.php

@@ -0,0 +1,7 @@
+<?php
+
+$dbutil = \Config\Database::utils();
+
+if ($dbutil->optimizeTable('table_name')) {
+    echo 'Success!';
+}

user_guide_src/source/database/utilities/008.php

@@ -0,0 +1,9 @@
+<?php
+
+$dbutil = \Config\Database::utils();
+
+$result = $dbutil->optimizeDatabase();
+
+if ($result !== false) {
+    print_r($result);
+}

user_guide_src/source/database/utilities/009.php

@@ -0,0 +1,8 @@
+<?php
+
+$db     = db_connect();
+$dbutil = \Config\Database::utils();
+
+$query = $db->query('SELECT * FROM mytable');
+
+echo $dbutil->getCSVFromResult($query);

user_guide_src/source/database/utilities/010.php

@@ -0,0 +1,12 @@
+<?php
+
+$db     = db_connect();
+$dbutil = \Config\Database::utils();
+
+$query = $db->query('SELECT * FROM mytable');
+
+$delimiter = ',';
+$newline   = "\r\n";
+$enclosure = '"';
+
+echo $dbutil->getCSVFromResult($query, $delimiter, $newline, $enclosure);