Getting Started

Minimal Steps

Installation Run:

composer require brunschgi/terrific-core-bundle:^1.0

// config/bundles.php
return [
    // ...
    Brunschgi\TerrificCoreBundle\TerrificCoreBundle::class => ['all' => true],
];

First Use Case: Asset Optimization TerrificCoreBundle integrates with Assetic to provide Terrific-specific filters (e.g., for CSS/JS minification, source maps, or vendor prefixing). Start by configuring Assetic in config/packages/assetic.yaml (Symfony) or app/config/config.yml (Laravel <5.4):
```
assetic:
    filters:
        terrific_css:
            class: Brunschgi\TerrificCoreBundle\Assetic\Filter\TerrificCssFilter
        terrific_js:
            class: Brunschgi\TerrificCoreBundle\Assetic\Filter\TerrificJsFilter
```

Basic Frontend Structure The bundle assumes a Terrific Concept-compliant structure. Create a web/ directory with:

web/
├── css/
│   ├── app.css
│   └── vendors/
├── js/
│   ├── app.js
│   └── vendors/
└── fonts/

Use Assetic to compile assets in your Twig templates:

{% stylesheets
    'css/app.css'
    filter='terrific_css'
    output='css/compiled.css'
%}
    <link rel="stylesheet" href="{{ asset_url }}">
{% endstylesheets %}

Implementation Patterns

Workflows

Modular Asset Management
- Vendor Assets: Place third-party libraries (e.g., Bootstrap, jQuery) in web/js/vendors/ and web/css/vendors/.
- Custom Assets: Keep project-specific CSS/JS in web/css/app.css and web/js/app.js.
- Assetic Dumps: Run php bin/console assetic:dump (Symfony) or php artisan assetic:dump (Laravel) to compile assets.
Terrific-Specific Features
- CSS/JS Prefixing: Use the terrific_css/terrific_js filters to auto-prefix vendor classes (e.g., .btn → .vendor-btn).
- Source Maps: Enable in Assetic config for debugging:
```
filters:
    terrific_css:
        debug: true  # Generates source maps
```
Integration with TerrificComposerBundle
- If using TerrificComposerBundle, leverage its automatic vendor asset loading to avoid manual web/ directory management:
```
composer require brunschgi/terrific-composer-bundle
```
- Configure in config/packages/terrific_composer.yaml:
```
terrific_composer:
    enabled: true
    output_dir: '%kernel.project_dir%/web'
```

Tips for Daily Use

Hot Reloading: Use Symfony’s built-in server (php bin/console server:run) or Laravel’s php artisan serve with Assetic’s --watch flag for live updates:
```
php bin/console assetic:watch
```
Environment-Specific Configs: Override Assetic filters in config/packages/assetic_{env}.yaml (e.g., disable minification in dev):
```
# config/packages/assetic_dev.yaml
filters:
    terrific_css:
        minify: false
```

Gotchas and Tips

Pitfalls

Assetic Configuration Conflicts
- Issue: If Assetic is already configured (e.g., by another bundle like SymfonyAsseticBundle), the terrific_* filters may not apply.
- Fix: Explicitly merge filters in assetic.yaml:
```
assetic:
    filters:
        terrific_css: ~  # Overrides existing CSS filters
        terrific_js: ~  # Overrides existing JS filters
```
Dev vs. Prod Builds
- Issue: Forgetting to dump assets in production (assetic:dump --env=prod) leads to uncompiled CSS/JS.
- Fix: Add a post-deploy script or use Laravel’s mix (if using Webpack) for production builds.

Terrific Concept Assumptions

Issue: The bundle expects a specific web/ structure. Deviations (e.g., custom asset paths) may break filters.

Fix: Extend the bundle’s TerrificCssFilter/TerrificJsFilter to support custom paths:

// src/Assetic/Filter/CustomTerrificFilter.php
namespace App\Assetic\Filter;
use Brunschgi\TerrificCoreBundle\Assetic\Filter\TerrificCssFilter;

class CustomTerrificFilter extends TerrificCssFilter {
    protected function getVendorPath() {
        return $this->getContext()->getParameter('custom_vendor_path');
    }
}

Debugging

Filter Not Applying? Check if the filter is registered in Assetic’s dump output:
```
php bin/console assetic:dump --debug
```
Look for terrific_css/terrific_js in the compiled asset headers.
Prefixing Issues If classes aren’t prefixed correctly, verify the filter’s getVendorPrefix() method (extend the filter if needed):
```
// Override in a custom filter
public function getVendorPrefix() {
    return 'myapp_'; // Custom prefix
}
```

Extension Points

Custom Filters Extend the base filters to add logic (e.g., auto-versioning):

// src/Assetic/Filter/VersionedTerrificFilter.php
use Brunschgi\TerrificCoreBundle\Assetic\Filter\TerrificCssFilter;

class VersionedTerrificFilter extends TerrificCssFilter {
    public function filterLoad() {
        $content = parent::filterLoad();
        return $this->addVersionHash($content);
    }

    private function addVersionHash($content) {
        return $content . "\n/*! Version: " . filemtime($this->getPath()) . " */";
    }
}

Asset Path Overrides Use dependency injection to override paths:

# config/services.yaml
services:
    Brunschgi\TerrificCoreBundle\Assetic\Filter\TerrificCssFilter:
        arguments:
            $vendorPath: '%kernel.project_dir%/custom_vendors'

Twig Extensions Add custom Twig functions for dynamic asset loading:

// src/Twig/AppExtension.php
namespace App\Twig;
use Brunschgi\TerrificCoreBundle\TerrificCoreBundle;

class AppExtension extends \Twig\Extension\AbstractExtension {
    public function getFunctions() {
        return [
            new \Twig\TwigFunction('terrific_asset', [$this, 'getTerrificAsset']),
        ];
    }

    public function getTerrificAsset($path) {
        return $this->env->getExtension('assetic')->getAssetUrl($path);
    }
}

Use in Twig:

<link rel="stylesheet" href="{{ terrific_asset('css/app.css') }}">

Terrific Core Bundle Laravel Package