README

安装

要安装 dlunamontilla/dltools，需要先安装 composer。若要安装 composer，请访问其官方网站 https://getcomposer.org.cn 并按照说明进行操作。

composer require dlunamontilla/dltools

重要：必须先安装 composer 才能安装此工具。若要安装 composer，请访问其官方网站 https://getcomposer.org.cn 并按照说明进行操作。

特性

该工具包括以下功能

• 查询构建器。
• 模型。
• 静态类型环境变量读取，同时支持读取环境变量文件。

要为应用程序与数据库引擎进行认证设置环境变量，创建一个名为 .env.type 的文件，并添加以下行

# Indica si la aplicación debe correr o no en producción:
DL_PRODUCTION: boolean = false

# Servidor de la base de datos:
DL_DATABASE_HOST: string = "localhost"

# Puerto del motor de la base de datos:
DL_DATABASE_PORT: integer = 3306

# Usuario de la base de datos:
DL_DATABASE_USER: string = "tu-usuario"

# Contraseña de la base de datos:
DL_DATABASE_PASSWORD: string = "tu-contraseña"

# Nombre de la base de datos:
DL_DATABASE_NAME: string = "tu-base-de-datos"

# Codificación de caracteres de la base de datos. Si no se define, 
# entonces, el valor por defecto serà `utf8`:
DL_DATABASE_CHARSET: string = "utf8"

# Colación del motor de base de datos. Si no se define, el valor por
# defecto será `utf8_general_ci`:
DL_DATABASE_COLLATION: string = "utf8_general_ci"

# Motor de base de datos. Si no se define esta variable, el valor
# por defecto será `mysql`:
DL_DATABASE_DRIVE: string = "mysql"

如果还需要发送电子邮件，请复制以下行

# Usuario de correo electrónico. Tome en cuenta que no debe colocar
# comillas de ningún tipo, porque no se evaluaría si es un correo:
MAIL_USERNAME: email = no-reply@example.com

# Contraseña del correo electrónico:
MAIL_PASSWORD: string = "Contraseña de correo"

# Puerto del servidor SMTP con certificado SSL para tu correo 
# electrónico:
MAIL_PORT: integer = 465

# Nombre de la empresa que envía el correo a través de su web
# o aplicación:
MAIL_COMPANY_NAME: string = "Empresa, marca o tu marca personal"

# Correo de contacto:
MAIL_CONTACT: email = contact@example.com

重要：为了语法高亮，请安装 DL Typed Environment

如果需要安装 Google API 密钥以安装 reCAPTCHA，请在 .env.type 文件中添加以下行

# Estas variables son opcionales. Si desea establecer un reCAPTCHA
# de Google, puedes definirlas aquí:
G_SECRET_KEY: string = "<tu-llave-privada>"
G_SITE_KEY: string = "<tu-llave-del-sitio>"

工具使用

模型

如果要在模型中创建一个扩展类，请编写以下代码

<?php

namespace TuApp\Models;

use DLTools\Database\Model;

class Products extends Model {}

其中 Products 是引用 products 表的类。如果应用程序的表使用了前缀，例如 wp_，则需要在 .env.type 文件中定义该前缀

DL_PREFIX: string = "wp_"

或者，如果您定义的环境变量不使用任何文件，请确保在您的托管服务提供商（例如 Heroku）中定义它，变量名应为

DL_PREFIX = "wp_"

如果要在 Products 模型中设置不同的表名，只需按以下方式定义即可

class Products extends Model {

  protected static ?string $table = "otra_tabla";
}

此外，它还提供了一些可用于与数据库交互的方法，例如，您可以从控制器中调用这些方法

  final class TestController extends Controller {

    /**
     * Ejemplo de interacción con el modelo `Products`.
     * 
     * @return array
     */
    public function products(): array {
      new Products();

      /**
       * Devuelve, máximo 100 registros
       * 
       * @var array $register
       */
      $register = Products::get();

      /**
       * Devuelve un número total de registros almacenados en la tabla
       * `products`.
       * 
       * @var integer $count
       */
      $count = Products::count();

      /**
       * Número de páginas
       * 
       * @var integer
       */
      $page = 1;

      /**
       * Número de registro por página.
       * 
       * @var integer
       */
      $paginate = Products::paginate($page, $rows);

      return [
        "count" => $count,
        "register" => $register,
        "paginate" => $paginate
      ]
    }
  }

前面的代码段是 Products 模型的基本示例，但不仅限于获取记录的方法，还包括存储新记录的方法，例如

final class TestController extends Controller {

  public function products(): array {
    $products = new Products();

    $products->product_name = $products->required('product_name');
    $products->product_description = $product->required('product_description');
    $products->save();


    return [];
  }
}

发送电子邮件

该工具使用 PHPMailer 发送电子邮件。

要从控制器发送电子邮件，可以按照以下方式操作

final class TestController extends Controller {

  /**
   * Ejemplo de envío de correos electrónicos.
   * 
   * @return array
   */
  public function mail(): array {

    $email = new SendMail();

    return $email->send(
      $email->get_email('email_field'),
      $body->get_required('body_field') # Puede contener código HTML
    );
  }
}

此外，您需要在 .env.type 文件中预先添加以下行才能发送电子邮件

# Servidor SMTP:
MAIL_HOST: string = "smtp.su-hosting.com"

# Cuenta de correo que enviará su correo electrónico:
MAIL_USERNAME: email = no-reply@su-dominio.com

# Contraseña de su cuenta de correo `no-reply@su-dominio.com`:
MAIL_PASSWORD: string = "contraseña"

# Correo electrónico en el que recibirá respuesta
MAIL_CONTACT: email = contact@su-dominio.com

认证系统

要实现基本的认证系统，应在 DLUser 中创建一个扩展类，如下所示

use DLTools\Auth\DLAuth;
use DLTools\Auth\DLUser;

class Users extends DLUser {

  public function capture_credentials(): void {
    /**
     * Autenticación del usuario
     * 
     * @var DLAuth
     */
    $auth = DLAuth::get_instance();

    $this->set_username(
      $this->get_required('username')
    );

    $this->set_password(
      $this->get_required('password')
    );
    
    $auth->auth($this, [
      "username_field" => 'username',
      "password_field" => 'password',
      "token_field" => 'token'
    ]);
  }
}

文档

这份文档将逐步更新关于此工具的完整使用说明。这只是其中一部分。