Download the PHP package popphp/pop-css without Composer

pop-css

• Overview
• Install
• Quickstart
• Selectors
• Media Queries
• Comments
• Colors
• Parse CSS
• Minify

Overview

pop-css provides the ability to create new CSS files as well as parse existing ones. There is support for a number of CSS-based features such as media queries, comments and even minification.

pop-css is a component of the Pop PHP Framework.

Top

Install

Install pop-css using Composer.

composer require popphp/pop-css

Or, require it in your composer.json file

"require": {
    "popphp/pop-css" : "^3.0.0"
}

pop-css requires PHP 8.4 or newer.

Top

Quickstart

In creating CSS, you will use the main CSS object and create and add selector, media and comment objects to it to build your CSS.

The above code will produce:

Rendering the CSS can happen a number of ways:

Call the render method

Call a string function

Write to file

The main CSS object's constructor is also flexible and other CSS-related objects can be injected into it:

Top

Selectors

The selector object is the main object in which to define the various selectors and add them to the main CSS object. The selector constructor accepts any valid CSS selector.

Selectors render in the order they were added, regardless of whether they're element, ID, or class selectors — mixing selector types renders them in that same insertion order, not grouped by type.

The above code will produce:

Multiple and compound selectors

A selector's constructor accepts any valid CSS selector string as-is, including comma-grouped lists and combinators. isMultipleSelector() and hasDescendant() let you inspect which kind of selector you're holding:

Setting properties three ways

Besides setProperty()/setProperties(), a selector's properties are also reachable as magic properties or via ArrayAccess — all three styles read and write the same underlying properties, so they're interchangeable:

isset($box['color'])/isset($box->color) and unset($box['color'])/unset($box->color) work the same way.

Reading the margin/padding shorthand as longhand

If a margin or padding shorthand property is set, the individual margin-top/-right/-bottom/-left (and the padding-* equivalents) can be read back out even though they were never set explicitly — the shorthand value is split according to CSS's normal 1/2/3/4-value rules:

Setting an explicit margin-top (or any other longhand) takes precedence over the synthesized value.

Reading, checking and removing properties

Tab size

Both Selector and Media accept an optional tab size (in spaces) as a constructor argument, controlling the indentation used when rendering:

Accessing and removing selectors on the main CSS object

Once selectors have been added to the main Css object, they can be looked up, checked for, or removed by name — and the Css object itself supports ArrayAccess, Countable, and iteration:

Adding a selector whose name matches one already present merges its properties into the existing selector (a later value for the same property wins) rather than replacing it outright — the same as how repeated CSS rules for one selector cascade:

Top

Media Queries

Media queries can be created as separate objects that contain their own selector objects. They are then added to the main CSS object.

The above code will produce:

Conditions: not and only

A media query's condition (not or only) can be set via setCondition(), or passed into the constructor:

Building a Media object in one call

Media's constructor accepts the type, a features array, the condition, and the tab size all at once, as an alternative to building it up with separate setFeature()/setCondition() calls:

Reading and removing features

Accessing and removing media queries on the main CSS object

Top

Comments

Comments can be added in a number of places. They can be added to the top of the main CSS content, to the top of a selector or to the top of a media query.

The above code will produce:

Comments can be tailored with the $wrap and $trailingNewLine properties that can be passed into the comment constructor. If the $wrap is set to 0, it will force a single-line comment.

The above code will produce:

Reading and removing comments

Comments can be added to a Css, Media, or Selector object (anything using CommentTrait), and read back or removed the same way on all three:

Top

Colors

Selector properties accept a Pop\Color\Color object anywhere they'd accept a string. The value is normalized to a CSS-valid string at set time — regardless of which color space you build it from, including formats (CMYK, Grayscale, HSV, HSB) that aren't natively CSS syntax on their own.

The above code will produce:

Note that background-color rendered as rgb(...), not raw CMYK numbers — CMYK (and Grayscale) aren't valid CSS color syntax on their own, so they're automatically converted through RGB.

You can also read a property back out as a color object, whether the selector was built manually or produced by parsing an existing CSS file:

getColorProperty() returns null if the property is missing, or if Color::parse() can't make sense of the value at all. Note that Color::parse() has permissive fallback heuristics — any string containing exactly 3 spaces is parsed as CMYK, and any bare numeric string is parsed as Grayscale — so some ordinary non-color values (a 4-value margin/padding shorthand, a bare numeric value like line-height: 1.5) get misidentified as colors rather than returning null. That's popphp/pop-color behavior, not something pop-css filters.

Top

Parse CSS

You can parse CSS with the following methods:

In each case, it will return a CSS object populated with the related CSS objects from the content of the source.

parseFile() throws a Pop\Css\Exception if the given file doesn't exist, and parseUri() throws the same exception if the URI can't be fetched:

Each static method has an equivalent instance method for parsing content into a Css object you already have:

Top

Minify

Setting the minify property on the main CSS object will perform a basic minification of the CSS content.

The above code will produce:

Top