README

为您的 Laravel 应用提供助手类和实用工具的集合

安装

composer require wendelladriel/laravel-hut

运行您的迁移，因为这个包提供了一个名为 change_logs 的表的迁移，将在下面解释。

用法

此包提供许多类，这些类对使用 Laravel 创建的许多项目都有用。我创建这个包是因为我在工作的项目中大量使用了这些助手类和实用工具，因此我希望它也能对其他人有所帮助。

异常

此包提供了 WendellAdriel\LaravelHut\Exceptions\ApiHandler 类，您可以使用和/或扩展它。如果您正在创建一个 API，可以使用这个类。它将以 JSON 格式渲染所有错误。

您可以在您的 App\Exceptions\Handler 中扩展它

// CHANGE THIS
<?php

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Throwable;

class Handler extends ExceptionHandler

// TO THIS

<?php

namespace App\Exceptions;

use Throwable;
use WendellAdriel\LaravelHut\Exceptions\ApiHandler;

class Handler extends ApiHandler

ApiHandler 还可以通过自定义异常发送自定义错误消息，您只需实现 WendellAdriel\LaravelHut\Exceptions\AppExceptionInterface。示例

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\Response;
use WendellAdriel\LaravelHut\Exceptions\AppExceptionInterface;

class AccessDeniedException extends Exception implements AppExceptionInterface
{
    public function __construct()
    {
        parent::__construct('Access Denied', Response::HTTP_FORBIDDEN);
    }
}

当在代码中抛出这个异常时，ApiHandler 将返回一个包含给定消息和 HTTP 状态码的响应。

如果您的 APP_DEBUG 设置为 true，它还会在抛出错误时发送调试信息。

HTTP

API 控制器

此包提供了一个可以扩展的 WendellAdriel\LaravelHut\Http\ApiController 类。您可以通过扩展这个控制器而不是 Laravel 基础控制器来获取这些方法的访问权限。

/**
 * Builds and sends a simple success API response
 *
 * @param int $code
 * @return JsonResponse
 */
protected function apiSimpleSuccessResponse(int $code = Response::HTTP_CREATED): JsonResponse
{
    return response()->json(['success' => true], $code);
}

/**
 * Builds and sends a success API response
 *
 * @param mixed $data
 * @param int   $code
 * @param bool  $forceUTF8Convert
 * @return JsonResponse
 */
protected function apiSuccessResponse(
    $data,
    int $code = Response::HTTP_OK,
    bool $forceUTF8Convert = false
): JsonResponse {
    $formattedData = $forceUTF8Convert ? $this->convertToUTF8Recursively($data) : $data;
    return response()->json($formattedData, $code);
}

/**
 * Builds and sends an error API response
 *
 * @param string         $message
 * @param Throwable|null $exception
 * @param int            $code
 * @return JsonResponse
 */
protected function apiErrorResponse(
    string $message,
    Throwable $exception = null,
    int $code = Response::HTTP_INTERNAL_SERVER_ERROR
): JsonResponse {
    $response = ['message' => $message];

    if (!empty($exception) && config('app.debug')) {
        $response['debug'] = [
            'message' => $exception->getMessage(),
            'file'    => $exception->getFile(),
            'line'    => $exception->getLine(),
            'trace'   => $exception->getTraceAsString()
        ];
    }

    return response()->json($response, $code);
}

请求和 DTO

此包提供了一个可以扩展的 WendellAdriel\LaravelHut\Http\BaseRequest 类。您可以通过扩展这个类而不是从 Illuminate\Foundation\Http\FormRequest 继承来使用 DTO 模式，当从控制器发送数据到其他应用层（如服务或仓库）时。

此包还提供了一个可以扩展以创建您自己的 DTO 的类 WendellAdriel\LaravelHut\Support\DTOs\BaseDTO。

此包还提供了一个具有基本功能（如分页、搜索和排序）的请求 + DTO，您可以使用和/或扩展它。检查以下类：WendellAdriel\LaravelHut\Http\CommonTableRequest 和 WendellAdriel\LaravelHut\Support\DTOs\CommonTableDTO。

此包还提供了一个具有上述基本功能以及日期范围过滤器的请求 + DTO，您可以使用和/或扩展它。检查以下类：WendellAdriel\LaravelHut\Http\DateRangeRequest 和 WendellAdriel\LaravelHut\Support\DTOs\DateRangeDTO。

模型

此包提供了一个可以扩展的 WendellAdriel\LaravelHut\Models\BaseModel 类。您可以通过扩展这个类而不是从 Illuminate\Database\Eloquent\Model 继承来跟踪对 DB 的更改，这些更改将被记录在名为 change_logs 的表中。检查类 WendellAdriel\LaravelHut\Models\ChangeLog 和特性 WendellAdriel\LaravelHut\Models\Traits\LogChanges。

此包还提供了一个可以用于在模型中添加 UUID 字段的特性 WendellAdriel\LaravelHut\Models\Traits\HasUuid。

支持

格式化器

此包提供了一个可以用于格式化数据（如整数、浮点数、货币值、日期）的 WendellAdriel\LaravelHut\Support\Formatter 类，并提供了一些通用的有用常量，用于在代码中避免使用硬编码的字符串。

分页器

此包提供了一个可以用于手动分页集合的 WendellAdriel\LaravelHut\Support\Paginator 类。

Slack 客户端

此包提供了一个可以用于向 Slack 发送通知的 WendellAdriel\LaravelHut\Support\SlackClient 类。首先，您需要将以下配置添加到您的 config/services 文件中，并在您的 .env 文件中设置所需的 ENV 值

'slack' => [
    'bot' => [
        'name' => env('SLACK_NOTIFICATIONS_BOT_NAME', 'APP-BOT'),
        'icon' => env('SLACK_NOTIFICATIONS_BOT_ICON', ':robot_face:'),
    ],
    'channel' => env('SLACK_NOTIFICATIONS_CHANNEL', '#general'),
    'webhook' => env('SLACK_NOTIFICATIONS_WEBHOOK'),
],

之后您就可以使用 sendNotification 方法了

/**
 * Notify the Slack channel, sending the given message and mentioning the given users
 *
 * @param string      $message
 * @param array       $users
 * @param string|null $target - IF CHANNEL: '#channel' IF USER: '@username'
 * @return void
 */
public function sendNotification(string $message, array $users = [], ?string $target = null): void

致谢

• 文德尔·阿德里安
• 所有贡献者

贡献

所有 Pull Request 都受欢迎。

对于重大变更，请先打开一个 issue，描述您想要添加/更改的内容。