spatie/laravel-package-tools

Laravel包创建工具

维护者

详细信息

github.com/spatie/laravel-package-tools

主页

源代码

问题

资助包维护！
spatie

安装量: 55,066,178

依赖: 4,203

建议者: 0

安全性: 0

星标: 764

关注者: 10

分支: 132

开放问题: 2

1.16.5 2024-08-27 18:56 UTC

Requires

Requires (Dev)

MIT c7413972cf22ffdff97b68499c22baa04eddb6a2

  • Freek Van der Herten <freek.woop@spatie.be>

spatielaravel-package-tools

This package is auto-updated.

Last update: 2024-08-27 18:57:40 UTC

README

Latest Version on Packagist Tests Total Downloads

此包包含一个PackageServiceProvider，您可以在您的包中使用它轻松注册配置文件、迁移等。

以下是如何使用它的一个示例。

use Spatie\LaravelPackageTools\PackageServiceProvider;
use Spatie\LaravelPackageTools\Package;
use MyPackage\ViewComponents\Alert;
use Spatie\LaravelPackageTools\Commands\InstallCommand;

class YourPackageServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('your-package-name')
            ->hasConfigFile()
            ->hasViews()
            ->hasViewComponent('spatie', Alert::class)
            ->hasViewComposer('*', MyViewComposer::class)
            ->sharesDataWithAllViews('downloads', 3)
            ->hasTranslations()
            ->hasAssets()
            ->publishesServiceProvider('MyProviderName')
            ->hasRoute('web')
            ->hasMigration('create_package_tables')
            ->hasCommand(YourCoolPackageCommand::class)
            ->hasInstallCommand(function(InstallCommand $command) {
                $command
                    ->publishConfigFile()
                    ->publishAssets()
                    ->publishMigrations()
                    ->copyAndRegisterServiceProviderInApp()
                    ->askToStarRepoOnGitHub();
            });
    }
}

底层将执行必要的操作来注册必要的东西并使所有类型的文件可发布。

支持我们

我们投入了大量资源来创建最佳的开放式源代码包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感激您从家乡给我们寄来明信片，说明您正在使用我们哪个包。您可以在我们的联系页面上找到我们的地址。我们将所有收到的明信片发布在我们的虚拟明信片墙上。

入门

此包对您如何构建包有自己的看法。为了轻松入门，请考虑使用我们的package-skeleton存储库来开始您的包。该骨架结构完美，可以与包中的PackageServiceProvider完美配合。

用法

在您的包中，您应该让服务提供者扩展Spatie\LaravelPackageTools\PackageServiceProvider。

use Spatie\LaravelPackageTools\PackageServiceProvider;
use Spatie\LaravelPackageTools\Package;

class YourPackageServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package) : void
    {
        $package->name('your-package-name');
    }
}

将包名传递到name是必需的。

处理配置文件

要注册配置文件，您应该在包的config目录中创建一个包含您的包名的php文件。在这个例子中，它应该在<package root>/config/your-package-name.php。

如果您的包名以laravel-开头，我们希望您的配置文件不包含该前缀。所以如果您的包名是laravel-cool-package，配置文件应命名为cool-package.php。

要注册该配置文件，请在configurePackage方法中对$package调用hasConfigFile()。

$package
    ->name('your-package-name')
    ->hasConfigFile();

hasConfigFile方法还将使配置文件可发布。您的包的用户将能够使用此命令发布配置文件。

php artisan vendor:publish --tag=your-package-name-config

如果您的包有多个配置文件，您可以将它们的名称作为数组传递给hasConfigFile

$package
    ->name('your-package-name')
    ->hasConfigFile(['my-config-file', 'another-config-file']);

处理视图

您的包提供的任何视图都应放在包根目录下的<package root>/resources/views目录中。

您可以使用hasViews命令注册这些视图。

$package
    ->name('your-package-name')
    ->hasViews();

这将注册您的视图与Laravel。

如果您有一个视图<package root>/resources/views/myView.blade.php，您可以这样使用它：view('your-package-name::myView')。当然，您也可以使用子目录来组织您的视图。位于<package root>/resources/views/subdirectory/myOtherView.blade.php的视图可以使用view('your-package-name::subdirectory.myOtherView')使用。

使用自定义视图命名空间

您可以将自定义视图命名空间传递给hasViews方法。

$package
    ->name('your-package-name')
    ->hasViews('custom-view-namespace');

现在您可以使用以下方式使用包的视图

view('custom-view-namespace::myView');

发布视图

调用hasViews也将使视图可发布。您的包的用户将能够使用此命令发布视图

php artisan vendor:publish --tag=your-package-name-views

注意

如果您使用自定义视图命名空间，那么您应该像这样更改您的发布命令

php artisan vendor:publish --tag=custom-view-namespace-views

与视图共享全局数据

您可以使用 sharesDataWithAllViews 方法与所有视图共享数据。这将使共享变量对所有视图可用。

$package
    ->name('your-package-name')
    ->sharesDataWithAllViews('companyName', 'Spatie');

与 Blade 视图组件一起工作

您提供的任何 Blade 视图组件都应该放置在 <package root>/src/Components 目录中。

您可以使用 hasViewComponents 命令注册这些视图。

$package
    ->name('your-package-name')
    ->hasViewComponents('spatie', Alert::class);

这将注册您的视图组件与 Laravel。对于 Alert::class，在视图中可以引用为 <x-spatie-alert />，其中 spatie 是您在注册期间提供的前缀。

调用 hasViewComponents 也会使视图组件可发布，并将发布到 app/Views/Components/vendor/<package name>。

您的包的用户将能够使用此命令发布视图组件

php artisan vendor:publish --tag=your-package-name-components

与视图组合器一起工作

您可以使用 hasViewComposers 方法注册项目中使用的任何视图组合器。您还可以注册一个接收 $view 参数的回调，而不是类名。

要注册所有视图的组合器，请使用视图名称 '*'。

$package
    ->name('your-package-name')
    ->hasViewComposer('viewName', MyViewComposer::class)
    ->hasViewComposer('*', function($view) { 
        $view->with('sharedVariable', 123); 
    });

与 Inertia 组件一起工作

您提供的任何 .vue 或 .jsx 文件都应该放置在 <package root>/resources/js/Pages 目录中。

您可以使用 hasInertiaComponents 命令注册这些组件。

$package
    ->name('your-package-name')
    ->hasInertiaComponents();

这将注册您的组件与 Laravel。

用户应手动发布或使用 installer-command 来使用这些组件。

如果您有一个 Inertia 组件 <package root>/resources/js/Pages/myComponent.vue，您可以像这样使用它：Inertia::render('YourPackageName/myComponent')。当然，您也可以使用子目录来组织您的组件。

发布 Inertia 组件

调用 hasInertiaComponents 也会使 Inertia 组件可发布。您的包的用户将能够使用此命令发布视图。

php artisan vendor:publish --tag=your-package-name-inertia-components

此外，Inertia 组件通过您的包 installer-command 以方便的方式提供

与翻译一起工作

您提供的任何翻译都应该放置在 <package root>/resources/lang/<language-code> 目录中。

您可以使用 hasTranslations 命令注册这些翻译。

$package
    ->name('your-package-name')
    ->hasTranslations();

这将注册翻译与 Laravel。

假设您将此翻译文件保存为 <package root>/resources/lang/en/translations.php...

return [
    'translatable' => 'translation',
];

...您的包和用户将能够使用以下方法检索翻译

trans('your-package-name::translations.translatable'); // returns 'translation'

如果您的包名称以 laravel- 开头，那么您应该在上述示例中省略它。

使用翻译字符串作为键进行编码，您应该在 <package root>/resources/lang/<language-code>.json 中创建 JSON 文件。

例如，创建 <package root>/resources/lang/it.json 文件如下

{
    "Hello!": "Ciao!"
}

...的输出是...

trans('Hello!');

...如果应用程序使用意大利语，输出将是 Ciao!。

调用 hasTranslations 也会使翻译可发布。您的包的用户将能够使用此命令发布翻译

php artisan vendor:publish --tag=your-package-name-translations

与资产一起工作

您提供的任何资产都应该放置在 <package root>/resources/dist/ 目录中。

您可以使用 hasAssets 方法使这些资产可发布。

$package
    ->name('your-package-name')
    ->hasAssets();

您的包的用户将能够使用此命令发布资产

php artisan vendor:publish --tag=your-package-name-assets

这将把资产复制到应用程序中的 public/vendor/<your-package-name> 目录中，您的包安装在那里。

与迁移一起工作

PackageServiceProvider 假设所有迁移文件都放在此目录下： <package root>/database/migrations。在这个目录内，您可以放置任何迁移文件。

要注册您的迁移，您应将不带扩展名的迁移名称传递给 hasMigration 表。

如果您的迁移文件名为 create_my_package_tables.php.stub，您可以这样注册：

$package
    ->name('your-package-name')
    ->hasMigration('create_my_package_tables');

如果您的包包含多个迁移文件，您只需多次调用 hasMigration 或使用 hasMigrations。

$package
    ->name('your-package-name')
    ->hasMigrations(['my_package_tables', 'some_other_migration']);

调用 hasMigration 也会使迁移可发布。您的包用户将能够使用此命令发布迁移

php artisan vendor:publish --tag=your-package-name-migrations

正如您可能预料的，已发布的迁移文件将以当前日期和时间开头。

您还可以启用迁移注册，而无需用户您的包发布它们

$package
    ->name('your-package-name')
    ->hasMigrations(['my_package_tables', 'some_other_migration'])
    ->runsMigrations();

与可发布的服务提供者一起工作

一些包需要在 Laravel 应用的 app\Providers 目录中复制一个示例服务提供者。例如，laravel/horizon 包会将 HorizonServiceProvider 复制到您的应用中，并设置一些合理的默认值。

$package
    ->name('your-package-name')
    ->publishesServiceProvider($nameOfYourServiceProvider);

将被复制到应用的文件应存储在您的包中的 /resources/stubs/{$nameOfYourServiceProvider}.php.stub。

当您的包安装到应用中时，运行以下命令...

php artisan vendor:publish --tag=your-package-name-provider

... 将将您的包中的 /resources/stubs/{$nameOfYourServiceProvider}.php.stub 复制到用户应用中的 app/Providers/{$nameOfYourServiceProvider}.php。

注册命令

您可以使用 hasCommand 函数注册您包提供的任何命令。

$package
    ->name('your-package-name')
    ->hasCommand(YourCoolPackageCommand::class);

如果您的包提供多个命令，您可以使用多次 hasCommand 或将数组传递给 hasCommands。

$package
    ->name('your-package-name')
    ->hasCommands([
        YourCoolPackageCommand::class,
        YourOtherCoolPackageCommand::class,
    ]);

添加安装命令

您可以为用户提供一个安装命令，该命令一次性完成发布配置文件、迁移和其他文件的工作。例如，Laravel Horizon 和 Livewire 包提供此类命令。

使用 Laravel Package Tools 时，您无需自己编写 InstallCommand。相反，您可以简单调用 hasInstallCommand 并使用闭包进行配置。以下是一个示例。

use Spatie\LaravelPackageTools\PackageServiceProvider;
use Spatie\LaravelPackageTools\Package;
use Spatie\LaravelPackageTools\Commands\InstallCommand;

class YourPackageServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package
            ->name('your-package-name')
            ->hasConfigFile()
            ->hasMigration('create_package_tables')
            ->publishesServiceProvider('MyServiceProviderName')
            ->hasInstallCommand(function(InstallCommand $command) {
                $command
                    ->publishConfigFile()
                    ->publishAssets()
                    ->publishMigrations()
                    ->askToRunMigrations()
                    ->copyAndRegisterServiceProviderInApp()
                    ->askToStarRepoOnGitHub('your-vendor/your-repo-name')
            });
    }
}

有了这个，包用户可以调用此命令

php artisan your-package-name:install

使用上面的代码，该命令将

  • 发布配置文件
  • 发布资源
  • 发布迁移
  • 将包中的 /resources/stubs/MyProviderName.php.stub 复制到 app/Providers/MyServiceProviderName.php，并在 config/app.php 中注册该提供者
  • 询问是否现在运行迁移
  • 提示用户在浏览器中打开 https://github.com/'your-vendor/your-repo-name' 以进行星标

您还可以在 InstallCommand 上调用 startWith 和 endWith。它们分别在运行 php artisan your-package-name:install 时执行。您可以使用此功能执行额外的工作或显示额外的输出。

use Spatie\LaravelPackageTools\Commands\InstallCommand;

public function configurePackage(Package $package): void
{
    $package
        // ... configure package
        ->hasInstallCommand(function(InstallCommand $command) {
            $command
                ->startWith(function(InstallCommand $command) {
                    $command->info('Hello, and welcome to my great new package!');
                })
                ->publishConfigFile()
                ->publishAssets()
                ->publishMigrations()
               ->askToRunMigrations()
                ->copyAndRegisterServiceProviderInApp()
                ->askToStarRepoOnGitHub('your-vendor/your-repo-name')
                ->endWith(function(InstallCommand $command) {
                    $command->info('Have a great day!');
                })
        });
}

与路由一起工作

PackageServiceProvider 假设所有路由文件都放在此目录下： <package root>/routes。在这个目录内，您可以放置任何路由文件。

要注册您的路由，您应将不带扩展名的路由名称传递给 hasRoute 方法。

如果您的路由文件名为 web.php，您可以这样注册：

$package
    ->name('your-package-name')
    ->hasRoute('web');

如果您的包包含多个路由文件，您只需多次调用 hasRoute 或使用 hasRoutes。

$package
    ->name('your-package-name')
    ->hasRoutes(['web', 'admin']);

使用生命周期钩子

您可以将包启动时需要的任何自定义逻辑放入以下方法之一

  • registeringPackage：将在 PackageServiceProvider 的 register 方法开始时调用
  • packageRegistered：将在PackageServiceProvider的register方法结束时调用
  • bootingPackage：将在PackageServiceProvider的boot方法开始时调用
  • packageBooted：将在PackageServiceProvider的boot方法结束时调用

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志

贡献

有关详细信息，请参阅贡献指南

安全漏洞

有关如何报告安全漏洞的详细信息，请查看我们的安全策略

鸣谢

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。