### Install Sage SVG Package

Source: https://github.com/log1x/sage-svg/blob/master/README.md

Installs the Sage SVG package using Composer. This is the primary method for adding the package to your Sage 10 project. Ensure Composer is installed and accessible in your project's root.

```bash
composer require log1x/sage-svg
```

--------------------------------

### WordPress Attachment Integration with ACF and Post Thumbnails

Source: https://context7.com/log1x/sage-svg/llms.txt

Demonstrates how to integrate SVGs using ACF fields (image type) or WordPress post thumbnails. It shows examples with Blade templates and helper functions, assuming ACF is configured for SVG uploads.

```php
<?php
// With ACF image field (SVG upload)
$logoField = get_field('site_logo'); // Returns: ['id' => 456, 'url' => '...']
$logo = get_svg($logoField, 'site-logo');

// In a Blade template with ACF
@svg(get_field('header_icon'), 'header-icon', ['aria-label' => 'Header'])

// With WordPress post thumbnail (if SVG)
$featuredSvg = get_svg(
    ['id' => get_post_thumbnail_id()],
    'featured-graphic'
);

// Multiple ACF SVGs in a loop
@foreach(get_field('icon_list') as $icon)
    @svg($icon['svg_file'], 'list-icon', ['aria-label' => $icon['label']])
@endforeach
```

--------------------------------

### Asset Manifest Resolution with Laravel Mix and Vite

Source: https://context7.com/log1x/sage-svg/llms.txt

Illustrates how the package automatically resolves SVG paths using asset manifest files (mix-manifest.json or Vite's manifest.json) for cache-busted filenames. This ensures that updated assets are correctly loaded.

```json
// mix-manifest.json or vite manifest
{
  "/images/logo.svg": "/images/logo.svg?id=abc123",
  "/images/icon.svg": "/images/icon.abc123.svg"
}
```

```php
<?php
// Automatically resolves through manifest
$logo = get_svg('images.logo');
// Looks up: mix-manifest.json -> /images/logo.svg?id=abc123

@svg('images.icon')
{{-- Resolves versioned filename from manifest --}}

// Vite bundle resolution
// resources/images/icon.svg -> build/assets/icon.abc123.svg
$icon = get_svg('images.icon');
```

--------------------------------

### Sage SVG Configuration - Publishing and Customization

Source: https://context7.com/log1x/sage-svg/llms.txt

The configuration file (`config/svg.php`) controls default SVG paths, classes, attributes, and custom Blade directives. Publish the configuration using the provided Artisan command. The configuration allows setting a default path, class, and attributes for all SVGs.

```bash
# Publish configuration file
wp acorn vendor:publish --provider='Log1x\SageSvg\SageSvgServiceProvider'
```

```php
<?php
// config/svg.php

return [
    // Default path for SVG file resolution
    'path' => public_path('dist/images'),

    // Default class applied to all SVGs
    'class' => 'inline-block',

    // Default attributes for all SVGs
    'attributes' => [
        'fill' => 'currentColor',
        'aria-hidden' => 'true',
    ],

    // Custom Blade directives for icon libraries
    'directives' => [
        'fa' => 'fontawesome.solid',      // Usage: @fa('download')
        'brands' => 'fontawesome.brands', // Usage: @brands('twitter')
        'hero' => 'heroicons.outline',    // Usage: @hero('search')
    ],
];
?>
```

```php
{{-- Using custom directives after configuration --}}
@fa('download', 'w-4 h-4')
{{-- Resolves to: dist/images/fontawesome/solid/download.svg --}}

@brands('github', 'text-gray-900', ['aria-label' => 'GitHub'])
{{-- Resolves to: dist/images/fontawesome/brands/github.svg --}}

@hero('search')
{{-- Resolves to: dist/images/heroicons/outline/search.svg --}}
```

--------------------------------

### Sage SVG Facade - SageSvg::render()

Source: https://context7.com/log1x/sage-svg/llms.txt

The `SageSvg::render()` facade provides static access to the SVG rendering functionality, mirroring the parameters of the `get_svg()` helper function. It's useful in controllers or other classes for programmatic SVG generation.

```php
<?php
use Log1x\SageSvg\Facades\SageSvg;

// Direct rendering via facade
$svg = SageSvg::render('images.logo', 'logo-class', ['width' => '100']);
echo $svg;

// In a controller
class HeaderController extends Controller
{
    public function compose()
    {
        return [
            'logo' => SageSvg::render('images.logo', 'h-12 w-auto'),
            'menuIcon' => SageSvg::render('icons.hamburger', 'w-6 h-6'),
        ];
    }
}

// With all parameters
$complexSvg = SageSvg::render(
    'graphics.illustration',
    'w-full max-w-2xl',
    [
        'aria-hidden' => 'true',
        'focusable' => 'false',
        'role' => 'presentation',
    ],
    ['idPrefix' => 'hero-illustration']
);
?>
```

--------------------------------

### Publish Sage SVG Configuration

Source: https://github.com/log1x/sage-svg/blob/master/README.md

Publishes the Sage SVG configuration file (`svg.php`) to your project using Acorn's vendor:publish command. This allows you to customize SVG settings according to your project's needs. The configuration file contains detailed DocBlocks for guidance.

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

--------------------------------

### Error Handling for Missing SVG Files

Source: https://context7.com/log1x/sage-svg/llms.txt

Explains how the package handles missing SVG files by outputting HTML comments instead of throwing errors. This is useful for graceful degradation in templates and conditional rendering.

```php
<?php
// Missing file handling
$missing = get_svg('nonexistent.icon');
echo $missing; // Output: <!-- nonexistent/icon.svg not found. -->

// In production blade templates - fails silently
@svg('missing.icon')
{{-- Output: <!-- missing/icon.svg not found. --> --}}

// Safe to use in conditionals
@if($icon = get_svg('optional.icon'))
    <div class="has-icon">{{ $icon }}</div>
@else
    <div class="no-icon">Icon not available</div>
@endif

// Checking existence before rendering
if (file_exists(public_path('images/dynamic.svg'))) {
    echo get_svg('images.dynamic', 'dynamic-class');
}
```

--------------------------------

### SVG Path Resolution Strategies

Source: https://context7.com/log1x/sage-svg/llms.txt

Details the priority order for resolving SVG paths: WordPress attachments, asset manifests, relative paths (configurable base), and absolute paths. It also covers dot notation conversion for nested paths.

```php
<?php
// 1. WordPress attachment (highest priority)
$svg1 = get_svg(['id' => 123]); // Uses get_attached_file(123)

// 2. Asset manifest lookup
$svg2 = get_svg('images.logo'); // Checks mix-manifest.json or vite manifest

// 3. Relative to config path (public_path() by default)
$svg3 = get_svg('icons/search.svg'); // Looks in: public_path() . '/icons/search.svg'

// 4. Dot notation conversion
$svg4 = get_svg('images.icons.user'); // Converts to: images/icons/user.svg

// 5. Absolute from webroot
$svg5 = get_svg('/app/uploads/2023/custom.svg'); // Strips leading slash, resolves absolutely

// If not found, returns HTML comment
// Output: <!-- images/missing.svg not found. -->
```

--------------------------------

### Render SVG using SageSvg Facade

Source: https://github.com/log1x/sage-svg/blob/master/README.md

Shows how to use the `SageSvg` Facade to render SVGs programmatically. This method is an alternative to the helper function and is useful when working with Facades in your application. Ensure the Facade is properly imported.

```php
use Log1x\SageSvg\Facades\SageSvg;

$image = SageSvg::render('images.logo');
```

--------------------------------

### Sage SVG Helper Function - get_svg()

Source: https://context7.com/log1x/sage-svg/llms.txt

The global `get_svg()` helper function renders SVG content as an HtmlString object. It accepts file paths (dot notation or absolute), CSS classes, attributes, and options like `idPrefix` for unique instances. It can also handle ACF field arrays for media attachments.

```php
<?php
// Basic SVG rendering
$logo = get_svg('images.logo');
echo $logo; // Outputs: <svg>...</svg>

// With CSS classes
$icon = get_svg('icons.search', 'w-5 h-5 text-gray-600');

// With WordPress ACF field (attachment array)
$customLogo = get_svg(
    get_field('logo_svg'), // ['id' => 123, 'url' => '...']
    'custom-logo',
    ['aria-label' => 'Company Logo']
);

// With ID prefix for unique instances
$iconWithPrefix = get_svg(
    'icons.heart',
    'icon',
    ['data-favorite' => 'true'],
    ['idPrefix' => 'favorite-btn']
);
// Output: <svg class="icon" data-favorite="true"><use href="#favorite-btn-icon-id"></use></svg>

// Multiple classes as array
$styledIcon = get_svg('icons.menu', ['flex', 'items-center', 'text-white']);
?>
```

--------------------------------

### Render SVG using Helper Function

Source: https://github.com/log1x/sage-svg/blob/master/README.md

Illustrates the usage of the global `get_svg()` helper function for rendering SVGs outside of Blade templates, such as in controllers or other PHP files. It handles relative and absolute paths, accepts CSS classes, and can process WordPress attachment IDs.

```php
# 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'
);
```

--------------------------------

### Sage SVG Blade Directive - @svg

Source: https://context7.com/log1x/sage-svg/llms.txt

The `@svg` Blade directive renders SVG files inline. It supports dot notation for paths, CSS classes, and HTML attributes. Absolute paths from the webroot are also handled. The output is an SVG HTML element.

```php
{{-- Basic usage with dot notation path --}}
@svg('images.logo')

{{-- With CSS classes --}}
@svg('images.icon', 'w-8 h-8 text-blue-500')

{{-- With classes and attributes --}}
@svg('images.social.twitter', 'w-6 h-6', ['aria-label' => 'Twitter Icon', 'role' => 'img'])

{{-- Absolute path from webroot --}}
@svg('app/uploads/2023/icons/custom.svg', 'inline-block', ['data-icon' => 'custom'])

{{-- Output: <svg class="inline-block" data-icon="custom" viewBox="0 0 24 24">...</svg> --}}
```

--------------------------------

### Render SVG using Blade Directive

Source: https://github.com/log1x/sage-svg/blob/master/README.md

Demonstrates how to use the `@svg()` Blade directive to render SVGs directly within your Blade templates. It supports relative paths (using dot notation) and absolute paths from the webroot, with options for adding CSS classes and ARIA attributes.

```blade
# 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'])
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.