Livewire 中文文档

主题

全部文档

贡献指南 ​

你好，欢迎阅读 Livewire 贡献指南。本指南将介绍如何通过提交新功能、修复失败测试或解决缺陷来为 Livewire 做贡献。

在本地搭建 Livewire 与 Alpine ​

要参与贡献，最简单的方式是在本地机器上搭建好 Livewire 与 Alpine 仓库。这样你可以方便地修改代码并运行测试套件。

Fork 并克隆仓库 ​

首先，需要 fork 并克隆仓库。最简单的方式是使用 GitHub CLI，你也可以在 GitHub 仓库页面 上手动点击「Fork」按钮完成。

shell
# Fork and clone Livewire
gh repo fork livewire/livewire --default-branch-only --clone=true -- livewire

# Switch the working directory to livewire
cd livewire

# Install all composer dependencies
composer install

# Ensure Dusk is correctly configured
vendor/bin/dusk-updater detect --no-interaction

要搭建 Alpine，请确保已安装 NPM，然后运行下列命令。若更想手动 fork，可访问其仓库页面。

shell
# Fork and clone Alpine
gh repo fork alpinejs/alpine --default-branch-only --clone=true --remote=false -- alpine

# Switch the working directory to alpine
cd alpine

# Install all npm dependencies
npm install

# Build all Alpine packages
npm run build

# Link all Alpine packages locally
cd packages/alpinejs && npm link && cd ../../
cd packages/anchor && npm link && cd ../../
cd packages/collapse && npm link && cd ../../
cd packages/csp && npm link && cd ../../
cd packages/docs && npm link && cd ../../
cd packages/focus && npm link && cd ../../
cd packages/history && npm link && cd ../../
cd packages/intersect && npm link && cd ../../
cd packages/mask && npm link && cd ../../
cd packages/morph && npm link && cd ../../
cd packages/navigate && npm link && cd ../../
cd packages/persist && npm link && cd ../../
cd packages/sort && npm link && cd ../../
cd packages/ui && npm link && cd ../../

# Switch the working directory back to livewire
cd ../livewire

# Link all packages
npm link alpinejs @alpinejs/anchor @alpinejs/collapse @alpinejs/csp @alpinejs/docs @alpinejs/focus @alpinejs/history @alpinejs/intersect @alpinejs/mask @alpinejs/morph @alpinejs/navigate @alpinejs/persist @alpinejs/sort @alpinejs/ui

# Build Livewire
npm run build

贡献失败测试 ​

若你遇到缺陷却不确定如何解决——尤其是 Livewire 核心相当复杂——可能会不知从何下手。这种情况下，最简单的做法是贡献一个会失败的测试。这样更有经验的人就能协助定位并修复缺陷。当然，我们也建议你浏览核心代码，以便更好地理解 Livewire 的工作方式。

我们按步骤来。

1. 确定把测试加在哪里 ​

Livewire 核心按不同文件夹划分，每个文件夹对应特定功能。例如：

shell
src/Features/SupportAccessingParent
src/Features/SupportAttributes
src/Features/SupportAutoInjectedAssets
src/Features/SupportBladeAttributes
src/Features/SupportChecksumErrorDebugging
src/Features/SupportComputed
src/Features/SupportConsoleCommands
src/Features/SupportDataBinding
//...

尽量找到与你遇到的缺陷相关的功能目录。若找不到合适文件夹或不确定选哪个，可以先选一个，并在 pull request 中说明你需要协助把测试放到正确的功能集里。

2. 确定测试类型 ​

Livewire 测试套件包含两类测试：

  1. Unit tests：这类测试关注 Livewire 的 PHP 实现。
  2. Browser tests：这类测试在真实浏览器中执行一系列步骤并断言正确结果，主要关注 Livewire 的 JavaScript 实现。

若不确定选哪类测试，或不熟悉如何为 Livewire 写测试，可以从浏览器测试开始：把你在应用和浏览器中复现缺陷的步骤实现出来即可。

单元测试应加到 UnitTest.php，浏览器测试应加到 BrowserTest.php。若其中一个或两个文件不存在，你可以自行创建。

单元测试

php
use Tests\TestCase;

class UnitTest extends TestCase
{
    public function test_livewire_can_run_action(): void
    {
       // ...
    }
}

浏览器测试

php
use Tests\BrowserTestCase;

class BrowserTest extends BrowserTestCase
{
    public function test_livewire_can_run_action()
    {
        // ...
    }
}

TIP

不确定怎么写测试？

多看现有的单元测试和浏览器测试，能学到很多写法。甚至直接复制粘贴一个现有测试，也是写自己测试的很好起点。

3. 运行测试 ​

提交 pull request 之前，请确保测试能通过。可以运行下列命令之一：

shell
vendor/bin/phpunit --filter "test_can_make_method_a_computed" # To run a specific test
vendor/bin/phpunit # To run all tests

默认情况下，浏览器测试会在有界面（headed）模式下运行。若想以无头（headless）模式运行，可在 Livewire 仓库根目录创建 .env 文件，并添加 DUSK_HEADLESS_DISABLED=false。

4. 准备 pull request 分支 ​

完成功能或失败测试后，就可以向 Livewire 仓库提交 Pull Request（PR）了。首先确保把改动提交到单独分支（不要用 main）。可用 git 命令创建新分支：

shell
git checkout -b my-feature

分支名可以随意取，但为便于日后查阅，最好用能反映功能或失败测试的描述性名称。

接着把改动提交到分支。可用 git add . 暂存所有改动，再用 git commit -m "Add my feature" 以描述性信息提交。

不过，目前分支只存在于你的本地机器。要创建 Pull Request，需要用 git push 把分支推到你 fork 的 Livewire 仓库。

shell
git push origin my-feature

Enumerating objects: 13, done.
Counting objects: 100% (13/13), done.
Delta compression using up to 8 threads
Compressing objects: 100% (6/6), done.

To github.com:Username/livewire.git
 * [new branch]        my-feature -> my-feature

5. 提交 pull request ​

就快完成了！打开浏览器，进入你 fork 的 Livewire 仓库（https://github.com/<code>&lt;your-username&gt;</code>/livewire）。屏幕中央会看到新通知：「my-feature had recent pushes 1 minute ago」，以及按钮「Compare & pull request」。点击该按钮打开 pull request 表单。

在表单中填写能描述 pull request 的标题，然后进入描述部分。文本框里已有预定义模板。请尽量回答每一个问题：

text
Review the contribution guide first at: https://livewire.laravel.com/docs/contribution-guide

1️⃣ Is this something that is wanted/needed? Did you create a discussion about it first?
Yes, you can find the discussion here: https://github.com/livewire/livewire/discussions/999999

2️⃣ Did you create a branch for your fix/feature? (Main branch PR's will be closed)
Yes, the branch is named `my-feature`

3️⃣ Does it contain multiple, unrelated changes? Please separate the PRs out.
No, the changes are only related to my feature.

4️⃣ Does it include tests? (Required)
Yes

5️⃣ Please include a thorough description (including small code snippets if possible) of the improvement and reasons why it's useful.

These changes will improve memory usage. You can see the benchmark results here:

// ...

都填好了？点击 Create pull request 🚀 恭喜！你已成功完成第一次贡献 🎉

维护者会审阅你的 PR，可能会给出反馈或要求修改。请尽量尽快处理这些反馈。

感谢你为 Livewire 做出贡献！