{"id":22730965,"url":"https://github.com/esensi/loaders","last_synced_at":"2025-04-14T00:31:15.112Z","repository":{"id":27587811,"uuid":"31070738","full_name":"esensi/loaders","owner":"esensi","description":"The missing loaders package for Laravel 5","archived":false,"fork":false,"pushed_at":"2024-01-10T13:36:40.000Z","size":41,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-11-29T17:41:49.510Z","etag":null,"topics":["esensi","laravel","loaders","yaml"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esensi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-20T15:28:04.000Z","updated_at":"2022-05-10T17:18:20.000Z","dependencies_parsed_at":"2022-08-21T11:50:49.248Z","dependency_job_id":null,"html_url":"https://github.com/esensi/loaders","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esensi%2Floaders","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esensi%2Floaders/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esensi%2Floaders/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esensi%2Floaders/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esensi","download_url":"https://codeload.github.com/esensi/loaders/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229116952,"owners_count":18022816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esensi","laravel","loaders","yaml"],"created_at":"2024-12-10T19:18:24.006Z","updated_at":"2024-12-10T19:18:24.517Z","avatar_url":"https://github.com/esensi.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Esensi Loaders Traits Package\n\n\u003e Version 1\n\nAn [Esensi\\Loaders] package, coded by [SiteRocket Labs®](https://www.siterocket.com).\n\nEsensi/Loaders uses [PHP traits](http://culttt.com/2014/06/25/php-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!)\n\n## Note\n\nThis `Esensi/Activity` is specifically designed to be compatible with the [Laravel Framework](https://laravel.com) and may not be compatible as a stand-alone dependency or as part of another framework.\n\n## Quick Start\n\nInstall the package with Composer: \n\n```bash\ncomposer require esensi/loaders\n```\n\nGetting started with these new traits is a simple matter of extending the abstract `ServiceProvider` class that comes with the `Esensi/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:\n\n```php\n\u003c?php namespace App\\Providers;\n\nuse Esensi\\Loaders\\Providers\\ServiceProvider;\n\nclass PackageServiceProvider extends ServiceProvider {\n\n    /**\n     * The namespace of the loaded config files.\n     *\n     * @var string\n     */\n    protected $namespace = 'vendor/package';\n\n    /**\n     * Bootstrap the application events.\n     *\n     * @return void\n     */\n    public function boot()\n    {\n        $namespace = $this-\u003egetNamespace();\n\n        // Load the configs first\n        $this-\u003eloadConfigsFrom(__DIR__ . '/../../config', $namespace, $this-\u003epublish);\n\n        // Optionally use Laravel 8's methods for loading views and language files\n        $this-\u003eloadViewsFrom(__DIR__ . '/../../resources/views', $namespace);\n        $this-\u003eloadTranslationsFrom(__DIR__ . '/../../resources/lang', $namespace);\n\n        // Optionally load custom aliases out of the configs\n        $this-\u003eloadAliasesFrom(config_path($namespace), $namespace);\n    }\n\n}\n```\n\n## Table of Contents\n\n\u003e **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.\n\n- **[Config Loader](#config-loader)**\n- **[YAML Loader](#yaml-loader)**\n- **[Alias Loader](#alias-loader)**\n    - [Example Alias File](#example-alias-file)\n- **[Unit Testing](#unit-testing)**\n    - [Running the Unit Tests](#running-the-unit-tests)\n- **[Contributing](#contributing)**\n- **[Licensing](#licensing)**\n\n## Config Loader\n\n\u003e **Pro Tip:** This package includes an abstract `ServiceProvider` that makes use of this trait. Package developers should consider extending the [`Esensi\\Loaders\\Providers\\ServiceProvider`](https://github.com/esensi/loaders/blob/master/src/Providers/ServiceProvider.php) and customizing the `boot()` method.\n\nThe [`ConfigLoader`](https://github.com/esensi/loaders/blob/master/src/Traits/ConfigLoader.php) 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.\n\nIn order to provide the application with namespaced configs, simply use the `ConfigLoader` trait on any `ServiceProvider` class and call `loadConfigsFrom()` method from the `boot()` method of the class. By default this will make the configs found at the specified path available for publishing using `php artisan vendor:publish --tag=\"config\"` (requires additional [`ConfigPublisher`](https://github.com/esensi/loaders/blob/master/src/Traits/ConfigPublisher.php) 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.\n\n```php\n\u003c?php namespace App\\Providers;\n\nuse Esensi\\Loaders\\Contracts\\ConfigLoader as ConfigLoaderContract;\nuse Esensi\\Loaders\\Traits\\ConfigLoader;\nuse Illuminate\\Support\\ServiceProvider;\n\nclass PackageServiceProvider extends ServiceProvider implements ConfigLoaderContract {\n\n    /**\n     * Load namespaced config files.\n     *\n     * @see Esensi\\Loaders\\Contracts\\ConfigLoader\n     */\n    use ConfigLoader;\n\n    /**\n     * Bootstrap the application events.\n     *\n     * @return void\n     */\n    public function boot()\n    {\n        $this-\u003eloadConfigsFrom(__DIR__ . '/../../config', 'vendor/package');\n    }\n\n    /**\n     * Register any application services.\n     *\n     * @return void\n     */\n    public function register()\n    {\n\n    }\n}\n```\n\n\u003e **Pro Tip:** When used with [`ConfigPublisher`](https://github.com/esensi/loaders/blob/master/src/Traits/ConfigPublisher.php) trait, an optional third parameter of the `loadConfigsFrom()` 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 the [`Esensi\\Loaders\\Contracts\\ConfigLoader`](https://github.com/esensi/loaders/blob/master/src/Contracts/ConfigLoader.php) for more details.\n\n\n## YAML Loader\n\n\u003e **Pro Tip:** This package includes an abstract `YamlServiceProvider` that makes use of this trait. Package developers should consider extending the [`Esensi\\Loaders\\Providers\\YamlServiceProvider`](https://github.com/esensi/loaders/blob/master/src/Providers/YamlServiceProvider.php) and customizing the `boot()` method.\n\nThe [`YamlLoader`](https://github.com/esensi/loaders/blob/master/src/Traits/YamlLoader.php) is a trait that is very similar to the [`ConfigLoader`](https://github.com/esensi/loaders/blob/master/src/Traits/ConfigLoader.php) 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 with [`ConfigPublisher`](https://github.com/esensi/loaders/blob/master/src/Traits/ConfigPublisher.php) to make publishing of the package's YAML configs to the namespaced config path of the Laravel project.\n\nIn order to provide the application with namespaced YAML configs, simply use the `YamlLoader` trait on any `ServiceProvider` class and call `loadYamlFrom()` method from the `boot()` method of the class. By default this will make the YAML found at the specified path available for publishing using `php artisan vendor:publish --tag=\"yaml\"` (requires additional [`ConfigPublisher`](https://github.com/esensi/loaders/blob/master/src/Traits/ConfigPublisher.php) 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 via `config('vendor/package::foo')` just like they would have been in Laravel 4.\n\n```php\n\u003c?php namespace App\\Providers;\n\nuse Esensi\\Loaders\\Contracts\\YamlLoader as YamlLoaderContract;\nuse Esensi\\Loaders\\Traits\\YamlLoader;\nuse Illuminate\\Support\\ServiceProvider;\n\nclass PackageServiceProvider extends ServiceProvider implements YamlLoaderContract {\n\n    /**\n     * Load namespaced YAML files.\n     *\n     * @see Esensi\\Loaders\\Contracts\\YamlLoader\n     */\n    use YamlLoader;\n\n    /**\n     * Bootstrap the application events.\n     *\n     * @return void\n     */\n    public function boot()\n    {\n        $this-\u003eloadYamlFrom(__DIR__ . '/../../config', 'vendor/package');\n    }\n\n    /**\n     * Register any application services.\n     *\n     * @return void\n     */\n    public function register()\n    {\n\n    }\n}\n```\n\n## Alias Loader\n\n\u003e **Pro Tip:** This package includes an abstract `ServiceProvider` that makes use of this trait. Package developers should consider extending the [`Esensi\\Loaders\\Providers\\ServiceProvider`](https://github.com/esensi/loaders/blob/master/src/Providers/ServiceProvider.php) and customizing the `boot()` method.\n\nThe [`AliasLoader`](https://github.com/esensi/loaders/blob/master/src/Traits/AliasLoader.php) 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 native [`class_alias`](http://php.net/class_alias) method.\n\nThis 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.\n\nIn order to provide the application with these aliases, simply use the `AliasLoader` trait on any `ServiceProvider` class and call `loadAliasesFrom()` method from the `boot()` method of the class. By default this will scan the specified path for config files and map the aliases to the classes set on the `aliases` configuration line. These aliases are then available for use within other classes of the application.\n\n```php\n\u003c?php namespace App\\Providers;\n\nuse Esensi\\Loaders\\Contracts\\AliasLoader as AliasLoaderContract;\nuse Esensi\\Loaders\\Traits\\AliasLoader;\nuse Illuminate\\Support\\ServiceProvider;\n\nclass PackageServiceProvider extends ServiceProvider implements AliasLoaderContract {\n\n    /**\n     * Load namespaced aliases from the config files.\n     *\n     * @see Esensi\\Loaders\\Contracts\\AliasLoader\n     */\n    use AliasLoader;\n\n    /**\n     * Bootstrap the application events.\n     *\n     * @return void\n     */\n    public function boot()\n    {\n        $this-\u003eloadAliasesFrom(config_path('vendor/package'), 'vendor/package');\n    }\n\n    /**\n     * Register any application services.\n     *\n     * @return void\n     */\n    public function register()\n    {\n\n    }\n}\n```\n\n\u003e **Pro Tip:** An optional third parameter of the `loadAliasesFrom()` method allows for customization of the key in which the `aliases` map should be found. See the [`Esensi\\Loaders\\Contracts\\AliasLoader`](https://github.com/esensi/loaders/blob/master/src/Contracts/AliasLoader.php) for more details.\n\n### Example Alias File\n\nJust like the `config/app.php` file that comes with Laravel 8's default configurations, an `aliases` key should be added to any config file that should register aliases. Below is an example configuration file:\n\n```php\n\u003c?php\n\nreturn [\n\n    /*\n    |--------------------------------------------------------------------------\n    | Application aliases\n    |--------------------------------------------------------------------------\n    |\n    | The following configuration options allow the developer to map shortcut\n    | and placeholder aliases to concrete classes. These aliases should be\n    | loaded by a service provider that uses the AliasLoader trait. If\n    | the app actually makes use of a class by the same name as an\n    | alias then simply comment out the alias here so that the\n    | real class may be used instead.\n    |\n    */\n    'aliases' =\u003e [\n\n        // A shortcut alias for a namespaced class\n        'User' =\u003e 'App\\Models\\User',\n\n        // A shortcut alias for a Facade or service locator\n        'Foo' =\u003e 'Vendor\\Package\\FooFacade',\n\n        // A placeholder alias for a missing class\n        'App\\Foo\\Bar' =\u003e 'Vendor\\Package\\Foo\\Bar',\n    ]\n];\n```\n\n\n\n## Unit Testing\n\n_**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. :wink:)_\n\n\n\n## Contributing\n\nThank you for considering contributing to Esensi Core!\n\n\n\n## Licensing\n\nCopyright (c) 2022 [SiteRocket Labs](https://www.siterocket.com)\n\nEsensi Core is open-sourced software licensed under the [MIT license](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesensi%2Floaders","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesensi%2Floaders","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesensi%2Floaders/lists"}