Skip to content

Commit 4b67d4b

Browse files
sakibwebsakibweb
authored
Update README.md
1 parent 176693d commit 4b67d4b

1 file changed

Lines changed: 212 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 212 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,212 @@
1-
# css2php
1+
# CSS2PHP
2+
3+
**Convert CSS files/URLs to PHP arrays**
4+
5+
[![Version](https://img.shields.io/github/v/release/sakibweb/css2php?style=flat-square)](https://github.com/sakibweb/css2php/releases)
6+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7+
[![GitHub Repo stars](https://img.shields.io/github/stars/sakibweb/css2php?style=social)](https://github.com/sakibweb/css2php)
8+
9+
**A versatile command-line tool to convert CSS stylesheets (from local files or URLs) into PHP arrays. Ideal for integrating CSS styles directly into your PHP applications, especially for dynamic styling or frameworks that utilize PHP-based styling.**
10+
11+
## Features
12+
13+
* **Advanced CSS Parsing:** Leverages `cssutils` for robust parsing of CSS, handling complex stylesheets, including media queries and pseudo-classes.
14+
* **Command-Line Interface (CLI):** Easy to use via the terminal, making it perfect for automation and integration into build processes.
15+
* **Comprehensive Reporting:** Provides detailed statistics on the conversion process, including input/output sizes, processing time, class counts, and syntax validation results.
16+
* **Error Handling:** Includes options to skip errors and continue processing or to halt on errors for strict validation.
17+
* **File Overwrite Control:** Option to prevent overwriting existing output files, ensuring data safety.
18+
* **Flexible Input Sources:** Accepts both local CSS file paths and remote CSS URLs as input.
19+
* **Merge Functionality:** Capable of merging multiple PHP array files (generated by CSS2PHP) into a single, consolidated file, useful for combining styles from different sources.
20+
* **Output Customization:** Allows setting a custom output directory and filename prefix for generated PHP files.
21+
* **PHP Syntax Validation & Auto-Fix:** Validates the generated PHP array for syntax errors and attempts to automatically fix common issues, ensuring code correctness.
22+
* **Statistics (Detailed):** Generates in-depth processing statistics, including class counts, compression ratio, media query and pseudo-class detection, and syntax validation status.
23+
* **Tailwind CSS Compatibility:** Handles common Tailwind CSS escape patterns in class names for cleaner PHP output.
24+
* **Timeout Control:** Sets a timeout for fetching remote CSS files, preventing indefinite hangs.
25+
* **Version Information:** Displays version details and author information.
26+
27+
## Getting Started
28+
29+
### Installation
30+
31+
1. **Prerequisites:**
32+
* Python 3.6 or higher
33+
* `pip` (Python package installer)
34+
* `php` (for syntax validation - ensure it's in your system's PATH)
35+
36+
2. **Install CSS2PHP via pip:**
37+
38+
```bash
39+
pip install css2php-cli
40+
```
41+
42+
Alternatively, you can clone the repository and run it directly:
43+
44+
```bash
45+
git clone https://github.com/sakibweb/css2php.git
46+
cd css2php
47+
pip install -r requirements.txt # Install dependencies
48+
```
49+
50+
### Usage
51+
52+
Basic conversion of a CSS file to a PHP array:
53+
54+
```bash
55+
css2php styles.css
56+
```
57+
58+
This will create a PHP file named `styles.php` in the `./output` directory (if it exists, otherwise it will be created). The PHP file will contain a PHP array representation of the CSS styles.
59+
60+
**Converting multiple CSS files:**
61+
62+
```bash
63+
css2php style1.css style2.css theme.css
64+
```
65+
66+
**Converting a CSS URL:**
67+
68+
```bash
69+
css2php https://example.com/styles.css
70+
```
71+
72+
**Specifying output directory and filename prefix:**
73+
74+
```bash
75+
css2php styles.css -o php_styles -n my_prefix_
76+
```
77+
78+
This will save the output to `php_styles/my_prefix_styles.php`.
79+
80+
**Merging existing PHP array files:**
81+
82+
```bash
83+
css2php -m -md ./php_output -mn combined_styles
84+
```
85+
86+
This will merge all PHP files found in the `./php_output` directory and create a merged file named `combined_styles.php` in the `./output` directory.
87+
88+
## Command-Line Arguments
89+
90+
Here is a list of all available command-line arguments, sorted alphabetically:
91+
92+
* `-i`, `--info`:
93+
* **Description:** Show detailed statistics and information after processing each CSS source.
94+
* **Example:** `css2php styles.css -i`
95+
96+
* `-m`, `--merge`:
97+
* **Description:** Enables the merge functionality to combine existing PHP array files.
98+
* **Example:** `css2php -m -md ./php_output -mn combined_styles`
99+
100+
* `-md`, `--merge-dir` `MERGE_DIR`:
101+
* **Description:** Specifies the directory containing PHP files to merge. Defaults to `./output`.
102+
* **Example:** `css2php -m -md ./custom_php_dir -mn merged_styles`
103+
104+
* `-mn`, `--merge-name` `MERGE_NAME`:
105+
* **Description:** Sets the filename prefix for the merged output file. Defaults to `main`.
106+
* **Example:** `css2php -m -md ./php_output -mn all_themes`
107+
108+
* `-mo`, `--merge-output` `MERGE_OUTPUT`:
109+
* **Description:** Specifies the output directory for the merged PHP file. Defaults to `./output`.
110+
* **Example:** `css2php -m -md ./php_output -mo ./merged_output -mn merged_styles`
111+
112+
* `-n`, `--name-prefix` `NAME_PREFIX`:
113+
* **Description:** Sets a prefix for the output filename. Useful for organizing output files.
114+
* **Example:** `css2php styles.css -n theme_` (Output: `output/theme_styles.php`)
115+
116+
* `-o`, `--output` `OUTPUT_DIR`:
117+
* **Description:** Specifies the output directory for the generated PHP files. Defaults to `./output`.
118+
* **Example:** `css2php styles.css -o php_arrays` (Output: `php_arrays/styles.php`)
119+
120+
* `-p`, `--priority-file` `PRIORITY_FILE`:
121+
* **Description:** When merging, this option allows you to specify a priority PHP file. If duplicate classes are found, the properties from the priority file will take precedence.
122+
* **Example:** `css2php -m -md ./php_output -p priority_styles.php -mn merged_styles`
123+
124+
* `-r`, `--no-overwrite`:
125+
* **Description:** Prevents overwriting existing output files. If an output file already exists, the conversion will be skipped, and an error will be raised.
126+
* **Example:** `css2php styles.css -r`
127+
128+
* `-s`, `--skip-errors`:
129+
* **Description:** Instructs CSS2PHP to skip errors encountered during CSS fetching or parsing and continue processing other sources. Warnings will be printed for skipped errors.
130+
* **Example:** `css2php styles.css -s`
131+
132+
* `-sources` `[SOURCES ...]`:
133+
* **Description:** One or more CSS file paths or URLs to convert. This is the primary input for the tool.
134+
* **Example:** `css2php styles.css https://example.com/theme.css`
135+
136+
* `-t`, `--timeout` `TIMEOUT`:
137+
* **Description:** Sets the timeout in seconds for fetching remote CSS files. Defaults to 30 seconds.
138+
* **Example:** `css2php https://slow-server.com/styles.css -t 60`
139+
140+
* `-v`, `--version`:
141+
* **Description:** Displays the current version of CSS2PHP, author information, and the repository link.
142+
* **Example:** `css2php -v`
143+
144+
## Merge Functionality Details
145+
146+
The merge functionality allows you to combine multiple PHP files (previously generated by CSS2PHP) into a single, consolidated PHP array. This is particularly useful when:
147+
148+
* You have styles split across multiple files (e.g., component-based styles).
149+
* You want to combine styles from different themes or modules.
150+
151+
**Key aspects of merging:**
152+
153+
* **Property-Level Merging:** When merging, CSS2PHP performs property-level merging. If the same CSS class exists in multiple input files, the tool will attempt to combine all unique CSS properties for that class into the merged output.
154+
* **"Last File Wins" Conflict Resolution:** In case of property conflicts (i.e., the same CSS property is defined with different values in multiple input files for the same class), the property value from the *last processed file* will take precedence. The processing order is determined by file size (largest to smallest by default), with an option to prioritize a specific file using `--priority-file`.
155+
* **Duplicate Class Detection:** The merge process detects duplicate CSS class names across input files and reports them in the header comment of the merged output file.
156+
* **Priority File:** Using the `--priority-file` option, you can designate a specific PHP file to have priority during merging. If a class is found in the priority file and other files, the properties from the priority file's class will be favored in case of conflicts.
157+
158+
## Reporting and Statistics
159+
160+
CSS2PHP provides detailed reports and statistics for each conversion and merge operation. This information is included as a header comment in the generated PHP files.
161+
162+
**For single CSS file conversion, the report includes:**
163+
164+
* **Source Information:** File path or URL of the processed CSS.
165+
* **Processing Statistics (A-Z):**
166+
* Classes found
167+
* Compression ratio (Output size / Input size)
168+
* Input size (bytes)
169+
* Media queries count
170+
* Output size (bytes)
171+
* Processing time (seconds)
172+
* Pseudo-classes count
173+
* Syntax validation status (Valid/Invalid)
174+
* **Configuration:**
175+
* Parse mode (Advanced - `cssutils`)
176+
* Skip errors (Yes/No)
177+
* Timeout (seconds)
178+
* Overwrite enabled (Yes/No)
179+
* **File Structure Explanation:** Describes the structure of the generated PHP array.
180+
181+
**For merge operations, the report includes:**
182+
183+
* **Merge Information:**
184+
* Source directory
185+
* Files processed count
186+
* Unique classes count in the merged output
187+
* Duplicate classes found count
188+
* Priority file (if used)
189+
* Timestamp of generation
190+
* **Duplicate Information:** Lists all duplicate CSS classes found during merging and the files where they were detected.
191+
192+
## Syntax Validation and Auto-Fix
193+
194+
CSS2PHP validates the generated PHP array code for syntax errors using the `php -l` command.
195+
196+
* **Validation:** After generating the PHP array, the tool runs a PHP syntax check.
197+
* **Auto-Fix:** If syntax errors are detected, CSS2PHP attempts to automatically fix common issues, such as missing commas, extra commas, unescaped characters, and invalid media query keys.
198+
* **Error Reporting:** If auto-fix is successful, a note is included in the output. If errors persist after auto-fix attempts, a warning message is displayed, and the tool will exit with an error code (unless `--skip-errors` is used).
199+
200+
## Contributing
201+
202+
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests on the [GitHub repository](https://github.com/sakibweb/css2php).
203+
204+
## License
205+
206+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
207+
208+
## Author
209+
210+
Created by [Sakib Hossain](https://sakib.io) ([@sakibweb](https://github.com/sakibweb))
211+
212+
[GitHub Repository](https://github.com/sakibweb/css2php)

0 commit comments

Comments
 (0)