Package Development

    Packages are the primary way of adding functionality to Laravel. Packages might be anything from a great way to work with dates like , or an entire BDD testing framework like Behat.

    Of course, there are different types of packages. Some packages are stand-alone, meaning they work with any framework, not just Laravel. Both Carbon and Behat are examples of stand-alone packages. Any of these packages may be used with Laravel by simply requesting them in your file.

    On the other hand, other packages are specifically intended for use with Laravel. These packages may have routes, controllers, views, and configuration specifically intended to enhance a Laravel application. This guide primarily covers the development of those that are Laravel specific.

    All Laravel packages are distributed via and Composer, so learning about these wonderful PHP package distribution tools is essential.

    Views

    Your package's internal structure is entirely up to you; however, typically each package will contain one or more . The service provider contains any service container bindings, as well as instructions as to where package configuration, views, and translation files are located.

    Package views are typically referenced using a double-colon "namespace" syntax:

    All you need to do is tell Laravel where the views for a given namespace are located. For example, if your package is named "courier", you might add the following to your service provider's boot method:

    1. {
    2.     $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');
    3. }

    Now you may load your package views using the following syntax:

    1. return view('courier::view.name');

    When you use the loadViewsFrom method, Laravel actually registers two locations for your views: one in the application's resources/views/vendor directory and one in the directory you specify. So, using our courier example: when requesting a package view, Laravel will first check if a custom version of the view has been provided by the developer in resources/views/vendor/courier. Then, if the view has not been customized, Laravel will search the package view directory you specified in your call to loadViewsFrom. This makes it easy for end-users to customize / override your package's views.

    Publishing Views

    1. public function boot()
    2. {
    3.     $this->loadViewsFrom(__DIR__.'/path/to/views', 'courier');
    5.     $this->publishes([
    6.         __DIR__.'/path/to/views' => base_path('resources/views/vendor/courier'),
    7.     ]);
    8. }

    Now, when users of your package execute Laravel's command, your views directory will be copied to the specified location.

    If you would like to overwrite existing files, use the —force switch:

    1. php artisan vendor:publish --force

    Package translation files are typically referenced using a double-colon syntax:

    All you need to do is tell Laravel where the translations for a given namespace are located. For example, if your package is named "courier", you might add the following to your service provider's boot method:

    1. public function boot()
    2. {
    3.     $this->loadTranslationsFrom(__DIR__.'/path/to/translations', 'courier');
    4. }

    Note that within your translations folder, you would have further directories for each language, such as en, es, ru, etc.

    Now you may load your package translations using the following syntax:

      Configuration

      Typically, you will want to publish your package's configuration file to the application's own config directory. This will allow users of your package to easily override your default configuration options.

      1. $this->publishes([
      2.     __DIR__.'/path/to/config/courier.php' => config_path('courier.php'),
      3. ]);

      Now, when users of your package execute Laravel's vendor:publish command, your file will be copied to the specified location. Of course, once your configuration has been published, it can be accessed like any other configuration file:

      1. $value = config('courier.option');

      You may also choose to merge your own package configuration file with the application's copy. This allows your users to include only the options they actually want to override in the published copy of the configuration. To merge the configurations, use the mergeConfigFrom method within your service provider's method:

      Your packages may have assets such as JavaScript, CSS, and images. To publish assets, use the publishes method from your service provider's boot method. In this example, we will also add a "public" asset group tag.

      1. $this->publishes([
      2.     __DIR__.'/path/to/assets' => public_path('vendor/courier'),
      3. ], 'public');

      Now, when your package's users execute the vendor:publish command, your files will be copied to the specified location. Since you typically will need to overwrite the assets every time the package is updated, you may use the —force flag:

      1. php artisan vendor:publish --tag=public --force

      If you would like to make sure your public assets are always up-to-date, you can add this command to the post-update-cmd list in your composer.json file.

      Publishing File Groups

      You may want to publish groups of files separately. For instance, you might want your users to be able to publish your package's configuration files and asset files separately. You can do this by 'tagging' them:

      1. // Publish a config file
      2. $this->publishes([
      3.     __DIR__.'/../config/package.php' => config_path('package.php')
      4. ], 'config');
      6. // Publish your migrations
      7. $this->publishes([
      8.     __DIR__.'/../database/migrations/' => database_path('/migrations')
      9. ], 'migrations');

      You can then publish these files separately by referencing their tag like so:

        Including A Routes File From A Service Provider

        Note: If your package is using controllers, you will need to make sure they are properly configured in your file's auto-load section.