Download the PHP package jdz/cssmaker without Composer

CssMaker

A modern PHP library for building optimized CSS files from LESS sources with advanced preprocessing, autoprefixing, and minification capabilities.

Features

• 🎨 LESS Compilation: Process LESS files with variables, mixins, and nesting
• 🚀 PostCSS Integration: Automatic vendor prefix addition and CSS optimization
• 🧹 CSS Optimization: Comment removal, whitespace cleaning, and minification
• 📁 Modular Organization: Structured approach with categorized file types
• 🔧 Font Management: Built-in font loading and @font-face generation
• ⚡ Performance: Efficient temporary file handling and process pipeline
• 🧪 Fully Tested: Comprehensive test suite with modular test architecture
• 🔄 Fluent Interface: Method chaining for clean, readable code

Installation

Node.js Dependencies

CssMaker requires Node.js tools for CSS processing. Install them automatically:

Dependencies

jdz/data is required for data handling and processing. jdz/output is required for output handling and logging. jdz/fontmanager is optional (suggested): the bundled example uses it to manage local fonts before handing them to addFont(); the @font-face generation itself is built in.

Quick Start

File Categories

CssMaker organizes LESS files into logical categories processed in order. You can extend the CssMaker class and add your own categories as needed.

Core Categories

• variables: LESS/YAML variables and configuration
• mixins: Reusable LESS mixins and functions
• normalize: CSS reset and normalization rules
• animations: CSS animations and keyframes
• fonts: Font declarations and @font-face rules

Layout Categories

• structure: Main layout and component styles
• icons: Icon fonts and SVG styles

Responsive Categories

• mobile: Mobile-first styles (wrapped in @media(max-width: @screen-breakpoint - 1px))
• screen: Desktop styles (wrapped in @media(min-width: @screen-breakpoint))
• queries: Custom media queries
• print: Print-specific styles (wrapped in @media print)

Configuration Files

PostCSS Configuration (postcss.json)

Browserslist Configuration (.browserslistrc)

Advanced Features

Variable Management

Custom Output Handler

Processing Pipeline

The CssMaker follows a structured build pipeline:

1. 🔧 Preparation

   • Load variables from YAML/LESS files
   • Validate directory structure
   • Initialize temporary file management

2. 📝 Content Merging

   • Merge variables into LESS format
   • Combine mixins and normalize files
   • Add font @font-face declarations
   • Process files by category with media query wrapping

3. ⚙️ LESS Compilation

   • Compile merged LESS to CSS using lessc
   • Handle variables, mixins, nesting, and functions
   • Generate source CSS file

4. 🎯 PostCSS Processing

   • Apply autoprefixer for vendor prefixes
   • Process with PostCSS plugins
   • Use browserslist configuration

5. 🧹 Optimization

   • Remove CSS comments and unnecessary whitespace
   • Clean and normalize formatting
   • Apply minification
6. 📦 Output Generation
   • Generate final CSS file
   • Create minified version (.min.css)
   • Clean up temporary files

Directory Structure

Error Handling

CssMaker provides comprehensive error handling:

Common Error Scenarios:

• Missing required directories
• Invalid LESS syntax
• Missing Node.js dependencies (lessc, postcss, minify)
• File permission issues
• Malformed configuration files

Testing

CssMaker includes a comprehensive test suite. See TESTS.md for detailed information.

Example Usage

See the complete working example:

The example demonstrates:

• Full project setup with directory structure
• Extended CssMaker class
• Configuration file usage
• Font integration
• Multiple file type processing
• Error handling

Browser Support

Default configuration targets:

• Modern Browsers: Chrome, Firefox, Safari, Edge (last 2 versions)
• Market Share: Browsers with > 0.5% usage
• Security: Excludes browsers without security updates
• Mobile: iOS Safari, Chrome Mobile

Customize in .browserslistrc:

Requirements

• PHP: >= 8.2
• Composer: For dependency management
• Node.js + npm: for the lessc, postcss (postcss-cli, autoprefixer, postcss-safe-parser, postcss-discard-comments) and minify command line tools — composer npm:local or composer npm:global installs them. If they are not on the PATH, pass their directory (with a trailing slash) as the second constructor argument: new CssMaker($output, '/path/to/node_modules/.bin/').

PHP Dependencies

• jdz/output: ^1.0 (Output handling)
• jdz/data: ^2.0 (Data processing)
• symfony/yaml: ^7.4 (YAML parsing)
• symfony/process: ^7.4 (External process execution)
• jdz/fontmanager (Font management - optional, suggested)

Performance Tips

1. Use file caching - Only rebuild when source files change
2. Minimize file count - Combine related LESS files
3. Optimize images - Use appropriate formats and compression
4. Monitor build time - Profile with verbose output
5. Cache font files - Reuse font declarations across builds

Troubleshooting

Common Issues

"lessc command not found"

"postcss command not found"

"minify command not found"

"Permission denied" errors

"LESS compilation failed"

• Check LESS syntax in source files
• Verify variable names and references
• Ensure all imported files exist

Debug Mode

Enable verbose output for troubleshooting:

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Ensure all tests pass (composer test)
5. Follow PSR-12 coding standards
6. Update documentation as needed
7. Commit changes (git commit -m 'Add amazing feature')
8. Push to branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Changelog

• 1.0.3 — The cleaner no longer strips // "comments": lessc already removes them, and the pattern cut every URL (url(https://…), SVG data URIs) to the end of its line. Each /* */ comment ends at its own close (/**/ used to swallow the next rule); no-break spaces and non-UTF-8 bytes survive (removeSpaces() was a TypeError on Latin-1). @font-face lists woff2 before ttf. A second process() on one maker merges the font themes once; minify writes through a build path with spaces; a font without an id throws its own error. trim() replaces mb_trim() (PHP 8.4 only, under php >=8.2).

• 1.0.2 — PHP >= 8.2, jdz/data ^2.0, Symfony ^7.4, PHPUnit 11; the cleaner also strips // single-line comments, and removes comments before collapsing whitespace.
• 1.0.1 — Output goes through jdz/output (the bundled Output class is gone); test suite split per feature.
• 1.0.0 — Initial release.

Support

• 📧 Email: [email protected]
• 🌐 Website: https://joffreydemetz.com
• 📦 Package: https://packagist.org/packages/jdz/cssmaker
• 🐛 Issues: GitHub Issues