spatie / laravel-package-tools
Tools for creating Laravel packages
Fund package maintenance!
spatie
Installs: 56 731 157
Dependents: 4 265
Suggesters: 0
Security: 0
Stars: 787
Watchers: 10
Forks: 132
Open Issues: 2
Requires
- php: ^8.0
- illuminate/contracts: ^9.28|^10.0|^11.0
Requires (Dev)
- mockery/mockery: ^1.5
- orchestra/testbench: ^7.7|^8.0
- pestphp/pest: ^1.22
- phpunit/phpunit: ^9.5.24
- spatie/pest-plugin-test-time: ^1.1
- dev-main
- 1.16.5
- 1.16.4
- 1.16.3
- 1.16.2
- 1.16.1
- 1.16.0
- 1.15.0
- 1.14.3
- 1.14.2
- 1.14.1
- 1.14.0
- 1.13.9
- 1.13.8
- 1.13.7
- 1.13.6
- 1.13.5
- 1.13.4
- 1.13.3
- 1.13.2
- 1.13.1
- 1.13.0
- 1.12.1
- 1.12.0
- 1.11.3
- 1.11.2
- 1.11.1
- 1.11.0
- 1.10.0
- 1.9.2
- 1.9.1
- 1.9.0
- 1.8.0
- 1.7.0
- 1.6.3
- 1.6.2
- 1.6.1
- 1.6.0
- 1.5.0
- 1.4.3
- 1.4.2
- 1.4.1
- 1.4.0
- 1.3.1
- 1.3.0
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.0
- 1.0.2
- 1.0.1
- 1.0.0
- 0.0.3
- 0.0.2
- 0.0.1
This package is auto-updated.
Last update: 2024-09-27 19:13:41 UTC
README
This package contains a PackageServiceProvider
that you can use in your packages to easily register config files,
migrations, and more.
Here's an example of how it can be used.
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(); }); } }
Under the hood it will do the necessary work to register the necessary things and make all sorts of files publishable.
Support us
We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.
Getting started
This package is opinionated on how you should structure your package. To get started easily, consider
using our package-skeleton repo to start your package. The
skeleton is structured perfectly to work perfectly with the PackageServiceProvider
in this package.
Usage
In your package you should let your service provider extend 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'); } }
Passing the package name to name
is mandatory.
Working with a config file
To register a config file, you should create a php file with your package name in the config
directory of your
package. In this example it should be at <package root>/config/your-package-name.php
.
If your package name starts with laravel-
, we expect that your config file does not contain that prefix. So if your
package name is laravel-cool-package
, the config file should be named cool-package.php
.
To register that config file, call hasConfigFile()
on $package
in the configurePackage
method.
$package ->name('your-package-name') ->hasConfigFile();
The hasConfigFile
method will also make the config file publishable. Users of your package will be able to publish the
config file with this command.
php artisan vendor:publish --tag=your-package-name-config
Should your package have multiple config files, you can pass their names as an array to hasConfigFile
$package ->name('your-package-name') ->hasConfigFile(['my-config-file', 'another-config-file']);
Working with views
Any views your package provides, should be placed in the <package root>/resources/views
directory.
You can register these views with the hasViews
command.
$package ->name('your-package-name') ->hasViews();
This will register your views with Laravel.
If you have a view <package root>/resources/views/myView.blade.php
, you can use it like
this: view('your-package-name::myView')
. Of course, you can also use subdirectories to organise your views. A view
located at <package root>/resources/views/subdirectory/myOtherView.blade.php
can be used
with view('your-package-name::subdirectory.myOtherView')
.
Using a custom view namespace
You can pass a custom view namespace to the hasViews
method.
$package ->name('your-package-name') ->hasViews('custom-view-namespace');
You can now use the views of the package like this:
view('custom-view-namespace::myView');
Publishing the views
Calling hasViews
will also make views publishable. Users of your package will be able to publish the views with this
command:
php artisan vendor:publish --tag=your-package-name-views
Note:
If you use custom view namespace then you should change your publish command like this:
php artisan vendor:publish --tag=custom-view-namespace-views
Sharing global data with views
You can share data with all views using the sharesDataWithAllViews
method. This will make the shared variable
available to all views.
$package ->name('your-package-name') ->sharesDataWithAllViews('companyName', 'Spatie');
Working with Blade view components
Any Blade view components that your package provides should be placed in the <package root>/src/Components
directory.
You can register these views with the hasViewComponents
command.
$package ->name('your-package-name') ->hasViewComponents('spatie', Alert::class);
This will register your view components with Laravel. In the case of Alert::class
, it can be referenced in views
as <x-spatie-alert />
, where spatie
is the prefix you provided during registration.
Calling hasViewComponents
will also make view components publishable, and will be published
to app/Views/Components/vendor/<package name>
.
Users of your package will be able to publish the view components with this command:
php artisan vendor:publish --tag=your-package-name-components
Working with view composers
You can register any view composers that your project uses with the hasViewComposers
method. You may also register a
callback that receives a $view
argument instead of a classname.
To register a view composer with all views, use an asterisk as the view name '*'
.
$package ->name('your-package-name') ->hasViewComposer('viewName', MyViewComposer::class) ->hasViewComposer('*', function($view) { $view->with('sharedVariable', 123); });
Working with inertia components
Any .vue
or .jsx
files your package provides, should be placed in the <package root>/resources/js/Pages
directory.
You can register these components with the hasInertiaComponents
command.
$package ->name('your-package-name') ->hasInertiaComponents();
This will register your components with Laravel.
The user should publish the inertia components manually or using the installer-command in order to use them.
If you have an inertia component <package root>/resources/js/Pages/myComponent.vue
, you can use it like
this: Inertia::render('YourPackageName/myComponent')
. Of course, you can also use subdirectories to organise your components.
Publishing inertia components
Calling hasInertiaComponents
will also make inertia components publishable. Users of your package will be able to publish the views with this
command:
php artisan vendor:publish --tag=your-package-name-inertia-components
Also, the inertia components are available in a convenient way with your package installer-command
Working with translations
Any translations your package provides, should be placed in the <package root>/resources/lang/<language-code>
directory.
You can register these translations with the hasTranslations
command.
$package ->name('your-package-name') ->hasTranslations();
This will register the translations with Laravel.
Assuming you save this translation file at <package root>/resources/lang/en/translations.php
...
return [ 'translatable' => 'translation', ];
... your package and users will be able to retrieve the translation with:
trans('your-package-name::translations.translatable'); // returns 'translation'
If your package name starts with laravel-
then you should leave that off in the example above.
Coding with translation strings as keys, you should create JSON files
in <package root>/resources/lang/<language-code>.json
.
For example, creating <package root>/resources/lang/it.json
file like so:
{ "Hello!": "Ciao!" }
...the output of...
trans('Hello!');
...will be Ciao!
if the application uses the Italian language.
Calling hasTranslations
will also make translations publishable. Users of your package will be able to publish the
translations with this command:
php artisan vendor:publish --tag=your-package-name-translations
Working with assets
Any assets your package provides, should be placed in the <package root>/resources/dist/
directory.
You can make these assets publishable the hasAssets
method.
$package ->name('your-package-name') ->hasAssets();
Users of your package will be able to publish the assets with this command:
php artisan vendor:publish --tag=your-package-name-assets
This will copy over the assets to the public/vendor/<your-package-name>
directory in the app where your package is
installed in.
Working with migrations
The PackageServiceProvider
assumes that any migrations are placed in this
directory: <package root>/database/migrations
. Inside that directory you can put any migrations.
To register your migration, you should pass its name without the extension to the hasMigration
table.
If your migration file is called create_my_package_tables.php.stub
you can register them like this:
$package ->name('your-package-name') ->hasMigration('create_my_package_tables');
Should your package contain multiple migration files, you can just call hasMigration
multiple times or
use hasMigrations
.
$package ->name('your-package-name') ->hasMigrations(['my_package_tables', 'some_other_migration']);
Calling hasMigration
will also make migrations publishable. Users of your package will be able to publish the
migrations with this command:
php artisan vendor:publish --tag=your-package-name-migrations
Like you might expect, published migration files will be prefixed with the current datetime.
You can also enable the migrations to be registered without needing the users of your package to publish them:
$package ->name('your-package-name') ->hasMigrations(['my_package_tables', 'some_other_migration']) ->runsMigrations();
Working with a publishable service provider
Some packages need an example service provider to be copied into the app\Providers
directory of the Laravel app. Think
of for instance, the laravel/horizon
package that copies an HorizonServiceProvider
into your app with some sensible
defaults.
$package ->name('your-package-name') ->publishesServiceProvider($nameOfYourServiceProvider);
The file that will be copied to the app should be stored in your package
in /resources/stubs/{$nameOfYourServiceProvider}.php.stub
.
When your package is installed into an app, running this command...
php artisan vendor:publish --tag=your-package-name-provider
... will copy /resources/stubs/{$nameOfYourServiceProvider}.php.stub
in your package
to app/Providers/{$nameOfYourServiceProvider}.php
in the app of the user.
Registering commands
You can register any command you package provides with the hasCommand
function.
$package ->name('your-package-name') ->hasCommand(YourCoolPackageCommand::class);
If your package provides multiple commands, you can either use hasCommand
multiple times, or pass an array
to hasCommands
$package ->name('your-package-name') ->hasCommands([ YourCoolPackageCommand::class, YourOtherCoolPackageCommand::class, ]);
Adding an installer command
Instead of letting your users manually publishing config files, migrations, and other files manually, you could opt to add an install command that does all this work in one go. Packages like Laravel Horizon and Livewire provide such commands.
When using Laravel Package Tools, you don't have to write an InstallCommand
yourself. Instead, you can simply
call, hasInstallCommand
and configure it using a closure. Here's an example.
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') }); } }
With this in place, the package user can call this command:
php artisan your-package-name:install
Using the code above, that command will:
- publish the config file
- publish the assets
- publish the migrations
- copy the
/resources/stubs/MyProviderName.php.stub
from your package toapp/Providers/MyServiceProviderName.php
, and also register that provider inconfig/app.php
- ask if migrations should be run now
- prompt the user to open up
https://github.com/'your-vendor/your-repo-name'
in the browser in order to star it
You can also call startWith
and endWith
on the InstallCommand
. They will respectively be executed at the start and
end when running php artisan your-package-name:install
. You can use this to perform extra work or display extra
output.
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!'); }) }); }
Working with routes
The PackageServiceProvider
assumes that any route files are placed in this directory: <package root>/routes
. Inside
that directory you can put any route files.
To register your route, you should pass its name without the extension to the hasRoute
method.
If your route file is called web.php
you can register them like this:
$package ->name('your-package-name') ->hasRoute('web');
Should your package contain multiple route files, you can just call hasRoute
multiple times or use hasRoutes
.
$package ->name('your-package-name') ->hasRoutes(['web', 'admin']);
Using lifecycle hooks
You can put any custom logic your package needs while starting up in one of these methods:
registeringPackage
: will be called at the start of theregister
method ofPackageServiceProvider
packageRegistered
: will be called at the end of theregister
method ofPackageServiceProvider
bootingPackage
: will be called at the start of theboot
method ofPackageServiceProvider
packageBooted
: will be called at the end of theboot
method ofPackageServiceProvider
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.