Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tattersoftware/codeigniter4-assets
Asset handling for CodeIgniter 4
https://github.com/tattersoftware/codeigniter4-assets
assets codeigniter codeigniter4 handling loading
Last synced: 1 day ago
JSON representation
Asset handling for CodeIgniter 4
- Host: GitHub
- URL: https://github.com/tattersoftware/codeigniter4-assets
- Owner: tattersoftware
- License: mit
- Created: 2019-03-13T18:48:22.000Z (almost 6 years ago)
- Default Branch: develop
- Last Pushed: 2024-01-18T15:31:09.000Z (12 months ago)
- Last Synced: 2025-01-02T17:15:54.579Z (9 days ago)
- Topics: assets, codeigniter, codeigniter4, handling, loading
- Language: PHP
- Homepage:
- Size: 243 KB
- Stars: 50
- Watchers: 7
- Forks: 12
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome - tattersoftware/codeigniter4-assets - Asset handling for CodeIgniter 4 (PHP)
README
# Tatter\Assets
Asset handling for CodeIgniter 4
[](https://github.com/tattersoftware/codeigniter4-assets/actions/workflows/test.yml)
[](https://github.com/tattersoftware/codeigniter4-assets/actions/workflows/analyze.yml)
[](https://github.com/tattersoftware/codeigniter4-assets/actions/workflows/inspect.yml)
[](https://coveralls.io/github/tattersoftware/codeigniter4-assets?branch=develop)
## Quick Start
1. Install with Composer: `> composer require tatter/assets`
2. Enable the `assets` filter in **app/Config/Filters.php**
3. Assign `$routes` to their assets in **app/Config/Assets.php**
## Features
Provides automated asset loading for CSS and JavaScript files for CodeIgniter 4.
## Installation
Install easily via Composer to take advantage of CodeIgniter 4's autoloading capabilities
and always be up-to-date:
* `> composer require tatter/assets`
Or, install manually by downloading the source files and adding the directory to
`app/Config/Autoload.php`.
## Configuration
The library's default behavior can be overridden or augmented by its config file. Copy
**examples/Assets.php** to **app/Config/Assets.php** and follow the instructions in the
comments. If no config file is found the library will use its default.
In order to use the `AssetsFilter` you must add apply it to your target routes. The filter
does its own route matching so it is safe to apply it globally in **app/Config/Filters.php**.
See [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) for more
info, or the **Example** section below.
## Usage
If installed correctly CodeIgniter 4 will detect and autoload the library, config, and filter.
### Asset
You may use the `Asset` class to build a tag for a single asset file:
```php
');
echo view('main', ['asset' => $asset]);
```
... then in your view file:
```php
Hello World
= $asset ?>
...
```
The `Asset` class also comes with some named constructors to help you create the tag strings:
* `createFromPath(string $path)` - Returns an `Asset` from a file relative to your config's `$directory`.
* `createFromUri(string $uri, string $type = null)` - Returns an `Asset` from a remote URL, with an optional type (`css`, `js`, `img`; `null` to detect).
Named constructors make the above example much easier:
```php
Hello World
= \Tatter\Assets\Asset::createFromPath('styles.css') ?>
...
```
### Bundle
Typically a project will need more than one single asset. The `Bundle` class allows you to collect
multiple `Asset`s into a single instance. Use the `head()` and `body()` methods to return the `Asset`s
destined for each tag, formatted as blocks of tags.
`Bundle`s can be created one of two ways.
#### Class Properties
Create your own `Bundle` class and use these properties to stage the assets you want it to have:
* `$bundles`: Names of other `Bundle` classes to merge with.
* `$paths`: Relative file paths to make into `Asset`s.
* `$uris`: URLs to make into `Asset`s.
* `$strings`: Direct strings to pass into an `Asset`.
Example:
```php
add(Asset::createFromPath('styles.css')) // Add individual Assets
->merge($someOtherBundle); // Or combine multiple Bundles
// Create more complex Assets
$source = '';
$inHead = true; // Force a JavaScript Asset to the tag
$asset = new Asset($source, $inHead);
}
}
```
### Filter
If you configured the `AssetsFilter` (see above) to load for your routes, you must also associate
the specific assets or bundles per route. Use the config ``$routes`` property, where the route
pattern is the key and the values are arrays of file paths, URLs, or bundle class names. E.g.:
```php
[
'bootstrap/bootstrap.min.css',
'bootstrap/bootstrap.bundle.min.js',
'font-awesome/css/all.min.css',
'styles/main.css',
],
'files' => [
'dropzone/dropzone.min.css',
'dropzone/dropzone.min.js',
],
];
}
```
If you apply the filter via your Routes config file you may also supply bundle class names
as arguments to merge them with any other configured route bundles:
```php
// **app/Config/Routes.php**
$routes->add('files', 'Files::index', ['filter' => 'assets:\App\Filters\FilesFilter']);
```
## Example
You want to make a simple web app for browsing and uploading files, based on Bootstrap's
frontend. Start your CodeIgniter 4 project, then add Bootstrap and DropzoneJS to handle
the uploads:
composer require twbs/bootstrap enyo/dropzone
> Note: You will need to copy files from **vendor** to **public/assets/** to make them
accessible, or use the framework's `Publisher` class to handle this for you.
Add this module as well:
composer require tatter/assets
Edit your **Filters.php** config file to enable the `AssetsFilter` on all routes:
```php
/**
* List of filter aliases that are always
* applied before and after every request.
*
* @var array
*/
public $globals = [
'before' => [
// 'honeypot',
// 'csrf',
],
'after' => [
'assets' => ['except' => 'api/*'],
],
];
```
Create a new `Bundle` to define your Bootstrap files in **app/Bundles/DropzoneJS.php**:
```php
[
'bootstrap/dist/css/bootstrap.min.css',
'bootstrap/dist/js/bootstrap.bundle.min.js',
],
'files/*' => [
\App\Bundles\DropzoneJS::class,
],
'upload' => [
\App\Bundles\DropzoneJS::class,
],
];
```
> Note: We could have made a `Bundle` for Bootstrap as well but since they are only needed for one route this is just as easy.
If you finished all that then your assets should be injected into your `` and `` tags accordingly.
Your view file:
```html
File Upload
Hello
Put your upload form here.
```
... served as:
```html
File Upload
Hello
Put your upload form here.
```
## Vendor Classes
This library includes two abstract class stubs to ease working with third-party assets.
`VendorPublisher` is a wrapper for the framework's [Publisher Library](https://codeigniter.com/user_guide/libraries/publisher.html)
primed for use with `Assets`, and `VendorBundle` is a specialized version of this library's
`Bundle` primed to handle assets published via `VendorPublisher`. Together these two classes
can take a lot of the work out of managing assets you include from external sources.
Let's revisit the example above... Instead of copies the files into **public/assets/** ourselves
(and re-copying every time there is an update) let's create a `VendorPublisher` to do that
for us. In **app/Publishers/BootstrapPublisher.php**:
```php
Note: Since these are external dependencies be sure to exclude them from your repo with your **.gitignore** file.
Now lets use these assets. We can create a new `VendorBundle` and use the new `addPath()`
method to access the same files we just published from Composer's vendor directory.
In **app/Bundles/BootstrapBundle.php**:
```php
addPath('bootstrap/bootstrap.min.css')
->addPath('bootstrap/bootstrap.bundle.min.js');
}
}
```
Now add the new bundle to our **app/Config/Assets.php** routes:
```php
public $routes = [
'*' => [\App\Bundles\BootstrapBundle::class],
];
```
And we have hands-free Bootstrap updates from now on!
## Testing
This library includes some PHPUnit extension classes in **src/Test/** to assist with testing
Assets and Bundles. These are used to test the files from this library but are also available
for your own libraries and projects to use. Simply extend the appropriate test case and add
a data provider method with your class name and criteria to meet. See the test files in
**tests/** for examples.