This tutorial will help you package a custom operation into a Composer package, so that you (or other people) can use it in multiple Laravel projects. If you haven't already, please create your custom operation first, and make sure it's working well, before you move it to a package. It's just easier that way.
Install this excellent package that will create the boilerplate code for you:
composer require jeroen-g/laravel-packager --dev
Ask the package to generate the boilerplate code for your new package:
php artisan packager:new MyName SomeCustomOperation --i
Keep in mind:
MyName
should be your GitHub handle (or organisation), in studly case (CompanyName
);SomeCustomOperation
should be the package name you want, in studly case (ModerateOperation
);website
should be a valid URL, so include the protocol too: http://example.com
;description
should be pretty short;license
is just the license name, if it's a common one (ex: MIT
, GPLv2
);This will create a /packages/MyName/SomeCustomOperation
folder in your root directory, which will hold all the code for your package. It has pulled a basic package template, that we need to customize.
It will also modify your project's composer.json
file to point to this new folder.
Inside your /packages/MyName/SomeCustomOperation/composer.json
file, make sure you require the version of Backpack your package will support. If unsure, copy-paste the requirement from your project's composer.json
file.
"require": {
+ "backpack/crud": "^4.0.0"
- "illuminate/support": "~5|~6"
},
Note:
illuminate/support
requirement in most cases - if Backpack is installed, so is that;Notice that this composer.json
will also:
autoload/psr-4
);extra/laravel/providers
);composer require myname/somecustomoperation
Congratulations! Now you have a basic package, installed in packages/MyName/SomeCustomOperation
, that is loaded in your current Laravel project. Note that:
composer.json
file, to require the package; Because previously Packager has pointed to the packages folder, it will pick it up from there, instead of the Internet;composer.json
file will point to the ServiceProvider
inside your package's src
folder;If you want to test that your package is being loaded, you can do a
dd('got here')
inside your package'sServiceProvider::boot
method. If you refresh the page, you should see thatdd()
statement executed.
You can choose whatever folder structure you want for your package. But within Backpack add-ons, we follow the convention that the package folder should look as much as possible like a Laravel project folder. That way, when someone looks at the addon's source code, they instantly understand where everything is.
Operation Trait
Notice a file has already been created, with the operation name, inside your package's src
folder. You can move your operation trait code from app/Http/Controllers/Admin/Operations
to this src/SomeCustomOperation
file, but make sure:
MyName\SomeCustomOperation
);Views
If your operation has a user interface, consider moving all the views this operation needs inside your package folder, inside a resources/views
folder.
Then in your package's ServiceProvider, make sure inside boot()
that you load the views:
$this->loadViewsFrom(__DIR__.'/../resources/views', 'somecustomoperation');
Config
For most custom Operations, there's really no need to define your own config file. You can just instruct people to use the config/backpack/crud.php
file, and define stuff inside operations
, inside an array with your operation's name. If this works for you, then:
config
folder entirely;register()
method, delete the line with mergeConfigFrom()
;bootForConsole()
method, delete the line that publishes the config file;bootFromConsole()
method, include:
$this->publishes([
__DIR__.'/../resources/views' => base_path('resources/views/vendor/backpack'),
], 'somecustomoperation.views');
That way, developers define config values for your custom operation the same way they define them for a default Backpack operation.
Translations
If your Operation has an interface, it most likely also needs a translation file, so that strings are translatable. To add a translation file:
boot()
method, include:
$this->loadTranslationsFrom(__DIR__.'/../resources/lang', 'backpack');
bootFromConsole()
method, include:
$this->publishes([
__DIR__.'/../resources/lang' => resource_path('lang/vendor/backpack'),
], 'somecustomoperation');
resources/lang/en
folder;somecustom.php
, with the translation lines there;trans('somecustomoperation::somecustom.line_key')
throughout your operation's controller/views;src/Facades
folder; if you do that, also remove the alias to that Facade, at the bottom of your package's composer.json
file;register()
, provides()
methods in your ServiceProvider; it's best to remove them;Inside your package folder, go through all markdown files and make them your own. At the very least, go through:
Inside your package folder, run:
cd packages/myname/somecustomoperation
git init
git add .
git commit -m "first commit"
First, create a new GitHub Repository for it. Remember to use the same name you defined in your package's composer.json
. If in doubt, double-check.
Second, add that new GitHub Repo as a remote, and push your code to your new GitHub repo.
git remote add origin [email protected]:yourusername/yourrepository.git
git push -u origin master
git tag -a 1.0.0 -m 'First version'
git push --tags
The tags are the way you will version your package, so it's important you do it.
In order for people to be able to install your package using composer, your package needs to be registered with Packagist, Composer's free package registry.
On Packagist.org, submit a new package. Enter your package's GitHub URL and click Check. If any errors occur, follow the onscreen instructions. When you're done, you're taken to your package's packagist page.
Congrats, you have a working package online, you can now install it using Composer.
Note: On the package page, you might get a notice like this: This package is not auto-updated. Please set up the GitHub Service Hook for Packagist so that it gets updated whenever you push! Let's take care of that. Click that link, get your API token and go to your package's GitHub page, in Settings / Webhooks & Services / Add a new service. Search for Packagist. Enter your username and the token and hit Submit. Your error in Packagist should disappear in 5–10 minutes.
Congratulations on your new Backpack addon!
To get feedback, ask people to try it on:
Make sure you write something nice, so people are interested to click.
After you've got some feedback, and a few users have installed your package and everything seems fine, time to promote it big time:
Then you'll love our premium add-ons - productivity tools and tons of new features.