NathanBurkett/Ecosystem
![Software License][ico-license], (*1)
Ecosystem is a simple and smart environment manager for your user-facing scripts and stylesheets., (*2)
Ecosystems are useful when you have collections of separate resources for differing sections of your application - http://example.com vs. http://example.com/admin. Creating an Ecosystem for each section allows to you manage each's resources in a collection one place while being able to add new resources to the collection on the fly., (*3)
Install
To install Ecosystem as a Composer package, run:, (*4)
``` bash
composer require nathanburkett/ecosystem, (*5)
Once it's installed, you can register the service provider in `config/app.php` in the `providers` array:
```php
'providers' => [
...
NathanBurkett\Ecosystem\Providers\EcosystemServiceProvider::class,
]
And register the Ecosystem facade in the the aliases array:, (*6)
'aliases' => [
...
'Ecosystem' => NathanBurkett\Ecosystem\Facades\Ecosystem::class,
Then publish Ecosystems's assets with php artisan vendor:publish. This will add the file config/ecosystem.php. This config file allows certain envionments to disable cache-busting strings., (*7)
Usage
Creating a New Ecosystem
Run php artisan from the console, and you'll see the new make:ecosystem command., (*8)
Running php artisan make:ecosystem StandardEcosystem from the console will create StandardEcosystem in App\Library\Ecosystems directory. If directory doesn't exist, the command will create it., (*9)
To place Ecosystem in a different directory, append --namespace=Your\Namespace\Here to the command. Doing so will create an Ecosystem in the string of directories starting with a lowercase version of the first directory segment - ie --namespace=Resources\Ecosystems would place the Ecosystem in resources\Ecosystems., (*10)
The command php artisan make:ecosystem StandardEcosystem would generate the following file in the App\Library\Ecosystems directory., (*11)
<?php
namespace App\Library\Ecosystems;
use NathanBurkett\Ecosystem\Contracts\AssetCollectionContract;
use NathanBurkett\Ecosystem\Entities\AbstractEcosystem as Ecosystem;
class StandardEcosystem extends Ecosystem implements AssetCollectionContract
{
/**
* Default StandardEcosystem head scripts
* @return array
*/
final public function defaultHeadScripts()
{
return [
'' => ['src' => '']
];
}
/**
* Default StandardEcosystem stylesheets
* @return array
*/
final public function defaultStylesheets()
{
return [
'' => ['href' => '']
];
}
/**
* Default StandardEcosystem footer scripts
* @return array
*/
final public function defaultFooterScripts()
{
return [
'' => ['src' => '']
];
}
}
Adding assets to any of the default collections allows you to display them easily from any view., (*12)
final public function defaultHeadScripts()
{
return [
'yahoo' => ['src' => '/yahoo.js'],
'wahoo' => ['src' => '/wahoo.js'],
'yippee' => ['src' => '/yippee.js']
];
}
This will bundle the assets in a Laravel Collection until they're output in a view. In a view associated with this route, (*13)
Ecosystem::getHeadScripts();
Would output, (*14)
<script src="/yahoo.js?123456789"></script>
<script src="/wahoo.js?123456789"></script>
<script src="/yippee.js?123456789"></script>
Attaching to Routes
Ecosystems are assigned to routes and groups of routes by attaching them as middleware., (*15)
Route::group(['middleware' => 'ecosystem', 'ecosystem' => 'App\Library\Ecosystems\StandardEcosystem'], function() {
Route::get('/', 'IndexController@index');
});
Ecosystems are overridden so the most immediate one on the route is used, (*16)
Route::group(['middleware' => 'ecosystem', 'ecosystem' => 'App\Library\Ecosystems\StandardEcosystem'], function () {
// NewStandardEcosystem would be used for the '/' route
Route::get('/', ['middleware' => 'ecosystem', 'ecosystem' => 'App\Library\Ecosystems\NewStandardEcosystem', 'uses' => 'IndexController@index']);
});
Dynamically Attaching Assets
Because the assets are not compiled and output until runtime, you have the ability to add one-offs to the Collection. This is typically done in a Controller., (*17)
<?php
namespace App\Http\Controllers;
use Ecosystem;
// ...
class IndexController extends Controller
{
public function index() {
Ecosystem::addScriptToHead('blammo', ['src' => '/blammo.js']);
}
}
Would change the Ecosystem::getHeadScripts() output to, (*18)
<script src="/yahoo.js?123456789"></script>
<script src="/wahoo.js?123456789"></script>
<script src="/yippee.js?123456789"></script>
<script src="/blammo.js?123456789"></script>
The Ecosystem::addScriptToHead(), Ecosystem::addStylesheet(), Ecosystem::addScriptToFooter() take a maximum of three arguments. A name for the asset, an array of attributes for the asset, and a option to set the asset before one already added to the Collection., (*19)
function addScriptToHead($name, $attr = array(), $before = null)
Supplying the name of an already registered asset in the $before argument will push the new asset above the target., (*20)
Ecosystem::addScriptToHead('blammo', ['src' => '/blammo.js'], 'yippee');
Yields, (*21)
<script src="/yahoo.js?123456789"></script>
<script src="/wahoo.js?123456789"></script>
<script src="/blammo.js?123456789"></script>
<script src="/yippee.js?123456789"></script>
Available Methods
The Ecosystem facade exposes certain methods to interact with the current Ecosystem while the actions fall within a route which has an Ecosystem registered to it., (*22)
These three methods output any assets registered to its collection in html elements and are intended to be used in views:, (*23)
Ecosystem::getHeadScripts();
Ecosystem::getStylesheets();
Ecosystem::getFooterScripts();
Ecosystem lets you add one-off assets in any area that the route middleware attached Ecosystem covers. However, this is typically done in Controllers., (*24)
<?php
namespace App\Http\Controllers;
// import the facade
use Ecosystem;
// ...
Ecosystem::addHeadScript($name, $attr = array(), $before = null);
Ecosystem::addStylesheet($name, $attr = array(), $before = null);
Ecosystem::addFooterScript($name, $attr = array(), $before = null);
Change log
Please see CHANGELOG for more information what has changed recently., (*25)
Contributing
Please see CONTRIBUTING and CONDUCT for details., (*26)
Security
If you discover any security related issues, please email nathan at nathanb dot me instead of using the issue tracker., (*27)
Credits
License
The MIT License (MIT). Please see License File for more information., (*28)
Wallogit.com
