캐싱 및 최소화

파이프라인의 마지막 부분에는 운영 환경과 관련된 세 가지 고려 사항이 있습니다. 동일한 입력을 다시 컴파일하지 않고, 요청마다 컴파일러를 새로 구성하는 비용을 피하며, 생성된 CSS의 크기를 줄이는 것입니다. 이 세 가지는 모두 컴파일러를 감싸는 PHP 측 헬퍼입니다.

캐싱

CSS 생성은 호출할 때마다 전체 파이프라인을 실행합니다. 요청 사이에 콘텐츠가 바뀌지 않는 경우 파일 기반 캐시는 결과를 디스크에 저장해 다음 호출부터 제공합니다.

tw::generate()에 cache을 전달하세요. 기본 디렉터리를 사용하려면 true를, 사용자 지정 디렉터리를 사용하려면 경로 문자열을 지정합니다.

use TailwindPHP\tw;

// Cache to the default directory: sys_get_temp_dir() . '/tailwindphp'
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => true,
]);

// Cache to a custom directory
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => '/path/to/cache',
]);

// With a time-to-live (seconds)
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => true,
    'cacheTtl' => 3600, // expire after 1 hour
]);

캐시 디렉터리가 없으면 자동으로 생성됩니다.

캐시 키

키는 콘텐츠, CSS 설정, minify 플래그에서 파생되며 파일 이름 tailwind_<hash>.css로 해시됩니다. 마크업이나 CSS 입력이 변경되거나 최소화 여부가 달라지면 키도 달라져 별도의 파일이 생성됩니다.

키에 포함되는 CSS 설정은 인라인 css와 importPaths에 지정된 파일의 콘텐츠입니다. 중첩된 @import로 해당 파일 안에서 불러온 파일과 TailwindPHP 버전은 키에 포함되지 않습니다. 중첩된 가져오기 파일을 수정하거나 패키지를 업그레이드한 후 캐시를 비우지 않으면 이전 출력이 계속 제공됩니다.

유효 기간

cacheTtl는 수명(초)입니다. 캐시 적중 시 파일의 수정 시각을 현재 시각과 비교합니다. 파일이 cacheTtl보다 오래되면 캐시 미스로 처리해 다시 컴파일합니다. cacheTtl가 없으면 항목은 만료되지 않으므로 직접 비워야 합니다.

캐시 비우기

tw::clearCache()(또는 clearCache() 함수)는 캐시 디렉터리에서 tailwind_*.css 파일을 제거하고 삭제한 파일 수를 반환합니다.

use TailwindPHP\tw;
use function TailwindPHP\clearCache;

$deleted = tw::clearCache();                  // default directory
$deleted = tw::clearCache('/path/to/cache');  // custom directory
clearCache('/path/to/cache');                 // function form

컴파일러 상태 캐시

출력 캐시는 같은 콘텐츠가 다시 사용될 때만 도움이 됩니다. 호출할 때마다 콘텐츠가 바뀐다면 비용이 큰 작업은 컴파일러 자체를 구성하는 일입니다. @import "tailwindcss" 확인, 번들 리소스 파싱, 테마 누적이 여기에 포함됩니다. 이 단계는 입력 CSS에만 의존하므로 저장해 재사용할 수 있습니다.

tw::compile()(또는 new TailwindCompiler($css, $options))에 stateCacheFile을 전달하세요.

use TailwindPHP\tw;

$compiler = tw::compile($themeCss, [
    'stateCacheFile' => __DIR__ . '/cache/tailwind-state.php',
]);

$css = $compiler->generateExact($html, true);

처음 구성할 때 상태를 일반 PHP 파일로 해당 경로에 기록하면 OPcache가 요청 간에 공유할 수 있습니다. 이후 구성에서는 다시 파싱하지 않고 파일을 불러옵니다. 출력은 캐시를 사용하지 않은 컴파일러의 출력과 바이트 단위로 동일합니다.

• 파일은 엔진 지문(TailwindPHP 소스 및 리소스의 크기와 수정 시각), 입력 CSS 및 base와 importSearchPaths 옵션에서 파생된 키, 그리고 입력에서 가져온 모든 파일의 크기와 수정 시각을 기준으로 검증됩니다. 일치하지 않으면 파일을 다시 구성하고 기록하므로 TailwindPHP를 업그레이드하거나 가져온 파일을 수정해도 별도 작업이 필요하지 않습니다.
• 경로는 직접 관리해야 합니다. 서로 다른 입력 CSS마다 파일 하나씩 사용하고 웹 서버가 쓸 수 있는 디렉터리에 두세요. 쓰기는 원자적으로 처리됩니다(임시 파일과 rename() 사용).
• 사용자 지정 importResolver를 사용하는 입력은 확인자 동작의 지문을 생성할 수 없으므로 캐시를 우회합니다.
• 하위 수준 compile() 배열 API에도 같은 캐시를 TailwindPHP\StateCache\compileCssCached($css, $cacheFile, $options)로 사용할 수 있습니다.

tw::generate()는 stateCacheFile을 받지 않으며 호출할 때마다 새 컴파일러를 만듭니다. 구성 비용이 중요하다면 컴파일러 인스턴스를 사용하세요.

최소화

최소화는 운영 환경용 출력의 크기를 줄입니다. minify 플래그는 직렬화 중에 최소화된 CSS를 바로 출력하므로 가장 빠르고 정확한 방법입니다. tw::minify()는 기존 CSS 문자열에 문자열 기반 최소화 도구(src/_tailwindphp/CssMinifier.php)를 실행합니다.

use TailwindPHP\tw;

// Minify during generation (serializer path, preferred)
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'minify' => true,
]);

// Or minify an existing string (string-based post-pass)
$css = tw::generate('<div class="flex p-4">Hello</div>');
$minified = tw::minify($css);

두 경로는 구조는 동일하지만 바이트까지 같지는 않습니다. 직렬화기 경로는 문자열 처리 과정에서 하나로 합쳐지는 하위 :not() 선택자를 보존하므로, 생성된 출력에는 minify 플래그를 사용하고 문자열로 전달되는 CSS에는 tw::minify()를 사용하세요.

기능

두 경로 모두 동일한 크기 축소 작업을 수행합니다:

설계상 중복 선택자를 병합하거나 축약 속성을 결합하지 않습니다. 두 작업 모두 디버깅을 어렵게 하고 캐스케이드에 영향을 줄 수 있기 때문입니다.

CLI: --minify 대 --optimize

CLI는 두 플래그를 통해 직렬화기 축소 경로를 제공합니다:

# Optimize and minify (smallest output)
tailwindphp -i ./src/app.css -o ./dist/styles.css --minify   # or -m

# Meant to optimize without minifying
tailwindphp -i ./src/app.css -o ./dist/styles.css --optimize

현재 릴리스에서는 --optimize도 축소하므로 두 명령은 같은 바이트를 기록합니다(#9). lightningcss에 해당하는 변환은 어느 쪽이든 모든 빌드에서 실행되므로, 플래그가 없는 일반 출력은 이미 최적화된 읽기 쉬운 형식입니다.

나머지 공개 API인 tw::generate(), tw::compile(), 검사 메서드 및 입력 형식은 API 참고를 확인하세요.