README

A powerful PHP wrapper for wikimedia/less.php that provides enhanced LESS compilation with caching, advanced configuration options, and streamlined error handling.

Features

Smart Caching: Automatic file-based caching with TTL support
Flexible Configuration: Comprehensive options for paths, variables, and compilation behavior
Global Variables: Define LESS variables available across all compiled files
Auto-loading: Automatically include mixin files before compilation
Custom Functions: Register custom PHP functions for use in LESS files
Import Path Management: Configure multiple import directories with URL mappings
Enhanced Error Handling: Detailed error messages with context

Requirements

PHP 8.2 or higher
Composer

Installation

composer require jbzoo/less

Quick Start

use JBZoo\Less\Less;

// Basic usage
$less = new Less();
$cssPath = $less->compile('/path/to/styles.less');

// With custom cache directory
$less = new Less(['cache_path' => './custom-cache']);
$cssPath = $less->compile('./assets/styles.less');

Advanced Configuration

All configuration options are optional and can be customized based on your needs:

use JBZoo\Less\Less;

try {
    $less = new Less([
        // Compilation behavior
        'force'        => false,                    // Force recompilation on each call
        'debug'        => false,                    // Enable source maps (future feature)

        // Path configuration
        'root_url'     => 'http://site.com/',       // Root URL for CSS asset references
        'root_path'    => '/full/path/to/site',     // Full path to web root directory

        // LESS features
        'global_vars'  => [                         // Global variables available in all files
            'primary-color' => '#007bff',           // Becomes @primary-color: #007bff;
            'font-size'     => '14px',              // Becomes @font-size: 14px;
        ],

        'autoload'     => [                         // Files automatically included before compilation
            '/full/path/to/mixins.less',
            '/full/path/to/variables.less',
        ],

        'import_paths' => [                         // Directory mappings for @import statements
            '/full/path/to/assets/less/' => 'http://site.com/assets/less/',
            './relative/path/to/less/'   => './relative/path/to/less/',
        ],

        // Caching configuration
        'cache_path'   => './cache',                // Cache directory location
        'cache_ttl'    => 2592000,                  // Cache TTL in seconds (30 days)

        // Custom functions (advanced feature)
        'functions' => [
            'str-reverse' => function ($arg) {
                $arg->value = strrev($arg->value);
                return $arg;
            },
        ],
    ]);

    // Add import paths dynamically
    $less->setImportPath(
        '/additional/import/directory/',
        'http://site.com/additional/directory/'     // URL mapping (optional)
    );

    // Compile LESS files
    $cssPath1 = $less->compile('/full/path/to/styles.less');
    $cssPath2 = $less->compile('./relative/path/to/styles.less');
    $cssPath3 = $less->compile(
        './relative/path/to/styles.less',
        'http://site.com/custom/base/path/'         // Override base path for URLs
    );

} catch (JBZoo\Less\Exception $e) {
    echo 'Compilation error: ' . $e->getMessage();
}

Configuration Options

Option	Type	Default	Description
`force`	bool	`false`	Force recompilation on every call, ignoring cache
`debug`	bool	`false`	Enable debug mode (future: source maps)
`root_url`	string	auto-detected	Base URL for asset references in CSS
`root_path`	string	auto-detected	Full filesystem path to web root
`global_vars`	array	`[]`	Global LESS variables available in all files
`autoload`	array	`[]`	LESS files to automatically include before compilation
`import_paths`	array	`[]`	Directory mappings for @import resolution
`cache_path`	string	`'./cache'`	Directory for storing compiled CSS files
`cache_ttl`	int	`2592000`	Cache time-to-live in seconds (30 days)
`functions`	array	`[]`	Custom PHP functions callable from LESS

Development

Running Tests

# Install dependencies
make update

# Run all tests and code quality checks
make test-all

# Run only PHPUnit tests
make test

# Run only code style checks
make codestyle

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Run tests and ensure code quality (make test-all)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License. See LICENSE file for details.

jbzoo / less

Maintainers

Details