README

Sage SVG is a simple package for using inline SVGs in your Sage 10 projects.

Requirements

Sage >= 10.0
PHP >= 7.4
Composer

Installation

Install via Composer:

$ composer require log1x/sage-svg

Usage

By default, the following paths are checked for your SVG (in order):

If passed an array containing id, it is assumed to be a WordPress attachment and is ran through get_attached_file().
Your default asset manifest (usually mix-manifest.json).
Path relative to config('svg.path') which is public_path() by default.
Absolute web root path.

Blade Directive

Unless you require advance functionality from somewhere such as a Controller, the best way to use Sage SVG is with the Blade directive straight in your templates.

# Relative path (with dot notation) – resolves to `app/themes/<your theme>/dist/images/logo.svg` by default
@svg('images.logo')

# Absolute path from webroot with `w-32 h-auto` CSS classes and an aria-label
@svg('app/uploads/2019/07/logo.svg', 'w-32 h-auto', ['aria-label' => 'Logo'])

Helper

The easiest way to use SVG outside of a Blade template is the global get_svg() helper function. get_svg() will return false if no image is found.

# Relative path
$image = get_svg('images.logo');

# Absolute path from webroot with `w-32 h-auto` CSS classes
$image = get_svg('app/uploads/2019/07/logo.svg', 'w-32 h-auto');

# WordPress attachment (e.g. ACF field) with `my-logo` CSS class
$image = get_svg(
    get_field('logo_svg'),
    'my-logo'
);

App Container

While it's easier to use the Helper function, if it not available or sane for your scenario, you can render your SVG using the initialized SageSvg instance from the app container.

use Log1x\SageSvg\SageSvg;
use function Roots\app;

$image = app(SageSvg::class)->render('images.logo');

Configuration

The configuration file, svg.php, can be published using Acorn:

$ wp acorn vendor:publish --provider='Log1x\SageSvg\SageSvgServiceProvider'

You can read the DocBlocks in config/svg.php for more details.

Why another SVG Package?

Didn't you author Blade SVG Sage? Why another SVG package?

While I do have my fork of Blade SVG called Blade SVG Sage, I find it rather underwhelming due to the following reasons:

Unable to handle WordPress attachments
Unable to inline SVGs that aren't set in a specific path
Unable to properly use the asset manifest.
I know QWp6t

Bug Reports

If you discover a bug in Sage SVG, please open an issue.

Contributing

Contributing whether it be through PRs, reporting an issue, or suggesting an idea is encouraged and appreciated.

License

Sage SVG is provided under the MIT License.

log1x / sage-svg

Maintainers

Details