Repository files navigation

Version 1

An [Esensi\Loaders] package, coded bySiteRocket Labs®.

Esensi/Loaders usesPHP traits to supplement Laravel's missing namespaced config and alias loaders. Using traits allows for a high-degree of code reusability and extensibility. While this package provides a reasonable base service provider, developers are free to mix and match traits into any class that needs to make use of namespaced loaders. Using contracts, developers can be confident that the code complies to a reliable interface. (For more details on the inner workings of these traits please review the generously commented source code!)

ThisEsensi/Activity is specifically designed to be compatible with theLaravel Framework and may not be compatible as a stand-alone dependency or as part of another framework.

Install the package with Composer:

composer require esensi/loaders

Getting started with these new traits is a simple matter of extending the abstractServiceProvider class that comes with theEsensi/Loaders package. This class already implements the two loader traits and is ready for quick customization. While the following example will get the job done, please consult the package's code for more customization options:

<?phpnamespaceApp\Providers;useEsensi\Loaders\Providers\ServiceProvider;class PackageServiceProviderextends ServiceProvider {/**     * The namespace of the loaded config files.     *     * @var string     */protected$namespace ='vendor/package';/**     * Bootstrap the application events.     *     * @return void     */publicfunctionboot()    {$namespace =$this->getNamespace();// Load the configs first$this->loadConfigsFrom(__DIR__ .'/../../config',$namespace,$this->publish);// Optionally use Laravel 8's methods for loading views and language files$this->loadViewsFrom(__DIR__ .'/../../resources/views',$namespace);$this->loadTranslationsFrom(__DIR__ .'/../../resources/lang',$namespace);// Optionally load custom aliases out of the configs$this->loadAliasesFrom(config_path($namespace),$namespace);    }}

Help Write Better Documentation: The documentation is still a work in progress. You can help others learn to reuse code by contributing better documentation as a pull request.

• Config Loader
• YAML Loader
• Alias Loader
  • Example Alias File
• Unit Testing
  • Running the Unit Tests
• Contributing
• Licensing

Pro Tip: This package includes an abstractServiceProvider that makes use of this trait. Package developers should consider extending theEsensi\Loaders\Providers\ServiceProvider and customizing theboot() method.

TheConfigLoader is a trait that package developers might find useful to provide the old Laravel 4 namespaced configs back to Laravel 8. With the move to Laravel 8, the internal config loader was simplified to make use of a single level deep config structure. This made it difficult for package developers to provide publishable configs that were easy to load and also did not conflict with other local configs. Suggestions for work arounds included prefixing the files (e.g.:config('vendor-package.foo')) or combining all of the config variables into a single file (e.g.:config('vendor.package.foo')). The Esensi development team was happy enough with the old way of it, so we decided to bring back the namespaced functionality (e.g.:vendor/package::foo) as a trait.

In order to provide the application with namespaced configs, simply use theConfigLoader trait on anyServiceProvider class and callloadConfigsFrom() method from theboot() method of the class. By default this will make the configs found at the specified path available for publishing usingphp artisan vendor:publish --tag="config" (requires additionalConfigPublisher trait). The trait will then cascade the published configs on top of the package's original configs and set them in Laravel application's config repository.

<?phpnamespaceApp\Providers;useEsensi\Loaders\Contracts\ConfigLoaderasConfigLoaderContract;useEsensi\Loaders\Traits\ConfigLoader;useIlluminate\Support\ServiceProvider;class PackageServiceProviderextends ServiceProviderimplements ConfigLoaderContract {/**     * Load namespaced config files.     *     * @see Esensi\Loaders\Contracts\ConfigLoader     */use ConfigLoader;/**     * Bootstrap the application events.     *     * @return void     */publicfunctionboot()    {$this->loadConfigsFrom(__DIR__ .'/../../config','vendor/package');    }/**     * Register any application services.     *     * @return void     */publicfunctionregister()    {    }}

Pro Tip: When used withConfigPublisher trait, an optional third parameter of theloadConfigsFrom() method allows the package developer the option to turn on and off config publishing. An optional fourth parameter also allows for customization of the tag in which the configs will be published under. See theEsensi\Loaders\Contracts\ConfigLoader for more details.

Pro Tip: This package includes an abstractYamlServiceProvider that makes use of this trait. Package developers should consider extending theEsensi\Loaders\Providers\YamlServiceProvider and customizing theboot() method.

TheYamlLoader is a trait that is very similar to theConfigLoader except that instead of parsing PHP config files it parses YAML config files. Package developers who prefer to use the YAML format for configuring their packages can use this trait to load all of their YAML config files in Laravel's config repository. Additionally it can be mixed withConfigPublisher to make publishing of the package's YAML configs to the namespaced config path of the Laravel project.

In order to provide the application with namespaced YAML configs, simply use theYamlLoader trait on anyServiceProvider class and callloadYamlFrom() method from theboot() method of the class. By default this will make the YAML found at the specified path available for publishing usingphp artisan vendor:publish --tag="yaml" (requires additionalConfigPublisher trait). The trait will then cascade the published configs on top of the package's original configs and set them in Laravel 8's config repository. The new configs are then accessible viaconfig('vendor/package::foo') just like they would have been in Laravel 4.

<?phpnamespaceApp\Providers;useEsensi\Loaders\Contracts\YamlLoaderasYamlLoaderContract;useEsensi\Loaders\Traits\YamlLoader;useIlluminate\Support\ServiceProvider;class PackageServiceProviderextends ServiceProviderimplements YamlLoaderContract {/**     * Load namespaced YAML files.     *     * @see Esensi\Loaders\Contracts\YamlLoader     */use YamlLoader;/**     * Bootstrap the application events.     *     * @return void     */publicfunctionboot()    {$this->loadYamlFrom(__DIR__ .'/../../config','vendor/package');    }/**     * Register any application services.     *     * @return void     */publicfunctionregister()    {    }}

Pro Tip: This package includes an abstractServiceProvider that makes use of this trait. Package developers should consider extending theEsensi\Loaders\Providers\ServiceProvider and customizing theboot() method.

TheAliasLoader is a trait that package developers might find useful to bind Facades and other service locators or classes into the application's autoloader space. In a sense, this is what Laravel's Container does by type hinting interfaces in its dependency injection. When the interface is called for it's mapped or aliased to a concrete implementation. Using this trait does something similar but outside of the application's container and instead using PHP's nativeclass_alias method.

This trait allows for shortcuts to be made for any of the longer namespaced classes the package might use. It can also allow for developers to alias app namespaced classes (e.g.:App\Foo\Bar) that do not actually exist (or maybe don't yet exist) to vendor package classes (e.g.:Foo\Bar\Class) that actually do. Having the aliases stored in a config file allows for developers to quickly swap out the aliased classes with different instances. It also makes it easy to just drop the alias if the app namespaced class does exist: aliases are effectively placeholders.

In order to provide the application with these aliases, simply use theAliasLoader trait on anyServiceProvider class and callloadAliasesFrom() method from theboot() method of the class. By default this will scan the specified path for config files and map the aliases to the classes set on thealiases configuration line. These aliases are then available for use within other classes of the application.

<?phpnamespaceApp\Providers;useEsensi\Loaders\Contracts\AliasLoaderasAliasLoaderContract;useEsensi\Loaders\Traits\AliasLoader;useIlluminate\Support\ServiceProvider;class PackageServiceProviderextends ServiceProviderimplements AliasLoaderContract {/**     * Load namespaced aliases from the config files.     *     * @see Esensi\Loaders\Contracts\AliasLoader     */use AliasLoader;/**     * Bootstrap the application events.     *     * @return void     */publicfunctionboot()    {$this->loadAliasesFrom(config_path('vendor/package'),'vendor/package');    }/**     * Register any application services.     *     * @return void     */publicfunctionregister()    {    }}

Pro Tip: An optional third parameter of theloadAliasesFrom() method allows for customization of the key in which thealiases map should be found. See theEsensi\Loaders\Contracts\AliasLoader for more details.

Just like theconfig/app.php file that comes with Laravel 8's default configurations, analiases key should be added to any config file that should register aliases. Below is an example configuration file:

<?phpreturn [/*    |--------------------------------------------------------------------------    | Application aliases    |--------------------------------------------------------------------------    |    | The following configuration options allow the developer to map shortcut    | and placeholder aliases to concrete classes. These aliases should be    | loaded by a service provider that uses the AliasLoader trait. If    | the app actually makes use of a class by the same name as an    | alias then simply comment out the alias here so that the    | real class may be used instead.    |    */'aliases' => [// A shortcut alias for a namespaced class'User' =>'App\Models\User',// A shortcut alias for a Facade or service locator'Foo' =>'Vendor\Package\FooFacade',// A placeholder alias for a missing class'App\Foo\Bar' =>'Vendor\Package\Foo\Bar',    ]];

Heads up! This package doesn't have test coverage yet! These unit tests won't be hard to write, but we wanted to get this package out as soon as we could. They're on our TODO list! (Or, why wait? Get coverage even faster by sending us a pull request with tests. 😉)

Thank you for considering contributing to Esensi Core!

Copyright (c) 2022SiteRocket Labs

Esensi Core is open-sourced software licensed under theMIT license.