php_db_components_pack/sources/traits/Database/DatabaseQueryExecute.php

<?php
    
    /**
     * @noinspection SqlNoDataSourceInspection
     */
    
    namespace goodboyalex\php_db_components_pack\traits\Database;
    
    use Exception;
    use PDO;
    use PDOException;
    
    /**
     * Трейт для работы с запросами к базе данных типа Query и Execute.
     *
     * @author Александр Бабаев
     * @package php_db_components_pack
     * @version 1.0
     * @since 1.0
     * @see PDO
     */
    trait DatabaseQueryExecute
    {
        /**
         * Выполнить запрос к базе данных и вернуть ассоциированный массив.
         *
         * @param string $query Запрос SQL.
         * @param array $params Параметры запроса.
         *
         * @return array|false Ассоциативный массив с результатом запроса или <code>false</code> в случае ошибки.
         */
        public function Query (string $query, array $params = []): array|false
        {
            // Проверяем, что это именно запрос SELECT
            if (!preg_match('/^\s*SELECT\s+/i', trim($query))) {
                $this->HandleException(new Exception("Некорректный запрос для метода Query() / Incorrect request for the Query() method: '$query'. Используйте метод Execute() для небезопасных операций / Use the Execute() method for unsafe operations."),
                    false);
                return false;
            }
            
            // Подготавливаем запрос
            $stmt = $this->DataBaseHandle->prepare($query, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
            
            // Если запрос не подготовлен
            if ($stmt === false) {
                // - обрабатываю ошибку
                $this->HandleException(new Exception("Ошибка подготовки SQL-запроса / SQL query preparation error"),
                    false);
                
                // - прерываю выполнение
                return false;
            }
            
            try {
                // Выполняем запрос
                $stmt->execute($params);
            }
            catch (PDOException $e) {
                // - в случае ошибки, обрабатываю её
                $this->HandleException(new Exception("Ошибка выполнения SQL-запроса / SQL query execution error: " .
                    $e->getMessage()), false);
                
                // - прерываю выполнение
                return false;
            }
            
            // Если получены данные, то возвращаю их, в противном случае возвращаю пустой массив
            return ($data = $stmt->fetchAll(PDO::FETCH_ASSOC)) !== [] ? $data : [];
        }
        
        /**
         * Получить первую строку результата запроса.
         *
         * @param string $query Запрос SQL.
         * @param array $params Параметры запроса.
         *
         * @return array|false Первая строка результата запроса или <code>false</code> в случае ошибки.
         */
        public function QueryFirst (string $query, array $params = []): array|false
        {
            // Выполняем запрос
            $rows = $this->Query($query, $params);
            
            // Если получены данные, то возвращаю первую строку, в противном случае возвращаю false
            return is_array($rows) ? reset($rows) : false;
        }
        
        /**
         * Получить последнюю строку результата запроса.
         *
         * @param string $query Запрос SQL.
         * @param array $params Параметры запроса.
         *
         * @return array|false Последняя строка результата запроса или <code>false</code> в случае ошибки.
         */
        public function QueryLast (string $query, array $params = []): array|false
        {
            // Выполняем запрос
            $rows = $this->Query($query, $params);
            
            // Если получены данные, то возвращаю последнюю строку, в противном случае возвращаю false
            return is_array($rows) ? end($rows) : false;
        }
        
        /**
         * Выполнить запрос, который изменяет данные в базе данных (INSERT, UPDATE, DELETE).
         *
         * @param string $query Запрос SQL.
         * @param array $params Параметры запроса.
         *
         * @return int|false Количество затронутых строк или <code>false</code> в случае ошибки.
         */
        public function Execute (string $query, array $params = []): int|false
        {
            // Проверяем, что это не запрос SELECT
            if (preg_match('/^\s*SELECT\s+/i', trim($query))) {
                // - выдаю ошибку
                $this->HandleException(new Exception("Некорректный запрос для метода Execute() / Incorrect request for the Execute() method: '$query'. Используйте метод Query() для безопасного выбора данных / Use the Query() method to select data safely."),
                    false);
                
                // - аннулирую результат
                return false;
            }
            
            try {
                // Если это простой запрос без параметров
                if (empty($params))
                    // - то просто выполняю его
                    return $this->DataBaseHandle->exec($query);
                else {
                    // - в противном случае, подготавливаем запрос с параметрами
                    $stmt = $this->DataBaseHandle->prepare($query, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
                    
                    // - если подготовили неуспешно
                    if (!$stmt) {
                        // -- то формируем ошибку
                        $this->HandleException(new PDOException("Ошибка подготовки SQL-запроса / SQL query preparation error"),
                            false);
                        
                        // -- возвращаем неудачу
                        return false;
                    }
                    
                    // - выполняем запрос
                    $executed = $stmt->execute($params);
                    
                    // - если успешно, то возвращаем количество изменённых строк, иначе - false
                    return ($executed) ? $stmt->rowCount() : false;
                }
            }
            catch (PDOException $e) {
                // - в случае ошибки, обрабатываю её
                $this->HandleException($e, false);
                
                // - прерываю выполнение
                return false;
            }
        }
    }