包简介

Symfony bundle for combining and serving CSS/JS theme files with HTTP caching and source maps

README 文档

README

A Symfony bundle that combines and serves CSS/JS files as single bundled assets with intelligent HTTP caching and source map support.

Features

File combining — merge multiple CSS or JS files into a single response
Namespace paths — organize assets with @namespace/file.css references
HTTP caching — automatic ETag, Last-Modified, and 304 Not Modified responses
Source maps — v3 source map generation for combined files (configurable)
Twig integration — themeAsset() function for easy template usage
Performance profiling — optional Stopwatch integration

Requirements

PHP 8.4+
Symfony 8.0+
Twig 3.0+ or 4.0+

Installation

composer require psychob/theme-bundle

The bundle auto-registers via Symfony Flex.

Configuration

Create or edit config/packages/theme.yaml:

theme:
    # Enable source map generation (useful in dev)
    sourcemaps: '%kernel.debug%'

    # Map namespace aliases to filesystem directories
    paths:
        '%kernel.project_dir%/assets/css': app
        '%kernel.project_dir%/vendor/some-lib/styles': lib

    # Define combined file bundles
    files:
        app.css:
            - '@app/reset.css'
            - '@app/layout.css'
            - '@lib/components.css'
            - '@app/main.css'
        app.js:
            - '@app/utils.js'
            - '@app/main.js'

Options

Option	Type	Default	Description
`sourcemaps`	`bool`	`false`	Enable source map generation
`paths`	`map`	`{}`	Maps filesystem directories to namespace aliases
`files`	`map`	`{}`	Defines combined output files and their source files

Usage

Twig

Use themeAsset() to generate URLs to combined files:

<link rel="stylesheet" href="{{ themeAsset('app.css') }}">
<script src="{{ themeAsset('app.js') }}"></script>

This generates URLs like /_/theme/app.css and /_/theme/app.js.

HTTP Caching

The bundle serves combined files at /_/theme/{file} with:

ETag header for cache validation
Last-Modified header as fallback
304 Not Modified responses when content hasn't changed
Cache-Control: public, must-revalidate

Source maps are served at /_/theme/{hash}.{ext}.map with immutable, long-lived cache headers (1 year).

Namespaces

The @namespace/ prefix in file paths resolves to the directory mapped in paths:

theme:
    paths:
        '%kernel.project_dir%/assets/css': app

    files:
        app.css:
            - '@app/reset.css'   # resolves to %kernel.project_dir%/assets/css/reset.css

Development

# Run tests
composer test

# Run tests with coverage
composer test:coverage

# Static analysis
composer psalm

# Check code style
composer lint

# Fix code style
composer format

License

MPL-2.0

psychob/theme-bundle 适用场景与选型建议

psychob/theme-bundle 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 66 次下载、GitHub Stars 达 0，最近一次更新时间为 2026 年 02 月 11 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 psychob/theme-bundle 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 psychob/theme-bundle 我们能提供哪些服务？

定制开发 / 二次开发

基于 psychob/theme-bundle 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

psychob/theme-bundle

包简介