README

一个用于在 Laravel 中简单设置 Clean Architecture 应用的包。

要求

PHP >= 7.4;
composer.

安装

composer require onramplab/laravel-clean-architecture

特性

用例

UseCase 类将 DTO 和业务逻辑结合到单个类中，以减少文件数量，因为 DTO 通常与特定的用例紧密相关。以下是创建您自己的 UseCase 类时的功能

定义 DTO
- 定义具有验证规则的字段（您可以创建自己的验证属性）。
定义业务逻辑。

有用的日志记录

通过使用我们的异常处理器，您将获得更好的日志记录和 API 错误响应（我们遵循 JSON API 规范）。它将包含更多上下文。

以下是 API 错误响应的示例

{
  "errors": [
    {
      "title": "Fake Domain Exception",
      "detail": "A fake message",
      "status": 400
    }
  ]
}

以下是错误日志上下文的示例

{
  "detail": "A fake message",
  "adapter": {
    "type": "API",
    "route": "test-route",
    "method": "GET",
    "url": "https:///test-route",
    "input": []
  },
  "errors": [
    {
      "title": "Unable To Do Something",
      "detail": "A fake message",
      "exception_class": "OnrampLab\\CleanArchitecture\\Exceptions\\UseCaseException",
      "stacktrace": [
        "## /var/www/html/tests/Unit/Exceptions/HandlerTest.php(149)",
        "#0 /var/www/html/vendor/phpunit/phpunit/src/Framework/TestCase.php(1548): OnrampLab\\CleanArchitecture\\Tests\\Unit\\Exceptions\\HandlerTest->handleUseCaseException2()"
      ]
    },
    {
      "title": "Fake Domain Exception",
      "detail": "A fake message",
      "exception_class": "OnrampLab\\CleanArchitecture\\Tests\\Unit\\Exceptions\\FakeDomainException",
      "stacktrace": [
        "## /var/www/html/tests/Unit/Exceptions/HandlerTest.php(146)",
        "#0 /var/www/html/vendor/phpunit/phpunit/src/Framework/TestCase.php(1548): OnrampLab\\CleanArchitecture\\Tests\\Unit\\Exceptions\\HandlerTest->handleUseCaseException2()"
      ]
    }
  ]
}

异常架构的清洁架构

通用异常
- 领域层
  - 领域异常
  - 自定义领域异常
- 应用层
  - 用例异常
  - 内部服务器错误异常
- 适配器层
  - 低级异常

如何使用

如何创建用例

namespace App\UseCases;

use OnrampLab\CleanArchitecture\UseCase;
use Spatie\LaravelData\Attributes\Validation\Url;

class DoSomethingUseCase extends UseCase
{
    #[Url()]
    public string $url;

    public function handle(): string
    {
        return 'do something';
    }
}

然后在您的控制器中

use App\Http\Controllers\Controller;
use App\UseCases\DoSomethingUseCase;
use Illuminate\Http\Request;

class DoSomethingController extends Controller
{
    public function doSomething(Request $request)
    {
        $result = DoSomethingUseCase::perform([
            'url' => $request->input('url'),
        ]);

        return response()->json([
            'result' => $result,
        ]);
    }
}

如何替换异常处理器

使您的 Laravel 默认处理器扩展我们的处理器。例如

namespace App\Exceptions;

use OnrampLab\LaravelExceptions\Handler as ExceptionHandler;

class Handler extends ExceptionHandler
{
   // ...
}

如何添加自定义验证属性

您可以在创建您的验证属性的文档中找到更多信息。

有用的工具

运行测试

php vendor/bin/phpunit

或

composer test

代码检查工具

php vendor/bin/phpcs --standard=PSR2 src/

或

composer psr2check

代码自动修复工具

composer psr2autofix
composer insights:fix
rector:fix

构建文档

php vendor/bin/phpdoc -d "src" -t "docs"

或

composer docs

变更日志

为了跟踪，请参阅 CHANGELOG.md。

贡献

将其分支
创建您的功能分支（git checkout -b my-new-feature）。
进行更改。
运行测试，如果有必要，添加新测试（phpunit）。
提交更改（git commit -am '添加了一些功能'）。
将更改推送到分支（git push origin my-new-feature）。
创建新的拉取请求。

同时，请参阅 CONTRIBUTION.md。

文件夹结构

这将为您创建一个基本的项目结构

/build 默认用于存储由代码覆盖率产生的输出；
/src 是您的代码所在的地方，每个类都需要位于此文件夹内的单独文件中；
/tests 在 src 文件夹中编写的每个类在“包含”到其他地方之前都需要进行测试。因此，我们基本上在那里有测试类来测试其他类；
.gitignore 有某些文件我们不想发布到 Git 中，所以我们只是将它们添加到该文件中，以便它们被“忽略”由 Git；
CHANGELOG.md 用于跟踪包更新；
CONTRIBUTION.md 贡献者公约代码行为准则；
LICENSE 其他程序员被允许使用此库的自由条款；
README.md 是库的迷你文档，这是通常在 GitHub 和 Packagist 上发布时您的 repo 的“主页”。
composer.json 是存储您库信息的文件，例如包名、作者和依赖项；
phpunit.xml 它是PHPUnit的配置文件，以便测试类能够测试您编写的类；
.travis.yml 为Travis CI提供的基本配置，已配置测试覆盖率报告以供Code Climate使用。

技术特性

PSR-4自动加载兼容的结构；
PSR-2兼容的代码风格；
使用PHPUnit 6进行单元测试；
提供全面指南和教程；
易于与任何框架或纯PHP文件一起使用；
包含有用的工具以改进代码。

许可证

请参阅许可证。

onramplab / laravel-clean-architecture

维护者

详细信息